Elbuz pulls orders from your Epicentr seller account via the Epicentr API (Merchant API) by token and turns them into documents handled in one queue with other channels.
When you need this:
- Your catalog goes to Epicentr as an Elbuz feed — orders come back via the API, no manual work.
- An order was canceled on Epicentr — an unposted document becomes “Canceled”.
- Managers use their own statuses — they stay until Epicentr's status changes.
- Lines must land on your cards — the feed ID comes back in the order line.
Where to start: generate a token in Epicentr and paste it into the “Epicentr” template in “Data import”.
What the Epicentr connection can do
- Orders — the customer, delivery, total, comment and payment flag go into the document.
- Catalog matching — order lines find product cards by the ID from your feed; unknown items are created in a service category.
- Statuses — Epicentr codes map to your statuses with no setup.
- Order updates — a status change on the marketplace reaches an unposted document.
- Schedule — each run fetches only changed orders.
This connection doesn't import the product catalog: your assortment goes to the marketplace in the opposite direction, as an XML feed.
What you need from Epicentr
You need a single token from the seller account. Tokens can be generated by the company administrator.
Where to get the token, step by step
| Where | What to do |
|---|---|
| Epicentr seller account | Turn on the switch in the additional settings — the tab you need then appears |
| Same place | “Settings” → “Company settings” → “API” tab → the “Generate” button |
| Same place | Copy the token with the icon to the right of the field |
| Elbuz | Import window → your “Epicentr” template → “Connection” card → “Token” field |
- There's no limit on the number of tokens, and all of them are active at once — create a separate token for Elbuz with a clear name.
- “Update key” issues a new token, and the previous one keeps working until you delete it.
Epicentr tokens have no expiry date and work until you delete them. Whoever has the token has access to your orders, so don't send it in open chats. If the key is compromised, delete it in the account with the trash icon (the exchange stops immediately) and generate a new one.
How to connect, step by step
- Create a template of the “Epicentr” type. There are no “What to import” switches: the connection handles orders only. Want to check first? Switch the “Active” badge to “Disabled”.
- Paste the token into the “Connection” card. The form saves itself — there's no save button: in an active template Elbuz usually starts picking up orders on its own within 5 minutes — for the last 30 days, then new ones. Don't want to wait? Click “Import”.
- Click “Test connection”. On success you see “Connection works” and the email of the Epicentr account that owns the token, so you can tell the key comes from the right account. On failure you see “Connection failed” and the reason from the marketplace.
- Open a few orders and check the lines, totals, customer and status.
What goes into the order
| Epicentr data | Document field in Elbuz |
|---|---|
| order number | External number |
| internal order ID | Key used to recognize the order on later imports |
| recipient's first, middle and last name | First name, middle name, last name |
| customer ID | Link between the contact and the source |
| phone and email | Phone, email |
| delivery details | Delivery address |
| order total | Document total |
| order comment | Order description |
| payment flag | Payment status: “Paid” or “Pending” |
| order status | Document status (see the status table) |
| created and modified dates | Order dates on the marketplace |
Order lines bring the name, SKU, price, quantity, line total and unit of measure, plus a link to the product and its image on the marketplace.
How order lines find catalog cards
With each order line, Epicentr returns the product ID in your system — the value you sent in the ID field of your XML feed: an internal number, code or SKU. Elbuz tries it every way in turn, so any choice works.
- The card Elbuz itself created for this Epicentr offer on earlier imports.
- The internal product code.
- The SKU together with the name.
- The name alone.
- The product number — only for an ID made up of digits only.
The first check that matches wins. So if your feed has the product number and the catalog has two cards with the same name, the line lands on the card found by name.
- Action or result
- Decision: the path depends on the answer
Export your catalog to Epicentr with Elbuz: the ID in the feed and in the order is then guaranteed to be the same. An assortment uploaded by hand will be searched by SKU and name, which is less reliable. General rules: how order lines find products.
Cards in the service category
An order line with no match in the catalog gets a card in the service category “Products - epicentr - ‹your template name›”. The category is created disabled and not marked for export, so these products don't go into feeds on their own.
The card holds the name, SKU, price and quantity from the order line, plus the product link and photo from the marketplace. The price is the one the item sold at, and the quantity is the ordered one. Fill in these cards or merge them with existing products.
You can move these cards to regular categories: a document line refers to the product, not the category, and keeps its own name, SKU, price and quantity.
Deleting a category removes all products for which it is the main one. Lines of imported orders keep their name, price and total, but the product link breaks, and these items drop out of sales counts. First move the cards to your own categories, then delete the empty service category.
How Epicentr statuses become yours
The mapping is built into the connection:
| Status on Epicentr | Marketplace code | Document status in Elbuz |
|---|---|---|
| New | new | New |
| Confirmed by seller | confirmed_by_merchant | Approval |
| Confirmed | confirmed | Confirmation |
| Sent | sent | Shipped |
| Ready for pickup | delivered | Delivered |
| Received | received | Issued |
| Completed; Closed | completed; closed | Done |
| Canceled; Canceled by seller | canceled; canceled_by_merchant | Canceled |
| Returned | returned | Returned |
| Return requested | return_requested | Awaiting return decision |
| Completed and Closed (seller rejection) | completed_merchant_rejection; closed_merchant_rejection | Rejected |
- The “Document status (site)” column shows the code from the middle column — confirmed_by_merchant, sent and so on, not a readable name.
- An order that sits in an intermediate status for a long time is moved to “Completed” by Epicentr itself, and Elbuz picks this up on the next import.
- Payment comes as a “paid” flag: if it's set, the payment status is “Paid”; if not, “Pending”.
The “Related settings” card has buttons for manual mapping of statuses, payment types and delivery types. The built-in mapping applies first, and your rules cover only what it found no match for.
What happens to an order that's already imported
An order is recognized by its internal Epicentr ID together with the source code, so no duplicate appears. General rule: two statuses of one order.
The document is posted — the import changes nothing in it; the card shows “The document is posted - editing is locked”. To get marketplace data flowing in again, unpost it.
The document isn't posted — Elbuz compares the Epicentr status code with the one it remembered last time:
- same code — your status stays, and the manager's edit is left alone;
- different code — the status is overwritten by the mapping table, even if a manager has just set their own;
- no code remembered yet — the status is left alone, and the code is only remembered.
- Action or result
- Decision: the path depends on the answer
Every import writes the Epicentr status code and the code and name of the payment and delivery method into an unposted document. The payment status, delivery status and payment type update only when a match is found — “Not matched” doesn't erase a value that's already set.
These don't change: the total, full name, phone, email, address, and quantity and price in the lines; lines aren't deleted. For a customer that's found, only empty email and phone are filled in.
If an order disappeared from your Epicentr account
The import doesn't delete or deactivate anything:
- deleted or hidden in the account — the document stays as it was after the last import;
- canceled — a cancellation code arrives, and an unposted document switches to “Canceled”;
- no longer changes — Elbuz fetches only changed orders, so the document isn't updated.
There's no separate “the order is gone” signal. Use the “Document status (site)” column with the latest code from Epicentr as a guide. Whether to delete the document or keep it for history is up to you.
When an order reaches stock and reservation
An order arrives as an unposted “Customer order” document and doesn't affect stock until it's posted.
- “Post” — the goods go into reservation. This needs the “Stock quantity tracking” setting turned on and at least one active warehouse. The reservation is counted on the warehouse from the order, or on the default warehouse if there isn't one.
- A sales invoice based on the order physically writes off the goods — posting it is what reduces the stock balance.
- The reservation is released by the statuses “Done”, “Completed”, “Issued”, “Canceled”, “Canceled return”, “Rejected”, “Returned”, “Product return”, “Voided”, “Failed”, “Overdue”, “Not relevant”. In “Shipped” and “Delivered” the reservation is kept.
- “Partial shipments” turned on — the reservation also shrinks as sales invoices are posted: only the unshipped quantity stays reserved.
The reservation is recalculated when a document is posted or unposted, or when its status changes in Elbuz itself.
Automatic import
Epicentr has no instant notifications, so Elbuz polls it: the system task “Marketplace orders” picks up orders for all active Epicentr templates with a token every 5 minutes. The template needs no schedule — there's no “Schedule setup” button in the form. You change the interval in the “Job schedule” window, in this task's row. More details: automatic order import.
- The first run fetches orders from the last 30 days.
- Later runs fetch only orders changed since the previous import.
How many orders one run fetches
- Pages of 100 orders, no more than 200 pages per run — up to 20,000 orders. The rest arrives on the next run.
- Every 200 orders are written to the database as a separate batch, so a break-off keeps everything up to the last batch saved.
- Each request gets 30 seconds to connect and 180 seconds for the response. On a server error or “too many requests” (code 429), there are up to three attempts with growing pauses, then the line “Epicentr: API request error” with the reason.
- Action or result
- Decision: the path depends on the answer
The log is kept in the Operations Center, so you can close the window. Log lines:
| Line | What it means |
|---|---|
| “Epicentr: page N, orders received: M” | the next page was read |
| “Orders received: N” | a batch was saved |
| “Total items imported: N” | new cards in the service category |
| “Total orders imported: N” | new documents |
| “Epicentr: order import finished, total: N”, “Data import completed!” | the run is over |
How to pause the import
There's a single switch — the template state, the “Active” / “Disabled” badge in the “State” column of the import list.
1
State pill (Disabled)- State pill in the Epicentr template row — shows Disabled; clicking it toggles the template, so it was not clicked.
Automatic import skips a disabled template, but a manual run still works. Documents, cards, contacts, mappings, the token and the starting point stay. Once you turn it back on, the run fetches everything that changed on Epicentr during the pause.
Scenarios
Orders should arrive on their own, without a manual run
Paste the token into the “Token” field, click “Test connection” and make sure the “State” column shows “Active”. No schedule is needed: every 5 minutes a run fetches changed orders, the first one for 30 days; new orders arrive unposted. Your actions won't change the status on Epicentr, and stock won't move until posting.
Managers use their own statuses, but a cancellation on the marketplace must override them
Nothing to turn on: the canceled code already maps to “Canceled”. While the code on Epicentr stays the same, the manager's status stays; once it changes, an unposted document gets the status from the mapping. A posted document doesn't change at all. You need the manual mapping buttons only for codes missing from the table.
Order lines should land on existing cards instead of creating new ones
Export your catalog to Epicentr with an Elbuz export template — the order line returns the feed ID. If the feed has an SKU and the line has none of its own, Elbuz searches by it plus the name. An unmatched line gets a card in the service category, and the next order with that offer lands on it.
Pause order intake without missing anything
Switch the badge in the “State” column to “Disabled”. The starting point doesn't move during the pause, so after you switch back to “Active”, the run fetches everything changed in the meantime. Documents, cards and the token stay.
What to do when orders don't arrive
| What you see | Why | What to do |
|---|---|---|
| “Epicentr: access token is not set” | The “Token” field in the template is empty — the marketplace wasn't even contacted | Paste the token from the account and save the template (where to get it) |
| “Connection failed: …” | The marketplace didn't accept the key: the token was copied partially, with a space, or was deleted in the account | Copy the token again with the icon next to the field and click “Test connection” once more |
| “Epicentr: API request error” | The marketplace didn't respond or returned an error three attempts in a row; the reason is in the same log line | Nothing — whatever didn't arrive will be fetched by the next pass (run limits). If you often get “too many requests” (429), increase the interval of the “Marketplace orders” task in the “Job schedule” window |
| A new order appeared more than 5 minutes late | Another template was being imported at that moment, including manually — two imports don't run at once, and the orders pass is skipped without a log entry | Nothing: the next pass will fetch the order. If delays are frequent, spread out the schedules of your other import templates |
| Order lines didn't find your products | The ID in the feed doesn't match the catalog, or the catalog wasn't uploaded from Elbuz | Export the catalog with Elbuz (matching) |
| “Posted documents were not deleted (N). Cancel the posting first.” | A posted document can't be deleted — it's already reflected in the accounting | Unpost it and delete again (how to undo a mistaken run) |
If a run was started by mistake
Everything that arrived can be found by filtering on the source columns (general rollback steps):
- “Documents” — “Source: name” (template name), “Source: code” (epicentr), “Source: ID” (template number);
- “Products” — “Source: name”, “Source: code”, “Source: ID”;
- “Contacts” — “Source: name”, “Source: code”.
Deleted documents go to the “Document trash”: the “Undo” button restores the batch, and the trash keeps snapshots for 30 days. Posted documents have to be unposted first. Contacts and cards are removed separately, in their own windows.
The next run fetches only orders changed since the previous import, so a deleted order won't arrive until something happens to it on the marketplace. Check the first run of a new connection right away.
FAQ
Can I import products into the catalog with this connection?
No, the connection brings in orders only. The catalog is exported to Epicentr as an XML feed — see exporting to Epicentr.
Do I need to renew the token periodically?
No, Epicentr tokens have no expiry date — they work until you delete them. So keep the token as safe as a password.
Does the order status on Epicentr change when I process the order in Elbuz?
No, the connection works one way. You change the status on the marketplace in your account, and the next import picks it up (how an order is updated).
How many tokens can I create?
As many as you like — all of them are active at once. “Update key” issues a new token, and the previous one works until it's deleted.
How far back does the first run fetch orders?
The last 30 days. After that, only orders changed since the previous import are fetched.
Why is there no “API” tab in my account?
The tab appears after you turn on the API switch in the additional settings, and tokens can be generated by the company administrator. If there's no tab, your user probably has a different role.
Where it is and who has access
- Menu
- Operations → Data import → template of the “Epicentr” type
- Access right
- the “Import” window in “Group permissions”
- Have ready
- a token from your Epicentr seller account
One template is one connection to one seller account.
1
Token field2
Test connection button- Token field — paste the API token from the Epicentr seller account here.
- Test connection button — checks the token against the marketplace (not pressed in this shot).
Related topics
- If you haven't exported your catalog to Epicentr yet — exporting to Epicentr as an XML feed.
- If an order got attached to the wrong customer — importing orders through the API.
- If you sell on Rozetka alongside Epicentr — catalog and orders from Rozetka.
