Connect your POS to ala.menu

1. 1

   You get a key

   We issue one secret key per menu. Send it on every request as Authorization: Bearer pos_YOURMENU_xxxx. Keep it on your server. If it leaks, tell us and we issue a new one.

2. 2

   You send items by their own id

   Every item carries an externalId: a barcode, or any string from your system that identifies the item and never changes. One externalId is one item on the menu. You never need to know our item ids.

3. 3

   You send only what changed, whenever it changes

   A price change is one small call with one item and one field. Fields you leave out are left alone. Items you leave out are left alone. Wire this to whatever event your system already fires.

4. 4

   On a schedule you choose, you send everything

   One call with your entire active catalog. It is the safety net. Anything a delta missed, dropped or got wrong corrects itself at the next full sync. The gap between full syncs is the longest a missed change can stay wrong, so pick the window you can live with. Most integrations run it daily, and a quiet hour works well.

Three calls. Replace pos_YOURMENU_xxxx with the key we gave you and paste each block into a terminal.

1. Check the key

curl https://ala.menu/api/pos/v1/ping \
  -H "Authorization: Bearer pos_YOURMENU_xxxx"

{
  "ok": true,
  "menu": "Pegasus Pet Center",
  "currency": "USD"
}

If the menu name and the currency are the ones you expect, the key is in the right environment.

2. See what we already hold

curl https://ala.menu/api/pos/v1/catalog \
  -H "Authorization: Bearer pos_YOURMENU_xxxx"

{
  "ok": true,
  "currency": "USD",
  "items": [
    {
      "externalId": "9003579311776",
      "name": "RC Wet Sterilised Jelly 85g",
      "price": 4.5,
      "inStock": true,
      "hidden": false,
      "hasImage": true,
      "brand": "Royal Canin",
      "size": "85g",
      "barcode": "9003579311776"
    },
    {
      "externalId": "9003579311714",
      "name": "RC Kitten Dry 2kg",
      "price": 28,
      "inStock": false,
      "hidden": false,
      "hasImage": false,
      "brand": "Royal Canin",
      "size": "2kg"
    }
  ]
}

This is the menu as customers see it, listed by your own ids. Use it to check that your ids match ours before you write anything.

3. Send your first change

One price change and one item going out of stock, in one call.

curl -X POST https://ala.menu/api/pos/v1/sync \
  -H "Authorization: Bearer pos_YOURMENU_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "delta",
    "currency": "USD",
    "items": [
      { "externalId": "9003579311776", "price": 5.0 },
      { "externalId": "9003579311714", "quantity": 0 }
    ]
  }'

{
  "ok": true,
  "received": 2,
  "updated": 2,
  "created": 0,
  "staged": 0,
  "unchanged": 0,
  "hidden": 0,
  "unhidden": 0,
  "rejected": []
}

Open the menu and the new price is there. Run the same call again and the response comes back with unchanged: 2, because nothing moved the second time.

Base URL https://ala.menu/api/pos/v1. Every endpoint needs the same header: Authorization: Bearer pos_YOURMENU_xxxx. Responses are JSON.

Confirms your key works and tells you which menu it is tied to.

{
  "ok": true,
  "menu": "Pegasus Pet Center",
  "currency": "USD"
}

Errors: the shared ones below. There is nothing else this call can get wrong.

Returns every item on the menu that is linked to one of your external ids, in the state customers see it.

{
  "ok": true,
  "currency": "USD",
  "items": [
    {
      "externalId": "9003579311776",
      "name": "RC Wet Sterilised Jelly 85g",
      "price": 4.5,
      "inStock": true,
      "hidden": false,
      "hasImage": true,
      "brand": "Royal Canin",
      "size": "85g",
      "barcode": "9003579311776"
    },
    {
      "externalId": "9003579311714",
      "name": "RC Kitten Dry 2kg",
      "price": 28,
      "inStock": false,
      "hidden": false,
      "hasImage": false,
      "brand": "Royal Canin",
      "size": "2kg"
    }
  ]
}

One thing to note. Items the menu owner created by hand are not in this list, because they are not linked to your system.

The retail facets come back here too, so anything you push you can read back and check against your own records. When your externalId is not the barcode, barcode is the column to match your rows on.

Errors: the shared ones below.

Sends a batch of items. This is the endpoint the whole integration hangs off, and it has two modes.

Request fields

Item fields

Only externalId is required. Everything else is optional, and leaving a field out means "do not change this".

mode: "delta", the everyday call

When to use it: every time something changes in your system. A price edit, a stock movement, a new product, a discontinued line. This is the normal path and it is what makes the menu update within seconds.

A delta carries only the items that changed, and inside each item only the fields that changed. Items you do not mention are untouched.

{
  "mode": "delta",
  "currency": "USD",
  "items": [
    { "externalId": "9003579311776", "price": 5.0 },
    { "externalId": "9003579311714", "quantity": 0 },
    { "externalId": "9003579311888", "status": "idle" },
    {
      "externalId": "6191544800014",
      "name": "New Product",
      "price": 12.0,
      "quantity": 20,
      "category": { "id": "17", "name": "Dog Food" },
      "brand": "Royal Canin",
      "size": "2kg"
    }
  ]
}

