Acting for partners

Once a partner is connected, you call the endpoints of the Open Network API for it: your key in Authorization, and its partnerId in X-Localoy-Partner-Id. Fields, rules and errors are the ones documented there. This page covers what is different when a provider calls them.

curl "$LOCALOY_BASE_URL/catalog/items" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY" \
  -H "X-Localoy-Partner-Id: $LOCALOY_PARTNER_ID"

Catalogue items you manage#

The items you create for a partner belong to your connection with it:

• You see only your items. GET /catalog/items lists only the items you created for that partner. Reading, updating or deleting any other externalId answers 404 open_network_item_not_found.
• Your items are marked. Each carries managedBy, naming you, so the partner can tell your items from its own.
• You cannot take over an externalId. Creating an item with an externalId that the partner or another integration already uses answers 409 open_network_item_managed_elsewhere. Nobody else's item is overwritten.
• Disconnecting removes them. When the partner disconnects you, every item you created for it is deleted. connection.revoked says how many.

{
  "id": "cm1q2w3e4r5t6y7u8i9o0p1b3",
  "externalId": "example-pos:4471",
  "name": "Kacchi Biryani (full)",
  "description": null,
  "priceCents": 45000,
  "currency": "BDT",
  "available": true,
  "stock": 12,
  "metadata": null,
  "localoyRef": { "type": "dining", "id": "cm4d1n1ng00000000000001" },
  "managedBy": { "type": "TECHNOLOGY_PROVIDER", "key": "example-pos", "name": "Example POS" },
  "createdAt": "2026-09-27T09:16:48.201Z",
  "updatedAt": "2026-09-27T09:16:48.201Z"
}

Choose externalIds that cannot collide with the partner's own — prefix them with your product's name, as in example-pos:4471. An externalId is unique within one partner's catalogue, so you can use the same ID for two partners.

The partner's own API key can still read and change the items you manage. Treat Localoy's copy as a mirror of your system: write when your data changes, and reconcile by paging through GET /catalog/items.

Bookables and linking#

GET /bookables lists only the partner's bookables in your modules:

Linking an item to a bookable outside your modules answers 404 open_network_bookable_not_found, as for a bookable that does not exist. A bookable can be linked to one item at a time — yours, the partner's or another integration's — so linking one that is taken answers 409 open_network_bookable_already_linked.

Linking an item is what makes Localoy ask an inventory endpoint before it accepts a booking of that bookable. The endpoint it asks is the partner's — see Settings each partner saves.

Payments#

With PAYMENT, you take payments for the partner's bookings through your own checkout, exactly as in Accept payments — read the session, charge, report the result, record refunds — with the partner header on every call.

• Modules. A session for an order outside your modules answers 404 payment_session_not_found, like a session that does not exist.
• Environments. A key sees only the sessions of its own environment. Real orders open their sessions in production.
• Customer data. A session carries the customer's name, phone and email. PAYMENT is one of the two scopes that share personal data, and its consent text tells the partner so.

Settings each partner saves#

In this release, two settings that point Localoy at your system are saved by the partner in its Partner Portal. You cannot set them through the API.

Neither the checkout redirect nor the inventory check names the partner, so the URL itself must. Give each partner its own URLs, with a query parameter that identifies it:

https://pay.example.com/localoy/checkout?account=acct_4471
https://pos.example.com/localoy/inventory?account=acct_4471

Localoy keeps the query string you give it. It appends session_id to the checkout URL, and adds external_id, quantity, module and, when the booking has a date or time, at to the inventory endpoint's. Show each partner its URLs in your product, ready to paste, and tell it to enable its production checkout — a production checkout is off until the partner switches it on, which needs Partner+.

The rules for each are in Accept payments and Live inventory checks.

The inventory signing secret#

Inventory checks are signed with the partner's inventory secret, invsec_… — one for each environment — not with anything of yours. The partner reveals it on Open Network → Inventory and hands it to you.

• Store it per partner, and verify each check with the secret of the partner that its URL names.
• When the partner rotates the secret, the old one stops at once, so the partner must give you the new one.
• Verify and answer exactly as in Live inventory checks, within 1.5 seconds.

Rate limits for each partner#

Each partner has its own budget: 240 requests per 15 minutes for your key and that partner, within 12,000 per 15 minutes for your key overall. A heavy sync for one partner cannot starve the others. See Limits.

The partner sees your calls#

Every call you make for a partner appears on its Open Network → Activity page, under your name.