↑↓ selectEnter openEsc close

    1. Elbuz
    2. Websites and CMS

    How to send OpenCart 3 orders to Elbuz with a ready-made module

    10 min readUpdated

    The Elbuz API Sync module on an OpenCart 3 store sends orders to Elbuz itself: new ones right after checkout, existing ones after each status change. They become “Customer order” documents.

    When you need this:

    • Managers need orders in Elbuz at once — they arrive within seconds, no schedule.
    • A customer paid on the site — the payment module sets a status, and the order becomes “Paid”.
    • Elbuz is down — checkout works; the order waits in the module queue.
    • Elbuz Tunnel still picks up orders — the module continues the same documents, no duplicates.

    Where to start: download and install the module, then issue it a key in Elbuz.

    What the module does

    How to install the module on your site

    1. Download the elbuz_api_sync.ocmod.zip archive.
    2. In the OpenCart admin, open “Extensions → Installer” and upload the archive with the “Upload” button. If you can't use the installer, copy the contents of the upload folder from the archive to the site root.
    3. Open “Extensions → Extensions” and choose “Modules” in the extension type list.
    4. In the “Elbuz: order sync” row, click “Install” (green plus), then “Edit” (pencil).

    After installation the module is off and sends nothing until you fill in the connection and save it with “Status” set to “Enabled”. Removing the module with “Uninstall” deletes its queue and log.

    How to issue a key for the module in Elbuz

    The module needs its own API v2 key. The key name becomes the order source in the list, and Elbuz uses the key to recognize orders it already has.

    1. In Elbuz, open “API and access tokens” and click “+”.
    2. In the “User” field, enter the store name, for example site_opencart.
    3. In “On behalf of”, choose an employee who has the orders window open and the “Add” button allowed.
    4. Clear “Read only”.
    5. Switch “Data changes” to “Act on its own”. Only the “Management” group can switch it.
    6. In “Safety limit: changes per hour”, set a number with headroom: each module send counts as one change, even if it carries 100 orders.
    7. Save and copy the key — it starts with elbz_.
    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.

    If you leave “Data changes” in “Ask” mode, or the key exceeds the safety limit, every send waits until someone accepts it in “Pulse”. In the module log these orders show the result “waiting for confirmation in Elbuz”, and they are not in the Elbuz order list.

    One key per site. Under a shared key, identical order numbers from two sites merge into one document. General key rules are in API v2.

    How to connect the module to Elbuz

    Where: the “Elbuz: order sync” module → “Connection” tab.

    1. “Status” — “Enabled”.
    2. “Elbuz API address” — your account address ending with /api/v2: https://your-domain.elbuz.com/api/v2. An address without https:// or http:// won't save: “The API address must start with https:// or http://”.
    3. “API key” — the key you copied in Elbuz.
    4. Leave “Elbuz template ID” empty. You only need it when moving from Elbuz Tunnel.
    5. Click “Check connection”. The reply “Connected. Document statuses received: N, payment statuses: M.” means the address and key are correct, and Elbuz statuses now appear on the “Statuses” tab.
    6. Save the module with the blue floppy-disk button at the top right.

    “Check connection” takes the address and key straight from the form, without saving. The module starts sending orders only after you save. A failed check reads “No connection to Elbuz: …” with the reason — see the table below.

    How to map site statuses to Elbuz statuses

    Where: the “Statuses” tab. For each OpenCart status, choose “Elbuz document status” and “Elbuz payment status”. The list of Elbuz statuses appears after “Check connection”.

    Status on the siteElbuz document statusElbuz payment status
    PendingNewPending
    Processing, paidPaidPaid
    CanceledCanceled— do not change —

    OpenCart has no separate payment status: payment is shown by the same order status. So for the statuses your site gives paid orders, choose “Paid” in the payment column.

    “— do not change —” means this site status doesn't change the matching status in Elbuz. A new order with no mapping gets the default status, “New”. If “Elbuz template ID” is filled in, the template's status mapping applies to empty rows.

    The module sends an order every time its status changes. Whether a new site status overwrites the one a manager set in Elbuz is decided by the general rules: which status wins. Line items are written only when the document is created.

    How to send orders that are already on the site

    The module sends new orders by itself. Send the ones that existed before installation manually.

    Where: the “Send” tab.

    1. In “Orders changed since”, pick a date. The default is 30 days ago.
    2. Click “Send”. The module takes all orders changed since that date, except abandoned carts with no status, and sends them in batches of 100.
    3. Keep the page open until “left in queue: 0” appears next to the button. The line reads “Sent: N, errors: M, left in queue: K”.

    Sending the same orders again creates no duplicates: they are updated in the documents already created. Use the same button to catch up after a failure — pick the date from which orders didn't arrive.

    Cron URL

    Under the button there is a “Cron URL”. Add it to your hosting scheduler to run every 5–15 minutes, for example:

    */10 * * * * curl -s "https://your-site/index.php?route=extension/module/elbuz_api_sync/cron&key=…" >/dev/null

    Cron sends whatever didn't go through at once — up to 1000 orders per run. Without it, the queue goes out with the next site order: if there are no orders at night, one held up yesterday arrives only in the morning. A URL without the correct key returns 403 and sends nothing.

    How to check that orders arrive

    1. Place a test order on the site.
    2. In the module, open the “Journal” tab. The order should have the state “sent” and the result “created”. The “Elbuz document” column shows the document ID in Elbuz, not its number in the order list.
    3. In Elbuz, open the “Orders” window. The order is at the top with the source “API: key name”; its site number is stored in the document as a separate field.
    4. Change the order status in the OpenCart admin. The log shows “updated”, and Elbuz shows the status from your mapping table.

    The log shows the last 30 orders. Yellow rows are still in the queue, red ones were not sent; the reason is in the “Message” column. The number in the “Order” column opens the order in OpenCart.

    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.

    What happens if Elbuz doesn't respond

    The module doesn't slow down or break checkout on the site. It waits up to 5 seconds for Elbuz to reply, then writes the error to the log and keeps the order in the queue.

    An order's path from the site to Elbuz: each send takes the order's current data, so a retry never sends an outdated status
    acceptedkey in “Ask” mode422 in order datano connection, key, rights,rate limitnoyesOrder placed or its status changedModule queues the orderand sends it at once, waits up to 5secondsWhat did Elbuz reply?“sent”: “created” or “updated”“sent”: “waiting for confirmation inElbuz”request in “Pulse”“not sent”: waits for a status changeor the “Send” button“queued”: retry after 1, 4, 9 …minuteswith the next order, via cron or thebutton30 attempts without success?
    • Start or end
    • Action or result
    • Decision: the path depends on the answer
    What happenedWhat the module doesState in the log
    Elbuz accepted the orderRecords the document number“sent”, “created” or “updated”
    The key is in “Ask” modeStops retrying: the request is already in “Pulse”“sent”, “waiting for confirmation in Elbuz”
    Elbuz rejected one order's data (422 with an orders[…] field)Stops only that order; the rest of the batch goes on“not sent”, “error”
    No connection, key or permission error, rate limit, another 422 reply (for example, template not found)Retries after 1, 4, 9 … minutes; the longest pause is 12 hours“queued”, “error”
    30 failed attempts in a rowStops retrying“not sent”, “error”

    An order marked “not sent” goes out again when its status changes on the site, or when you click “Send” with a date that covers it. Every retry takes the order's current data.

    How to move from Elbuz Tunnel without duplicates

    Orders already picked up by the tunnel are stored with its template as the source. To make the module update those documents instead of creating new ones, enter that template's number.

    1. In Elbuz, open Directories → Operations → Data import. The tunnel template number is in the last column of the template list, “ID”.
    2. In the module, on the “Connection” tab, enter it in “Elbuz template ID” and save.
    3. Change the status of one old order on the site. The module log should show “updated”, not “created”.
    4. In the tunnel template, clear the “Orders” checkbox so orders don't arrive two ways. The tunnel keeps picking up the catalog.

    With “Elbuz template ID” set, the template's status mapping applies: its “Order statuses” and “Payment statuses” buttons. A row filled in on the module's “Statuses” tab takes priority over the template. The template must be visible to the key's employee, otherwise a send returns 422 with "template_id": "not found".

    Scenarios

    New store: orders must appear in Elbuz at once

    Task: the manager works in Elbuz and shouldn't wait for a schedule to see site orders.

    What to do: a separate key in “Act on its own” mode; in the module — “Status” “Enabled”, the address, the key, “Check connection”, status mapping, save; “Send” with the date the site went live; the cron URL in the scheduler every 10 minutes.

    Result: each new order becomes a “Customer order” document with the source “API: key name” within seconds, and a status change on the site updates the same document.

    Card payment on the site must show up in Elbuz

    Task: the manager shouldn't reconcile payments with the payment provider by hand.

    What to do: on the “Statuses” tab, for the status the payment module sets after payment, choose “Paid” in both columns.

    Result: as soon as the payment module changes the status, the order in Elbuz gets the payment status “Paid”. Stock and reservations don't change until the document is posted.

    Catalog via the tunnel, orders via the module

    Task: for years the tunnel picked up both the catalog and orders; orders now need to arrive at once, not with the next run.

    What to do: move from the tunnel: the tunnel template in “Elbuz template ID”, a check on an old order, then clear the “Orders” checkbox in the template.

    Result: old orders are updated in the same documents, and new ones go there too. The tunnel keeps updating the catalog on its own schedule.

    What to do when orders don't arrive

    Common problems
    What you seeWhyWhat to do
    “No connection to Elbuz: HTTP 401 invalid, disabled or expired key”the key was copied partially, turned off or replaced with a new onecopy the key again from “API and access tokens” and check the key's “Active” flag
    “No connection to Elbuz: HTTP 404” or a connection errorthe address lacks /api/v2 or the domain is wrongthe address must be https://your-domain.elbuz.com/api/v2
    “HTTP 403 read-only key” in the logthe key has “Read only” checkedclear the checkbox in the key; the module retries on its own
    “HTTP 403 no right for sync” in the logthe key's employee isn't allowed the “Add” button in the orders windowgrant the right or choose another employee in the key
    “HTTP 403 IP … is not allowed for this key” in the logthe key has a list of allowed IPs, and the site server isn't on itadd the site server's IP to the key
    Result “waiting for confirmation in Elbuz”, and the order isn't in Elbuzthe key is in “Ask” mode or exceeded the safety limitaccept the requests in “Pulse”, switch the key to “Act on its own”, raise the safety limit (key)
    “not sent”, with HTTP 422 and an orders[…] field in “Message”Elbuz didn't accept the order data, for example a mapped status was deleted in Elbuzclick “Check connection”, choose the statuses again, save and send the order with “Send”
    An order stays “queued” for a long timeElbuz didn't respond, and cron isn't set upadd the cron URL or click “Send”
    The same order appears twice in Elbuzthe tunnel loaded it, and the module runs without “Elbuz template ID”; or the key was replaced with a different onemove from the tunnel; don't switch the module to a different key, only reissue the same one
    The log is empty after a new orderthe module is disabled or the settings weren't savedset “Status” to “Enabled” and save; until then “Send” replies “Enable the module and save the settings.”

    FAQ

    Does the module send products and prices to Elbuz?

    No, only orders. Elbuz Tunnel brings the catalog from the site, and tunnel export sends it from Elbuz to the site.

    What currency do amounts arrive in?

    In the order currency, that is, the way the customer paid. Line prices include tax; shipping comes as a separate amount.

    A customer added a product to an order on the site — will the document change?

    No. Line items are written only when the document is created; copy a changed order composition into the document by hand. Until the document is posted, repeat sends update the status, payment and shipping method; the address, amounts and customer stay from the first send.

    Does the module work on OpenCart 2 or 4?

    No, the module is for OpenCart 3.0.x. On an OpenCart 2 site, the tunnel picks up orders.

    Will an order from the module reduce stock?

    No. The document is created unposted, and Elbuz counts stock and reservations only from posted documents.

    What happens if I delete an order on the site?

    The document in Elbuz stays: the module doesn't delete documents. Before deleting, move the order on the site to a status mapped to “Canceled”, or delete the document in Elbuz.

    Where it is and who has access

    Download
    elbuz_api_sync.ocmod.zip — OpenCart 3.0.x, PHP 7.1+ with curl
    Module on the site
    Extensions → Extensions → Modules → “Elbuz: order sync”
    Key in Elbuz
    Account → System settings → “Other settings” → “API and access tokens”
    Access rights
    the key's employee needs the orders window and its “Add” button
    Where orders show up
    the “Orders” window, source “API: key name”

    The module sends orders only. It doesn't send the catalog: Elbuz Tunnel brings products from the site into Elbuz.

    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