Partner Sync API

Concretely, that means three things:

• A stock sync SETS an absolute on-hand figure. It never applies a change. Re-sending the same payload does nothing; a payload you dropped is corrected by the next one. There is no ordering requirement between pages and no reconciliation protocol to implement.
• Stockwaka holds only a short reservation window against your figure while a shopper pays — never a parallel count. See Reservations, below.
• Stockwaka orders are requests you accept, not deductions imposed on you. You take an order in, acknowledge it, and your next sync carries the consequence back to us as an ordinary absolute count.

If you are ever tempted to send us what changed since last time, send the current count instead. The API rejects a negative quantity for exactly this reason.

There is no self-service signup. A partner integration is set up with a person, because binding your store codes to the right shops is a decision nobody should make by guessing.

1. 1Get in touch. Email support@bitasei.com with your company, roughly how many stores you run, and which system will be talking to us (SAP, Odoo, Microsoft Dynamics, an in-house ERP — it makes no difference to the API, but it tells us who to put you with).
2. 2A short technical call. We agree which stores go live first, and which scopes each of your jobs needs.
3. 3Your account and your stores are set up. One Stockwaka account for the chain, with one shop under it per store — created and named from your own store list, however many that is. If some of your branches already use Stockwaka on WhatsApp, nothing about their accounts changes.
4. 4We issue your test key. It arrives once, over a secure channel, and starts with swp_test_. Stockwaka stores only a hash of it, so it can never be shown again — a lost key is replaced, not recovered.
5. 5You build against the sandbox using the reference below. Start with GET /partner/whoami; if that returns your business name, everything else is downhill.
6. 6Bind your store codes with PUT /partner/stores/:code, once per store. The call is idempotent, so it belongs in your deploy script rather than in a runbook.
7. 7Pilot on a handful of real stores. We watch the first syncs together — the two numbers that matter early are unpricedCount and skipped, which between them tell you whether your export is mapping cleanly.
8. 8Go live. We issue the production key (swp_live_) and you bring stores on as fast as you like. Nothing is all-or-nothing: a store whose code you have not bound yet is simply not synced, and binding it later needs no change on our side.

Send your key as a bearer token on every request.

Authorization: Bearer swp_live_...

A key looks like swp_<env>_<43 characters>, where env is live or test. The environment is part of the key so a test credential pasted into a production config is visibly wrong before it is used.

Scopes

Ask for the narrowest set each job needs. Your nightly stock push has no business reading your customers’ phone numbers.

GET /partner/whoami needs no scope at all — it is how you find out what you hold.

What a key can reach

Failures

A 403 never means “rotate your key”. Read the message — it names the scope you are short of.

Stockwaka calls a shop a branch. You call it a store, with your own code (SW-IKJ-01). Binding the two is a one-time setup step per store.

Lists every shop on the account, including ones you have not bound yet.

[
  { "storeCode": "SW-MAIN",   "branchId": "primary",                  "name": "Lekki",         "isPrimary": true,  "isActive": true },
  { "storeCode": "SW-IKJ-01", "branchId": "66f1a0c2e4b0a1d2c3e4f5b1", "name": "Ikeja",         "isPrimary": false, "isActive": true },
  { "storeCode": null,        "branchId": "66f1a0c2e4b0a1d2c3e4f5b2", "name": "Yaba",          "isPrimary": false, "isActive": true }
]

branchId is opaque. One shop on every account is the main shop, and its branchId is the literal string "primary" rather than an id. That is not a placeholder — it is a real, permanent handle you can use anywhere a branchId is accepted.

Binds your store code to one shop. Idempotent — safe to run on every deploy.

# by the id from GET /partner/stores  (recommended for scripts)
curl -X PUT "$BASE/partner/stores/SW-IKJ-01" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"branchId": "66f1a0c2e4b0a1d2c3e4f5b1"}'

# the main shop
curl -X PUT "$BASE/partner/stores/SW-MAIN" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"branchId": "primary"}'

# by name — convenient by hand; refused if it matches more than one shop
curl -X PUT "$BASE/partner/stores/SW-YAB-01" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"branchName": "Yaba"}'

A code already bound to a different shop on the same account returns 409 and names the shop holding it. Re-bind that one first.

The main endpoint. An absolute per-store upsert.

