↑↓ selectEnter openEsc close

    1. Elbuz
    2. API v2

    How to send your store's orders to Elbuz via the API

    5 min readUpdated

    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

    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

    1. 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”.
    2. In the “On behalf of” field, select an employee who has the orders window and the “Add” button allowed.
    3. Clear “Read only”.
    4. Switch “Data changes” to “Act on its own”; only Management can do this. Otherwise each order batch waits for approval in Pulse.
    5. In “Safety limit: changes per hour”, set a number with room to spare: one orders/sync request is one change, even with 100 orders in it. Exceeding the hourly limit switches the key back to “Ask”.
    API key card: user name, data changes mode, hourly safety limit and the read-only switch
    1User = key name
    2Data changes: Act on its own
    3Safety limit: changes per hour
    4Read only (off)
    1. User — the key name, which also becomes the source of the orders it brings in.
    2. Data changes — set to “Act on its own”, so the key writes changes itself.
    3. Safety limit — at most 1000 changes per hour are allowed for this key.
    4. 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.

    FieldWhat it holds
    ordersfrom 1 to 100 orders; no other top-level fields are allowed except template_id
    order_idrequired 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_idElbuz status ids: how to pass statuses
    firstname, lastname, email, phonethe 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_extcurrency code (UAH), order total and order date on the website
    item_listitems: 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 fieldLookupExample in the demo account
    status_idGET /api/v2/document_statuses1: “New”, 11: “Paid”, 10: “Canceled”
    payment_status_idGET /api/v2/payment_statuses1: “Pending”, 5: “Paid”
    delivery_status_idGET /api/v2/delivery_statuses1: “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_id than last time, or the manager hasn't changed this status yet. Sending the same status_id again doesn't overwrite the manager's status.
    • Items don't change: you can omit item_list in 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.updated webhook. Several changed orders in one batch give one documents.bulk_updated event. 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”:

    The Orders window filtered to the three orders that arrived through the API key: payment, delivery and order statuses
    1Order paid on the site
    2Delivery status On the way
    3New order, not paid yet
    1. An order paid on the site arrives in Elbuz with the payment status Paid and the order status Paid.
    2. The delivery status from the site, On the way, is carried over to the order.
    3. 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_id is 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_code is 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).

    CodeWhat's in detail / errorsCause
    400orders is requiredthe orders array is empty or missing
    400Idempotency-Key header is required for POSTno Idempotency-Key header
    403read-only key“Read only” is on for the key
    403no right for syncthe key owner isn't allowed the “Add” button in the orders window
    404POST /orders/sync has no idthe 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
    422at most 100 orders per requestmore than 100 orders in a batch
    422unknown fields in action bodysomething at the top level other than orders and template_id
    429another order import is running, retry laterwaited 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

    Common problems
    What you seeWhyWhat to do
    Response 202, no orders in the listthe key is in “Ask” mode, or switched back to it itself after exceeding the safety limitaccept the request in Pulse, switch the key to “Act on its own” and raise the safety limit (key)
    The same order appeared twiceit was sent with another key or without template_id, while the tunnel imported it firstsend with one key; for tunnel orders, with template_id (moving)
    The website sent a status, but Elbuz kept the old onethe manager changed the status and the website repeated the same status_id, or the document is postedthis 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 senduse a new Idempotency-Key for each new send
    Items landed in a service categorythe product wasn't found in the catalog by sku and namepass 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_statuses lookups

    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

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free