Create or replace an item

Create a catalogue item, or update the item that already has this externalId.

POST{BASE_URL}/catalog/items

Creates an item, or — when an item with this externalId already exists — updates it. Requires the REGISTRATION scope.

Important

On an existing item only the fields you send are changed. Fields you leave out keep their stored values; they are not reset to defaults.

Body

externalIdstringrequired: Your ID for the item. 1–128 characters; starts with a letter or digit; then letters, digits, ., _, : or -.
namestringrequired: Up to 120 characters.
descriptionstring | nulloptional: Up to 2,000 characters. An empty string is stored as null.
priceCentsintegeroptional: Minor units, 0 to 2,147,483,647. Defaults to 0 on create.
currencystringoptional: A three-letter ISO 4217 code, any case. Defaults to BDT on create.
availablebooleanoptional: Defaults to true on create.
stockinteger | nulloptional: 0 to 1,000,000,000, or null for untracked. Defaults to null on create.
metadataobject | nulloptional: A JSON object of your own data, at most 16,384 bytes when serialized. Not an array.
localoyRefobject | nulloptional: { "type", "id" } linking the item to one of your bookables; null unlinks. type is event_ticket, activity_item or dining.

Response

dataobjectrequired: The catalogue item.

Status codes#

Status	Code	Meaning
`201`	—	The item was created.
`200`	—	The item existed and was updated.
`400`	—	A field is invalid; `message` names it.
`404`	`open_network_bookable_not_found`	`localoyRef.id` is not one of your bookables.
`409`	`open_network_bookable_already_linked`	Another of your items is linked to that bookable.

Side effects#

Sends catalog.item.created (on 201) or catalog.item.updated (on 200) to your webhook endpoints of the key's environment.

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)",
    "priceCents": 45000,
    "stock": 12
  }'

Response · 201

{
  "success": true,
  "message": "Catalog item created",
  "data": {
    "id": "cm1q2w3e4r5t6y7u8i9o0p1a2",
    "externalId": "sku-4471",
    "name": "Kacchi Biryani (full)",
    "description": null,
    "priceCents": 45000,
    "currency": "BDT",
    "available": true,
    "stock": 12,
    "metadata": null,
    "localoyRef": null,
    "managedBy": null,
    "createdAt": "2026-09-26T08:15:30.123Z",
    "updatedAt": "2026-09-26T08:15:30.123Z"
  }
}