curl -X POST "$BASE/partner/stock/sync" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storeCode": "SW-IKJ-01",
    "items": [
      { "externalRef": "SKU-88213", "name": "Amlodipine 5mg 30s", "quantity": 42,
        "sellingPrice": 2400, "costPrice": 1800, "barcode": "6154001234567",
        "unit": "pack", "category": "Medicines" },
      { "externalRef": "SKU-88214", "quantity": 0 }
    ]
  }'

{
  "storeCode": "SW-IKJ-01",
  "branch": "Ikeja",
  "total": 2, "created": 0, "updated": 2, "skipped": 0,
  "unpricedCount": 0,
  "skippedSamples": [],
  "warnings": [],
  "photosQueued": 0,
  "reserved": 3,
  "sellable": 39,
  "syncedAt": "2026-08-18T09:00:00.000Z"
}

Item fields

Any field we do not recognise is ignored, not rejected — adding a column to your export will never break the integration. A field you omit always means “leave what Stockwaka holds alone”; it never means “clear it”.

externalRef is the join key

Send your own stable SKU on every line. Stockwaka matches an incoming row against the catalogue in this order: externalRef, then barcode, then the product name.

Matching on name alone is fragile. The first time you correct a product’s description, a name-matched sync would create a second row and split that product’s stock across both. A SKU cannot do that.

{ "storeCode": "SW-IKJ-01", "items": [{ "externalRef": "SKU-88213", "quantity": 17 }] }

Absolute, not delta

• Sending the same payload twice leaves the quantity unchanged. Retry freely.
• A lower number is applied as-is. It is a count, not an increment.
• quantity: 0 is how you say “none left” for counted stock. There is deliberately no delete: a zeroed product keeps its price, barcode and SKU, so restocking it later is one more sync rather than a re-setup. A made-to-order dish has no count — take it off sale with soldOut instead.
• A negative quantity is rejected for the whole request, with nothing written, because it is evidence the payload is deltas — in which case every other row in it is wrong too.

Response fields worth alerting on

Partial success

Individual bad rows are skipped, counted and reported — they never fail the batch. A contract error rejects the whole request and writes nothing, because it means the payload as a whole cannot be trusted: no storeCode, items not a list, over the size cap, a negative or non-numeric quantity, a stockMode other than tracked or made_to_order, or a soldOut / soldOutUntil that cannot be read. The last two are contract errors on purpose: a mis-mapped availability column would otherwise take every dish on, or off, every menu at once.

A restaurant, a bakery or a juice bar sells what it makes. A large pepperoni has no on-hand count, so the counted model does not fit it. Send those products as made_to_order, through the same POST /partner/stock/sync. Your POS stays the master of the menu exactly as an ERP is the master of a count: each dish is stated in full on every sync, and nothing is merged or inferred from a row you did not send.

stockMode

• Send it on every row. A product sent without it keeps the mode it already has, and a new one takes the account’s default — made-to-order for a food business, counted for a shop. A menu that mixes dishes and bottled drinks needs you to say which is which.
• Changing it converts the product. A dish converted to tracked takes the quantity on the same row.
• quantity is ignored for a made_to_order product — including 0.

Taking a dish off the menu

{ "storeCode": "PZ-IKJ", "items": [
  { "externalRef": "PIZ-PEP-L", "soldOut": true },
  { "externalRef": "PIZ-MAR-L", "soldOutUntil": "2026-09-15T10:00:00Z" },
  { "externalRef": "PIZ-BBQ-L", "soldOut": false }
] }

• soldOut: true with no soldOutUntil is until further notice. It does not clear at midnight: your system is the master of availability, so the dish stays off until you send soldOut: false.
• soldOutUntil takes the dish off until that moment; it comes back on sale by itself, with no further call.
• A row that carries neither leaves availability exactly as it is — a price-only sync never puts a sold-out dish back on.
• To remove a dish for good, send it with soldOut: true. Removal is never inferred from a dish missing from a page: pages are independent, so a row you did not send cannot mean “deleted”.
• soldOut on a tracked product is ignored and reported in warnings.

This is also the fast path for taking a dish off mid-service: a one-row sync, applied at once to the storefront and to every counter terminal in that store.

Option groups

{
  "externalRef": "PIZ-PEP-L",
  "name": "Pepperoni Pizza (Large)",
  "stockMode": "made_to_order",
  "sellingPrice": 12000,
  "category": "Pizzas",
  "modifierGroups": [
    { "name": "Crust", "required": true,
      "options": [
        { "label": "Classic", "externalRef": "MOD-CR-CL" },
        { "label": "Stuffed crust", "priceDelta": 1500, "externalRef": "MOD-CR-ST" }
      ] },
    { "name": "Extra toppings", "maxSelect": 3,
      "options": [
        { "label": "Mushroom", "priceDelta": 500, "externalRef": "MOD-TP-MU" },
        { "label": "Jalapeño", "priceDelta": 500, "externalRef": "MOD-TP-JA" }
      ] }
  ]
}

