Sync your catalogue

Your catalogue is the list of items your own system sells — dishes, tickets, sessions, products — as Localoy knows them. Each item is keyed by your ID, the externalId, so you never have to store Localoy's IDs.

The catalogue does two things:

1. It links your items to your Localoy listings. Link an item to one of your bookables with localoyRef, and Localoy asks your system about that item before accepting a booking. See Live inventory checks.
2. It keeps a record of changes. Every create, update and delete sends a catalog.item.* webhook to your endpoints, so other systems of yours can follow along.

Scopes you need#

Create or replace an item#

POST /catalog/items is an upsert keyed on externalId: the first call creates the item and answers 201; later calls update it and answer 200.

curl -X POST "$LOCALOY_BASE_URL/catalog/items" \
  -H "Authorization: Bearer $LOCALOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "sku-4471",
    "name": "Kacchi Biryani (full)",
    "description": "Mutton kacchi with borhani",
    "priceCents": 45000,
    "currency": "BDT",
    "available": true,
    "stock": 12,
    "metadata": { "posCategory": "mains" }
  }'

Choosing externalId#

Use the ID your own system already has — a SKU, a product ID, a menu item code. It must be 1–128 characters, start with a letter or digit, and contain only letters, digits, ., _, : and -. It cannot be changed later; to rename, delete the item and create it again.

Stock and availability#

These values are stored as a snapshot. When a customer books a linked item, Localoy does not read them — it asks your inventory endpoint live. See Live inventory checks.

Link an item to a Localoy listing#

1. List what you can link to with GET /bookables. It returns every ticket option, activity item and dining reservation of yours, each with a type and an id.

   Response · 200Copy

   {
     "success": true,
     "data": {
       "items": [
         { "type": "event_ticket", "id": "cm4t1ck3t0pt10n00000001", "name": "VIP", "experienceId": "cm4ev3nt000000000000001", "experienceName": "Jazz Night" },
         { "type": "dining", "id": "cm4d1n1ng00000000000001", "name": "Table reservation", "experienceId": "cm4d1n1ng00000000000001", "experienceName": "Sultan's Dine" }
       ]
     }
   }

2. Set localoyRef on the item that stands for it:

   cURLCopy

   curl -X PATCH "$LOCALOY_BASE_URL/catalog/items/table-booking" \
     -H "Authorization: Bearer $LOCALOY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "localoyRef": { "type": "dining", "id": "cm4d1n1ng00000000000001" } }'

A bookable can be linked to one item at a time. Linking a second item answers 409 open_network_bookable_already_linked; unlink the first by setting its localoyRef to null.

Keep it in sync#

• Send a write whenever an item changes in your system, rather than re-sending everything on a timer.
• Use PATCH to change a few fields — for example only stock.
• Use DELETE when you stop selling an item. Deletion is permanent.
• To reconcile, page through GET /catalog/items with limit and offset and compare with your own records.

Items managed by an integration#

Some items in your catalogue can be written for you by an integration you connect in the Partner Portal. Each such item carries a managedBy object naming the integration; items you create with your own key have managedBy: null.

Your key sees these items and can edit them like any other. The integration keeps writing them, though, so change them at their source:

• A Technology Provider writes its items from its own system, and its next write can overwrite your edit. When you disconnect the provider, the items it created are removed.
• A WooCommerce store is read every hour. Localoy mirrors your published products as items with externalId woocommerce:{productId}, and never writes to your store. The next sync overwrites the fields that come from WooCommerce, so change them in WooCommerce instead.