The catalog item
One object, used by all five catalogue endpoints. A create needs two fields; everything else takes a default.
Fields
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
externalId | string | Required | — | Your system's own id for the item, and the id every later call addresses it by. 1–128 characters, starting with a letter or digit, then letters, digits, dots, colons, dashes and underscores — it appears in a URL, so nothing that would need escaping. Immutable once created. |
name | string | Required | — | What the item is called. At most 120 characters. |
description | string | null | Optional | null | At most 2,000 characters. Send null to clear it. |
priceCents | integer | Optional | 0 | Minor units — 45000 is BDT 450.00. An integer, never a decimal, so money never touches floating point. Between 0 and 2,147,483,647. |
currency | string | Optional | "BDT" | A three-letter ISO-4217 code. Lower case is accepted and stored upper case; anything that is not three letters is a 400. |
available | boolean | Optional | true | Whether the item can be bought or booked right now. This is the flag to use for a temporary stop, rather than deleting the item. |
stock | integer | null | Optional | null | null and 0 mean different things and are both kept: null is 'this item does not track stock', 0 is 'it tracks stock and there is none left'. Between 0 and 1,000,000,000. |
metadata | object | null | Optional | null | Anything your system carries that Localoy has no column for. Stored and returned untouched — never read, never validated beyond being a JSON object that serializes to at most 16 KB. Must be an object: an array or a bare string is a 400. |
localoyRef | object | null | Optional | null | The Localoy bookable this item stands for — { "type": "event_ticket" | "activity_item" | "dining", "id": "<an id from GET /bookables>" }. Once linked, and once your live inventory endpoint is switched on, Localoy asks your system before booking it. One item per bookable: linking a second is a 409 (open_network_bookable_already_linked), and an id that is not yours is a 404 (open_network_bookable_not_found). Send null to unlink. |
Absent is not the same as null
On a PATCH, leaving a key out of the body keeps the stored value; sending it as null clears it. That distinction is the only way to remove a description or a stock count, so the two are never treated as the same thing. The same applies to stock in a different sense: null means the item does not track stock, and 0 means it does and there is none left.