• The list is the dish’s complete set, and it replaces what the dish had. A group you stop sending is deleted; "modifierGroups": [] removes them all. A row with no modifierGroups key leaves them alone.
• Sizes are products, not options. Send Small, Medium and Large as three products with three SKUs; the storefront groups them into one size picker, and each size keeps its own price, options and availability.
• An option can only add to the price. A cheaper version of a dish is its own product at its own price.
• A malformed group refuses the whole row (reported in skippedSamples) and nothing from that row is written — not even its price, which may have moved into the options.
• A dish with a required choice cannot be added by a voice order without the choice: the shopper is sent to the typed flow, which asks.

Photos and descriptions

• imageUrl is fetched in the background, after the page has been written; photosQueued says how many. A link is fetched once — re-sending the same link downloads nothing. To replace a photo, send a new link (a new file name, or ?v=2).
• A photo that could not be fetched is asked for again on your next sync. GET /partner/stock returns the photo shoppers actually see in imageUrl; null means none has arrived yet.
• If the merchant replaces a photo you sent, your next sync restores yours.
• description is shopper-facing copy for the photo menu, kept to 280 characters. Omit it to leave the stored text alone.

What Stockwaka currently holds, for reconciliation.

curl "$BASE/partner/stock?storeCode=SW-IKJ-01&limit=200" \
  -H "Authorization: Bearer $KEY"

{
  "items": [
    {
      "externalRef": "SKU-88213",
      "name": "Amlodipine 5mg 30s",
      "storeCode": "SW-IKJ-01",
      "branchId": "66f1a0c2e4b0a1d2c3e4f5b1",
      "stockMode": "tracked",
      "quantity": 42, "reserved": 3, "available": 39,
      "soldOut": false, "soldOutUntil": null,
      "sellingPrice": 2400, "costPrice": 1800,
      "barcode": "6154001234567", "unit": "pack", "category": "Medicines",
      "description": null, "imageUrl": null, "modifierGroups": [],
      "updatedAt": "2026-08-18T09:00:00.000Z"
    }
  ],
  "nextCursor": "66f1a0c2e4b0a1d2c3e4f5c9"
}

• quantity, reserved and available are null for a made-to-order dish — it has no count, and a 0 would read as “none left”.
• soldOutUntil is null while a dish is on sale, and also while it is off until further notice.
• modifierGroups come back in the shape you send them, with minSelect resolved (1 for a plain required group).
• imageUrl is Stockwaka’s stored copy of the photo, never the link you sent.

Page until nextCursor is null. An item present here but absent from your system is usually one the merchant added themselves on WhatsApp — it will have externalRef: null.

This is the one place your count and ours legitimately differ, and the reserved and sellable fields exist to explain it.

When a shopper places an order, Stockwaka reserves the units for a short window — 15 minutes, extended to at most 24 hours once they say they have paid — so two shoppers cannot buy the same last pack. Nothing is deducted: the units are still on your shelf and still in your count.

your on-hand:  42        (what you sent)
reserved:       3        (held by open orders)
sellable:      39        (what a shopper can order right now)

A reservation survives your sync. If you push quantity: 20 while three units are reserved, the result is 20 on hand with 3 still held and 17 sellable. Your figure is authoritative for on-hand; the reservation is ours.

Reservations release automatically when an order is confirmed, cancelled or expires. The only lasting effect on your side is the confirmed sale, which appears as an order in the pull below.

A change feed, ordered by when each order last changed. Poll it with the cursor you last received.

# first ever pull
curl "$BASE/partner/orders?limit=100" -H "Authorization: Bearer $KEY"

# every pull after that
curl "$BASE/partner/orders?limit=100&cursor=$CURSOR" -H "Authorization: Bearer $KEY"