{
  "ok": true,
  "received": 4,
  "updated": 3,
  "created": 1,
  "staged": 0,
  "unchanged": 0,
  "hidden": 1,
  "unhidden": 0,
  "rejected": []
}

Three existing items moved (a price, a stock count, one going idle) and one unknown id created a new item. The idle one counts in both updated and hidden, because it changed and it left the menu in the same call.

mode: "full", the full sync

When to use it: on a schedule you choose, carrying your entire active catalog. How often is your call: the gap between full syncs is the longest anything a delta missed can stay wrong. Most integrations run it daily. It is a safety net, not a way to make routine updates. Do not use it to push a single price change.

Same payload shape. We reconcile everything against it: values that drifted are corrected, and linked items that are not in the snapshot are hidden. Nothing is deleted, and an item that shows up again in a later snapshot comes back on its own.

{
  "mode": "full",
  "currency": "USD",
  "items": [
    {
      "externalId": "9003579311776",
      "name": "RC Wet Sterilised Jelly 85g",
      "price": 5.0,
      "quantity": 42,
      "category": { "id": "17", "name": "Dog Food" }
    },
    {
      "externalId": "9003579311714",
      "name": "RC Kitten Dry 2kg",
      "price": 28.0,
      "quantity": 0,
      "category": { "id": "18", "name": "Cat Food" }
    }
  ]
}

A full snapshot that leaves out too much of the catalog is refused. See suspect_snapshot in the errors below.

Response counters

The response tells you exactly what happened. Every call returns all eight fields, including the zeros.

created, updated, staged, unchanged and the length of rejected add up to received. hidden and unhidden count something else: they overlap with updated, and a full snapshot can hide items you did not mention at all.

Two kinds of failure

Some problems are about one row, and some are about the whole payload. They are answered differently on purpose.

One row is wrong. You get HTTP 200. The rest of the batch lands and the bad rows come back in rejected. A single malformed product must never strand a full sync.

{
  "ok": true,
  "received": 3,
  "updated": 2,
  "created": 0,
  "staged": 0,
  "unchanged": 0,
  "hidden": 0,
  "unhidden": 0,
  "rejected": [
    { "externalId": "6191544800014", "reason": "missing_price" }
  ]
}

The payload is wrong. You get HTTP 422 and nothing at all is written. Accepting half of a payload with the wrong currency in it would be worse than accepting none of it.

{ "ok": false, "error": "currency_mismatch" }

Whole-call errors, HTTP 422

Nothing was written. Fix the payload and resend.

Per-item reasons, inside rejected

These come back with HTTP 200. The rest of the batch landed.

Sends one photo for one item. The image file is the raw request body, not a form field and not JSON.

curl -X POST https://ala.menu/api/pos/v1/items/9003579311776/image \
  -H "Authorization: Bearer pos_YOURMENU_xxxx" \
  -H "Content-Type: image/jpeg" \
  --data-binary @product.jpg

{
  "ok": true,
  "imageUrl": "https://firebasestorage.googleapis.com/...jpg?alt=media&token=...",
  "applied": true
}

We resize the photo to fit within 1600 by 1600 and store it as a JPEG at its own permanent URL. Nothing is ever overwritten, so a new upload is always a new URL.

applied tells you whether your photo is the one customers now see. It comes back false when the menu owner has set their own photo for that item: yours is stored, theirs keeps showing. That is not an error and there is nothing to retry.

Errors always come back as { "ok": false, "error": "..." }. The error string is stable, so it is safe to log it and to branch on it.

These are the reasons you can wire this up without a rollback plan. None of them depend on your code being careful.

• A field you leave out changes nothing

  Absent means "no change", never "clear this". Sending only externalId and price touches the price and nothing else.

• An explicit null clears the field

  Only category, imageUrl, brand, size and barcode can be cleared that way. A null name or price is a bug in the caller, not an instruction, so that row is rejected and the item keeps what it had.

• Resending is always harmless

  Every call is idempotent. If a request times out and you do not know whether it landed, send it again. A repeat that changes nothing counts as unchanged and does not even touch the menu.

• Nothing is ever deleted

  There is no delete in this API. An item you stop sending, or mark idle, is hidden. Its history, its photos and the owner edits on it all stay. Include it in a full sync again and it comes back on its own.

• A broken export cannot wipe the menu

  A full snapshot missing a large share of the catalog is refused as suspect_snapshot and changes nothing. A half-written export file cannot empty a menu.

• Quantity zero sells out, above zero brings back

  Stock is a fact you own. Zero shows the item as sold out and blocks it at checkout, anything above zero restores it. If you never send quantity, we leave the sold-out switch the owner set by hand exactly as it is.

• Presentation is not yours to break

  Layout, descriptions, section order and design are managed on the menu side. Your calls cannot reorder, rename or remove anything you were not talking about. If an owner has edited a name, a price or a photo by hand, that edit stays on top and your value is kept underneath.