Your website, CMS or accounting system sends new orders and their changes to Elbuz with a POST /api/v2/orders/sync request. New orders become “Customer order” documents; imported ones are updated.
When you need this:
- Your CMS has no tunnel or marketplace: the website module sends orders to the API.
- Payment arrives on the website: the module resends the order, and Elbuz marks it “Paid” without a manager.
- A manager already handles the order: resending doesn't overwrite their status.
- You're moving from the tunnel: with
template_id, orders go into the same documents, no duplicates.
Where to start: issue a separate key for the store in “Act on its own” mode.
What order sync does
- Accepts a batch of up to 100 orders: new ones become documents, imported ones are updated; the response gives the
document_idand result for each. - Takes statuses by Elbuz lookup ids: order, payment and delivery status without mapping tables.
- Protects the manager's work: the status they set stays until the store sends a different one.
- Reports changes: a changed order gets a new modified date, triggers and the
documents.updatedwebhook. - Continues the tunnel's history: orders imported by the tunnel are updated via the API.
Why this matters for your business is covered separately: what it gives your store.
Ready-made module for OpenCart 3
For an OpenCart 3.0.x website, you don't need to write a module: the ready-made Elbuz API Sync module sends orders/sync itself, after checkout and after every status change. It keeps a “site status → Elbuz status” table, a retry queue and a send log. Download: elbuz_api_sync.ocmod.zip. Installation and setup: orders from OpenCart 3 with the ready-made module.
How to prepare the store key
- In the “API & access tokens” window, click “+” and in the “User” field give the key the store's name, for example
site_opencart. This name becomes the order source: “API: site_opencart”. - In the “On behalf of” field, select an employee who has the orders window and the “Add” button allowed.
- Clear “Read only”.
- Switch “Data changes” to “Act on its own”; only Management can do this. Otherwise each order batch waits for approval in Pulse.
- In “Safety limit: changes per hour”, set a number with room to spare: one
orders/syncrequest is one change, even with 100 orders in it. Exceeding the hourly limit switches the key back to “Ask”.
1
User = key name2
Data changes: Act on its own3
Safety limit: changes per hour4
Read only (off)- User — the key name, which also becomes the source of the orders it brings in.
- Data changes — set to “Act on its own”, so the key writes changes itself.
- Safety limit — at most 1000 changes per hour are allowed for this key.
- Read only — switched off, so the key may create and update orders.
One key, one store. Elbuz looks up imported orders by key: the same order_id sent with another key becomes a new document. Several websites need several keys.
How to send orders: request and response
curl -s -X POST "https://<your-domain>/api/v2/orders/sync" \
-H "Authorization: Bearer elbz_xxxxxxxx_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10481-1729700000" \
-d '{
"orders": [{
"order_id": "10481",
"firstname": "Olena", "lastname": "Koval",
"email": "olena.koval@example.com", "phone": "+380671234501",
"shipping_city": "Lviv", "shipping_method": "Nova Poshta",
"payment_method": "Card payment on the website",
"currency_code": "UAH", "document_sum": "825",
"date_added_ext": "2026-10-23 21:12:40",
"status_id": 1, "payment_status_id": 1,
"item_list": [
{"product_id_ext": "5", "sku": "99180", "name": "Blackview R3 Black", "quantity": "1", "price": "825"}
]
}]
}'
Response (demo account, 23.10.2026):
{"data":{"source":"api_key_509","template_id":null,"orders":[
{"order_id":"10481","document_id":1000403,"result":"created"},
{"order_id":"10482","document_id":1000404,"result":"created"},
{"order_id":"10483","document_id":1000405,"result":"created"}]},
"approval_id":11765}
approval_id is the number of the Pulse entry: every batch leaves a trace there, and in “Act on its own” mode it's already done.
| Field | What it holds |
|---|---|
orders | from 1 to 100 orders; no other top-level fields are allowed except template_id |
order_id | required order number on the website, up to 64 characters, unique within the batch. Elbuz uses it to recognize the order next time |
status_id, payment_status_id, delivery_status_id | Elbuz status ids: how to pass statuses |
firstname, lastname, email, phone | the customer; Elbuz uses the email and phone to find an existing contact |
shipping_*, payment_* | delivery address, carrier, payment method, as text, as on the website |
currency_code, document_sum, date_added_ext | currency code (UAH), order total and order date on the website |
item_list | items: product_id_ext (product id on the website), sku, name, quantity, price; the product is looked up by the same steps as in import |
The full list of fields is in GET /api/v2/openapi.json, path /orders/sync. Fields with internal Elbuz ids (product_id, category_id, currency_id, payment_type_id, *_jumper) aren't allowed: the response is 422.
If the website catalog was exported from Elbuz and the website knows our product id, pass it in product_id_2. By the Elbuz product uuid, the item is found right away; by the numeric id, as the last step, if the SKU and name didn't help.
The Idempotency-Key header is required, as for every POST in API v2. A retry with the same key and the same body within 24 hours gets the saved response without running anything again: if the connection dropped after the write, the order won't be duplicated.
After a 429, a retry with the same key runs. The same key with a different body: 422. Use a new key for each new send of an order.
The result in the response: created means a new document was created, updated means the order already existed, failed means there is no document after the write. The document number in Elbuz: GET /api/v2/orders/{document_id}.
How to pass statuses
The website passes Elbuz status ids, not its own names: the key has no mapping table, and the website module keeps the “site status → Elbuz status” mapping. Take the ids from the lookups:
| Order field | Lookup | Example in the demo account |
|---|---|---|
status_id | GET /api/v2/document_statuses | 1: “New”, 11: “Paid”, 10: “Canceled” |
payment_status_id | GET /api/v2/payment_statuses | 1: “Pending”, 5: “Paid” |
delivery_status_id | GET /api/v2/delivery_statuses | 1: “Awaiting sender”, 2: “On the way” |
Ids differ in each account, so read the lookup once when setting up the module. A nonexistent id returns 422 with "orders[0].status_id": "not found", and no orders from the batch are written. You can omit a field: a new order without delivery_status_id gets the default delivery status (“Awaiting sender”), and an imported one keeps its current status.
What happens to an order already imported
The same order_id from the same key is an update. The rules are the same as for marketplace import; in full: what overwrites what. In short:
- Payment and delivery are taken from the request if the field is passed.
- The order status changes if the store sent a different
status_idthan last time, or the manager hasn't changed this status yet. Sending the samestatus_idagain doesn't overwrite the manager's status. - Items don't change: you can omit
item_listin an update. - A posted document doesn't change at all.
- A changed order gets a new modified date and a change event: triggers, Flows and the
documents.updatedwebhook. Several changed orders in one batch give onedocuments.bulk_updatedevent. An order without changes gets neither a date nor events.
For an update, order_id and the changed fields are enough:
{"orders":[
{"order_id":"10481","status_id":11,"payment_status_id":5},
{"order_id":"10482","status_id":11,"payment_status_id":5,"delivery_status_id":2}]}
The response is "result":"updated" for both. In the order list, they show the source “API: site_opencart” and the status and payment “Paid”:
1
Order paid on the site2
Delivery status On the way3
New order, not paid yet- An order paid on the site arrives in Elbuz with the payment status Paid and the order status Paid.
- The delivery status from the site, On the way, is carried over to the order.
- A new order that is not paid yet stays New with the payment status Pending.
How to move from the tunnel without duplicates
Orders already imported by the tunnel or another import template are stored with the template's source. To have the API continue them instead of creating new ones, add that template's template_id to the body:
{"template_id": 2, "orders": [{"order_id": "11912",
"order_status_code": "2", "order_status_name": "Zapłacono",
"payment_service_status_name": "Zapłacono"}]}
- orders are looked up among those imported by the tunnel, so
order_idis the same as in the tunnel (the order number on the website). All tunnel templates share one source, so two websites with the same order numbers can't be separated this way; order_status_codeis the same code the tunnel wrote: for OpenCart, the order status number on the website. A different code is treated as a status change on the website and overwrites the manager's status;- the template's mapping applies, so you can send statuses by website names:
order_status_code,order_status_name,payment_service_status_name; - the point from which the tunnel continues importing (“Import orders starting from ID”) doesn't move: a batch may carry old orders;
- the template must be visible to the key owner; a nonexistent or someone else's template returns 422
"template_id": "not found".
Once the module is working, clear the “Orders” checkbox in the tunnel template so orders don't arrive two ways.
Errors
An error in any order rejects the whole batch: errors lists the fields with the order's position in the batch (up to 50 lines).
| Code | What's in detail / errors | Cause |
|---|---|---|
| 400 | orders is required | the orders array is empty or missing |
| 400 | Idempotency-Key header is required for POST | no Idempotency-Key header |
| 403 | read-only key | “Read only” is on for the key |
| 403 | no right for sync | the key owner isn't allowed the “Add” button in the orders window |
| 404 | POST /orders/sync has no id | the path contains an id: /orders/123/sync |
| 422 | "orders[0].nope": "unknown field" | an unknown field or an internal Elbuz field (order_status_id_jumper, product_id in an item) |
| 422 | "orders[1].order_id": "duplicate in request" | the same order_id twice in one batch |
| 422 | "orders[0].status_id": "not found" | no such status in the lookup |
| 422 | at most 100 orders per request | more than 100 orders in a batch |
| 422 | unknown fields in action body | something at the top level other than orders and template_id |
| 429 | another order import is running, retry later | waited 30 seconds for another batch of this account |
| 202 | {"status":"pending","approval_id":…} | the key is in “Ask” mode: the batch waits in Pulse |
Scenarios
An OpenCart module sends orders on status change
Task: every new order and every status change on the website must appear in Elbuz without a schedule.
What to do: in the website module, store the mapping “OpenCart status → Elbuz status_id and payment_status_id” read from the lookups. On order creation and on status change, send that order to POST /orders/sync with a new Idempotency-Key; items only on creation. On a 429 response or a dropped connection, repeat the same request with the same key.
Result: the order appears in Elbuz right after sending, payment on the website moves it to “Paid”, and the status set by the manager stays until the website changes its own.
Moving from the tunnel to the API without duplicates
Task: orders came in through the tunnel for years; now the website module sends them.
What to do: in the module, pass the tunnel template's template_id and statuses by website names, as in its “Order statuses” and “Payment statuses”. Test on one old order: the response must be "result":"updated", not created. Then clear the “Orders” checkbox in the tunnel template.
Result: old orders are updated in the same documents, new ones are added there too, and you don't have to move the status mapping.
What to do when orders don't arrive
| What you see | Why | What to do |
|---|---|---|
| Response 202, no orders in the list | the key is in “Ask” mode, or switched back to it itself after exceeding the safety limit | accept the request in Pulse, switch the key to “Act on its own” and raise the safety limit (key) |
| The same order appeared twice | it was sent with another key or without template_id, while the tunnel imported it first | send with one key; for tunnel orders, with template_id (moving) |
| The website sent a status, but Elbuz kept the old one | the manager changed the status and the website repeated the same status_id, or the document is posted | this protects the manager's work; a new status_id from the website will change the status (updates) |
| 422 “Idempotency-Key was used with another request” | the module sent a changed order with the key of the previous send | use a new Idempotency-Key for each new send |
| Items landed in a service category | the product wasn't found in the catalog by sku and name | pass product_id_2 with the Elbuz product id, or move the cards (product lookup) |
FAQ
Will sending again update the order items?
No. Items are written only when the document is created; items changed on the website are moved to the document manually.
What happens if an order was deleted on the website?
Nothing: orders/sync doesn't delete documents. Move the order to “Canceled” by sending the matching status_id, or delete the document in Elbuz.
Can several websites send orders with one key?
Better not: orders are recognized by order_id within a key, and matching numbers from two websites will merge into one document. Give each website its own key.
Will an order from the API write off stock?
No. The document is created unposted; post it in the window or with a POST /api/v2/documents/{id}/sign request.
In what language are status names written?
In the language of the employee on whose behalf the key was issued, or in the language from the Accept-Language header. That's how the order list shows them.
Where it is and who has access
- Address
POST https://<your-domain>/api/v2/orders/sync; list:GET /api/v2/orders- Key
- Account → System settings → “Other settings” → the “API & access tokens” tile
- Access right
- the key owner needs the orders window and its “Add” button
- Where orders appear
- the “Orders” window, source “API: key name”
- Prepare
- status ids from the
/document_statuses,/payment_statuses,/delivery_statuseslookups
General API rules (the Authorization: Bearer key, the limit of 120 requests per minute, the error format) are in the API v2 article. This one covers only orders.
Related topics
- If your website runs OpenCart 3: a ready-made module instead of your own code.
- If you haven't issued a key yet: API v2: key, permissions, errors.
- If another system needs to know about order changes: API v2 webhooks.
- If your website runs OpenCart and you don't want to install a module: orders via the tunnel.
- If you need to understand whose status stays: what overwrites what.
- If you're choosing software for order management: what it gives your store.