{
  "orders": [
    {
      "reference": "7QM4P2",
      "status": "preparing",
      "storeCode": "PZ-IKJ",
      "branchId": "66f1a0c2e4b0a1d2c3e4f5b1",
      "customerName": "Mrs Adebayo",
      "customerPhone": "2348012345678",
      "customerNote": "12 Allen Avenue, opposite GTBank",
      "fulfillmentType": "delivery",
      "deliveryLocation": { "latitude": 6.6018, "longitude": 3.3515 },
      "items": [
        { "externalRef": "PIZ-PEP-L", "name": "Pepperoni Pizza (Large)",
          "quantity": 2, "unit": null, "unitPrice": 12000, "lineTotal": 28000,
          "modifiers": [
            { "group": "Crust", "label": "Stuffed crust", "priceDelta": 1500, "externalRef": "MOD-CR-ST" },
            { "group": "Extra toppings", "label": "Mushroom", "priceDelta": 500, "externalRef": "MOD-TP-MU" }
          ] }
      ],
      "totalAmount": 28000, "taxAmount": 0,
      "deliveryFee": 1500, "deliveryFeeOnArrival": false, "payableAmount": 29500,
      "placedAt": "2026-08-18T08:41:00.000Z",
      "confirmedAt": "2026-08-18T08:43:00.000Z",
      "preparingAt": "2026-08-18T08:44:00.000Z", "readyAt": null,
      "fulfilledAt": null, "cancelledAt": null,
      "createdAt": "2026-08-18T08:39:00.000Z",
      "updatedAt": "2026-08-18T08:44:00.000Z",
      "ackedAt": null, "externalOrderId": null
    }
  ],
  "nextCursor": "2026-08-18T08:44:00.000Z|66f1a0c2e4b0a1d2c3e4f5d3"
}

Because this is a change feed, an order you have already seen reappears when its status changes. That is the point: you never miss a confirmation or a cancellation.

Order statuses

Draft carts are never published. Take in any paid status you have not seen — not only confirmed. A kitchen’s till moves an order to preparing or ready within a minute of payment, so a feed polled every few minutes often meets it there first.

Order fields

• fulfillmentType is pickup, delivery or dine_in. For a delivery the address is in customerNote; for dine-in, the table.
• deliveryLocation is the exact point a delivery goes when the shopper shared a location pin, as named latitude and longitude. null for pickup, dine-in and typed addresses.
• unitPrice is the base price per unit, before options. lineTotal is (unitPrice + Σ modifiers[].priceDelta) × quantity — options are priced per unit.
• modifiers[].externalRef is the option code you sent on a sync, frozen when the shopper chose it; null for an option the merchant set up on WhatsApp.
• totalAmount is the goods — what to take in as the sale. deliveryFee sits beside it, never inside it; deliveryFeeOnArrival is true when the rider collects that fee. payableAmount is what the shopper actually paid at checkout. Every money figure is in the shop’s own currency, in whole units.
• preparingAt and readyAt stamp the kitchen states, for ticket times.
• items[].note is the shopper’s instruction for that line — “no onions” — and kitchenNote their note for the whole order. Both are null when empty; print them on the ticket. A fixed choice (“Pepper: Normal / Extra”) belongs in modifierGroups with priceDelta: 0, which carries your option code.
• Line items carry externalRef where we know it. It is null for a product the merchant added themselves on WhatsApp — we will not invent a SKU your system has never issued.

An order you have already taken in can come back with more than a new status: when a payment confirms automatically, the shopper may choose pickup or delivery a moment later. Update the order you hold rather than skipping it.

Records that your system has taken the order in. Idempotent.

curl -X POST "$BASE/partner/orders/7QM4P2/ack" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalOrderId": "ERP-2026-00184"}'

externalOrderId is optional and stored so support can trace an order across both systems. A repeat ack returns alreadyAcked: true and changes nothing — including ackedAt, which stays the moment you first took the order. Acking does not advance an order’s updatedAt, so an acknowledged order will not come back on the next pull just because you acknowledged it.

An ack is not a fulfilment. It means “we have this”. Use the four actions below to move the order itself.

Order actions

Five things your system can do to an order. Each returns 200 and each is idempotent — a repeat returns alreadyDone: true and changes nothing, so a retrying job is always safe.

curl -X POST "$BASE/partner/orders/7QM4P2/confirm" \
  -H "Authorization: Bearer $KEY"

{
  "reference": "7QM4P2",
  "status": "confirmed",
  "alreadyDone": false,
  "updatedAt": "2026-08-18T09:05:11.000Z"
}

status is read back after the action, so you can store the row you were given rather than inferring what the action must have produced.

• Confirm is the same rung as a merchant confirming by hand, so your system and the shop owner can race safely — whichever lands second reports alreadyDone rather than deducting twice.
• Reject only works before payment. Once an order is confirmed the money has been taken and the stock deducted, so unwinding it is a refund — a decision this API will not take on a merchant’s behalf. It returns 409.
• Preparing and ready need a paid order. Both are reachable straight from confirmed, so you never have to post a state you do not model — a kitchen that only knows “ready” never posts preparing. An order already past the state you post returns 409.
• None of these writes a stock figure. Confirming moves units the shopper had already reserved into a sale; your next absolute sync still overwrites whatever we hold.

You do not have to use them. A merchant can drive every one of these from WhatsApp or the till, and a small shop does. These exist because nobody types CONFIRM 7QM4P2 a hundred times a day, and your back office already knows when it took the money.

Instead of polling every 30–60 seconds, register one HTTPS endpoint and every order change is posted to it within seconds — the same order object GET /partner/orders returns.

curl -X PUT "$BASE/partner/webhook" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://erp.example.com/hooks/orders"}'

The response carries a secret (whsec_…) the first time only — store it like your API key. One webhook per account; PUT again to move it (the secret is kept) or to switch a disabled one back on. Registering needs orders:read too, because an endpoint receives order data.

What arrives

A POST signed to the open Standard Webhooks specification, so you can verify it with a published library.

{
  "id": "msg_7QM4P2_1755507911000",
  "type": "order.updated",
  "createdAt": "2026-08-18T09:05:11.000Z",
  "data": { "order": { "reference": "7QM4P2", "status": "confirmed", "…": "…" } }
}

• Answer any 2xx within 10 seconds, then do the work. Redirects are not followed.
• The order is sent as it stands when the delivery goes out, so a burst of changes arrives as one delivery of the latest state.
• Delivery is at least once. Verify the signature over the raw body, and reject a timestamp more than five minutes old.

Retries, rotation and removal

A failed delivery is retried after 30s, 2m, 10m, 30m, 1h, 3h, 6h, 12h, 24h — about two days. An endpoint that answers 410 Gone, or where 20 deliveries in a row fail every retry, is switched off; GET /partner/webhook shows why, and PUT switches it back on.

Standard HTTP status codes, with a message written to be read by a human.

{
  "statusCode": 400,
  "message": "\"items\" carried 1500 products, which is over the limit of 1000 per request. Split the store's catalogue into pages of 1000 or fewer…",
  "error": "Bad Request"
}

Retrying

Everything here is safe to retry: the sync sets absolute figures, the ack is idempotent, and reads have no side effects. Retry 5xx and network failures with exponential backoff; do not retry a 4xx without changing the request.

Limits

A large chain’s catalogue must be paged. Pages are independent — each is applied on its own, order does not matter, and a failed page can be re-sent alone. Send pages sequentially per store: two concurrent syncs of the same store would both be applied, and the last to land wins.

Setup, once

GET  /partner/whoami          # confirm the key and the account
GET  /partner/stores          # pull the shop list
PUT  /partner/stores/:code    # bind your codes — safe to re-run on every deploy

Stock or menu, on your own schedule

A full push nightly, plus a smaller push every 15–30 minutes for products that moved, is a good default. Both are the same call; there is no separate “incremental” mode, because an absolute figure needs none. A kitchen should also send a one-row sync the moment a dish is taken off or put back on — waiting for the next scheduled push leaves a window in which that dish can still be ordered.

for each store:
    for each page of ≤1000 items:
        POST /partner/stock/sync
        alert if unpricedCount > 0 or skipped > 0
        log warnings

Orders, every 30–60 seconds for a kitchen; every 1–5 minutes otherwise

PAID = {"confirmed", "preparing", "ready", "fulfilled"}

cursor = load_saved_cursor()          # null on first ever run
loop:
    page = GET /partner/orders?cursor={cursor}&limit=100
    for order in page.orders:
        if order.ackedAt is null and order.status in PAID:
            create_in_erp(order)
            POST /partner/orders/{order.reference}/ack
        elif order.ackedAt is not null:
            update_in_erp(order)      # status, kitchen times, fulfilment details
    save_cursor(page.nextCursor)      # persist BEFORE the next request
    if page.orders is empty: sleep and continue

Persist the cursor durably. Losing it is recoverable — you can replay from the start and your ackedAt check will skip everything you already have — but it is avoidable.

Reconciliation, daily

GET /partner/stock per store, compared against your own count. Expect differences of exactly reserved units; anything else is worth investigating.

Questions, a key rotation, or a new store code: email support@bitasei.com or call +234 907 888 4939.