↑↓ selectEnter openEsc close

    1. Elbuz
    2. Ukrainian marketplaces

    How to import orders from Prom.ua into Elbuz

    17 min readUpdated

    Elbuz fetches orders from your Prom.ua account via the API with a token and turns them into documents in one queue with other channels.

    When you need this:

    • Prom orders are handled in a separate tab — they arrive in the document list with customer, delivery, waybill and commission.
    • Your Prom catalog came from Elbuz — items find cards by product code, not by name.
    • Orders should arrive without manual runs — Elbuz fetches new ones every 5 minutes.
    • You have several Prom accounts — all feed one order queue.

    Where to start: create a token in Prom and paste it into the “Prom.ua (API)” template in “Data import”.

    What the Prom connection does

    • Orders — the customer, delivery, , payment, promo codes and CPA commission go into the document.
    • Catalog matching — items find cards by the Elbuz product code; unknown ones are created in a service category.
    • Statuses — Prom order and payment statuses are mapped to yours with no setup.
    • Automatic import — new orders every 5 minutes, recent ones updated, no duplicates.

    This connection doesn't import Prom products: the catalog comes separately, via XLSX import (EVO) or .

    What you need from Prom

    You need one value — the Token, an API access key you create in your Prom company account. The token grants access to the account, so keep it safe like a password.

    Where to get the token: step by step

    WhereWhat to do
    Prom accountSection «Налаштування» → «Управління API-токенами» (Settings → API token management) → the «Створити токен» (Create token) button
    Same placeSet a name (optional), an expiry period and access rights per method group
    Same placeClick the created token to view and copy it
    ElbuzImport window → your Prom template → the “Connection” card → the “Token” field

    Tokens can be created by the company owner or a user with the «Адміністратор» (Administrator) role. If the menu item is missing, your user has a different role.

    Rights are set per method group: no access / read only / read and write. Importing orders needs only read access to the «Замовлення і повідомлення» (Orders and messages) group. To send statuses to Prom and reply to customers from “Tickets”, give it read and write. At least one group must be open, or Prom won't save the token.

    Prom limits the token's validity to one year at most (one day at least). When it expires, the import stops with authorization errors. Set a reminder: before it expires, extend the token in your account or create a new one and update the “Token” field.

    Signs in the log: missing rights — Prom responds with an access denial; expired — with an authorization error.

    Prom's step-by-step guide describing all token settings: Managing API tokens in your company account (Prom.ua help center for sellers).

    How to connect step by step

    1. Create a template of the “Prom.ua (API)” type. Want to test it first? Switch the “Active” badge to “Disabled”.
    2. Paste the token into the “Connection” card. The form saves itself; there's no save button. For an active template, Elbuz usually starts fetching orders within 5 minutes — the whole history Prom returns, then new ones. Don't want to wait? Click “Import”.
    3. Open a few imported orders and check the items, totals, customer and status.

    What goes into the order

    Prom dataElbuz document field
    order numberExternal number (used to recognize the order on later runs)
    customer's first name, middle name, last nameFirst name, middle name, last name (capitalized)
    customer IDLink between the contact and the source
    email and phoneEmail, phone
    delivery addressDelivery address
    delivery method, carrier, sender's and recipient's branchesDelivery details
    waybill numberWaybill (in the field of the matching carrier)
    delivery costDelivery cost
    order totalDocument total
    customer commentOrder description
    order sourceSource
    discount, promo code, free delivery under a promotionPromotion details
    CPA commission and its refund flagMarketplace commission
    payment method and statusPayment type, payment status
    order statusDocument status
    created and modified datesOrder dates on the marketplace

    Order lines bring the name, SKU, price, quantity, unit of measure, line total, plus a link to the product and its image on Prom.

    How items find catalog cards

    With each order line, Prom returns the external product ID — the one you passed to the marketplace with your catalog. The Elbuz export writes the Elbuz product code there. The product went to Prom with our code and the order came back with the same code, so the item finds its card exactly.

    Export your catalog to Prom with Elbuz — via XLSX export or an XML feed. If the catalog was uploaded manually or with another tool, items will be looked up by SKU with the name or by the name alone, which is less reliable. The general matching order: how items find a product.

    Checks run top to bottom and stop at the first match. A new card in the service category appears only when none of the four worked.
    yesnoyesnoyesnoyesnoyesnoItem from a Prom orderHas this product comefrom Prom before?Item linkedto an existing cardDoes the Prom product IDmatch the Elbuz product code?Do SKU and name match?Does the name match?Does the Prom product IDmatch the Elbuz product ID?New card in the category“Products - evo_market - templatename”The card is rememberedby the internal Prom product ID
    • Action or result
    • Decision: the path depends on the answer

    Service category for unknown products

    Prom doesn't pass the product category in the order line. An item missing from your catalog gets a card in the service category “Products - evo_market - template name”: name, SKU, price, quantity, unit, a link to the Prom product page and the Prom photo. The category is created disabled, excluded from file exports, one per template.

    Moving cards from there into your own tree is safe: the order line refers to the card, not the category, and keeps its own copies of the name, SKU, price and quantity. Later orders for the same product will find the card in its new place. You can delete the empty category after the move.

    A category deleted together with its cards takes the cards with their descriptions, photos and attributes along with it. Lines of already imported orders stay, but their link to the card breaks, and the next run will create the card and the category again. Move the cards first, then delete the category.

    How Prom statuses become yours

    Status mapping is built into the connection:

    Status in PromElbuz document status
    new (pending)New
    acceptedApproval
    paidPaid
    deliveredDelivered
    canceledCanceled
    draftDraft
    What is mappedHow
    Payment status“not paid” → pending, “paid” → payment, “refunded” → refund, “paid out to seller” → a separate settlement state with the marketplace
    Payment type «Пром-оплата» (Prom payment)payment via the marketplace
    Payment type «Безготівковий розрахунок» (cashless payment)bank transfer
    Any method containing «Накладений платіж» (cash on delivery)cash on delivery

    The “Related settings” card has buttons for manual mapping of statuses, payment and delivery types. The built-in mapping applies first, and your rules only pick up what it found no match for.

    What happens to an already imported order

    The first run fetches the whole order history. Later runs re-read orders from at least the last 7 days; older ones aren't re-read. The run finds a document with the same Prom order number and source, so no second copy appears.

    In already imported orders, the status, payment and delivery are updated. Your status changes only after a new change on Prom — which status wins. A cancellation on Prom of an order older than 7 days won't reach Elbuz.

    How a status from Elbuz gets to Prom

    In the other direction, the status is sent: change a Prom order's status in Elbuz, and the new status goes to Prom. For this:

    1. Turn on the “Send order status to the marketplace” switch: “Tickets” → gear → “Autonomous support” → the “Channels and proactive” tab. It's off by default.
    2. Map your statuses to Prom codes with the template's “Order statuses” button: Prom gets the code set next to your status.
    3. Give the token read and write access to the Orders and messages group.

    A cancellation goes to Prom with a reason. The result shows in the document history: “Status sent to the marketplace: ‹code›” or the reason it wasn't sent — the status isn't mapped, the template has no credentials, or Prom responded with an error.

    • The customer is looked up by email, then phone, then Prom customer ID (without it, by the “email + phone” fingerprint). Only empty email and phone are filled in on the found card; the name, address and the rest aren't updated.
    • Product cards aren't updated: not the price, stock or name. Only the total number of sales is recalculated.
    • A line deleted by the manager won't be added back: items are added only to documents created by the same run.

    How to check that the run worked

    The Prom template has no “Check connection” button: run the import and read the log in the Operations center. The window isn't blocked, and there's a “Stop” button next to the log.

    Log lineWhat it means
    “Requesting a list of orders #1”, “#2”, …the number of the page currently being fetched from Prom; as many such lines, as many pages read
    “Orders received: N”how many orders Prom returned across all pages — both new ones and those you already had
    “Total items imported: N”how many new product cards had to be created for order items
    “Total orders imported: N”how many documents were created. This is the result of the run
    “Updating values based on formulas”the final step; the automatic pass skips it
    “Data import completed! Time elapsed: …”the run has finished, with its duration next to it

    Look at the numbers, not the last line. No “Orders received” line means Prom returned no new orders, and the run still ends with “Data import completed!”.

    Errors are logged as separate lines — “API token not specified” or a Prom authorization denial with the text 401 Not Authenticated. Such a line marks the whole operation as failed.

    • Run trail: the “Last import” column in the template list and the “Run history” button in the template header.
    • “New order” notifications with the number, total, customer and products — no more than ten per run; find the rest in the document list.

    Imported orders are visible in the document list through the source columns:

    Document list columnWhat it shows for Prom
    “Source: name”the name of your Prom template
    “Source: code”the connection code — for Prom it's evo_market
    “Source: ID”the number of the template that imported the document
    “External document ID (UUID string)” and “Document number (site)”the order number on Prom — the same key the run uses to recognize an already imported order

    Automatic import

    Prom doesn't send instant notifications, so Elbuz checks by itself: the “Marketplace orders” system task fetches orders for all active Prom templates with a token every 5 minutes. The template needs no schedule — the Prom form has no “Schedule setup” button. The interval is changed in the “Job schedule” window, in this task's row. More: automatic order import.

    How many orders a run fetches

    • There's no cap. Orders come in pages of 100 with a one-second pause until Prom returns an empty list.
    • Prom limits per IP address are 100 requests per second, 200 per 10 seconds and 21,600 per two hours. One page per second keeps the run well below them.
    • First connection — no date is set in the request, so the run pulls the whole history the marketplace returns.
    • Later runs — from the start of the day on which the last imported order was created, but no later than 7 days ago: that's how cancellations and payments reach already imported orders. Existing documents aren't duplicated.

    The boundary is shown in the “Advanced” section of the template form: “Import orders starting from ID” and “Import orders from date (YYYY-MM-DD)”. The run sets both values itself, but a value you type is kept: the next run starts from the earlier of the two dates — yours or “7 days ago”. Leave the date empty, and the run fetches the whole history, as the first time.

    Expanded Advanced section with the two order start fields
    1Import orders starting from ID
    2Import orders from date (YYYY-MM-DD)
    1. Import orders starting from ID — the minimum order ID to download; 0 means no limit.
    2. Import orders from date — only orders created on or after this date are downloaded.

    Two imports never run at the same time. If another template is importing at that minute, including manually, the pass is silently skipped and the next one, 5 minutes later, fetches the orders (how imports are kept apart).

    How to pause the import

    The template state is switched with the “Active” / “Disabled” badge in the form header; in the template list, it's the “State” column.

    Template header with the state pill and the run history icon
    1State pill
    2Run history icon
    1. State pill — shows whether the template is Active or Disabled; in this demo it is Disabled.
    2. Run history icon — opens the history of import runs.

    Automatic import skips a disabled template; the token, mapping, orders and the “from date” marker remain. You can still run it manually. Once it's enabled again, the run starts from the same marker: orders created during the pause are imported, and statuses of already imported orders after the marker are updated (what is updated).

    Scenarios

    Prom orders should appear in Elbuz without manual runs

    What to turn on: a “Prom” template, the “Token” field in the “Connection” card, and the “Active” template state. No schedule is needed.

    Result: every 5 minutes, the run creates documents for new orders and updates the status, payment and delivery of those imported in the last 7 days.

    Order items should land on existing cards instead of creating new ones

    What to turn on: first export your catalog to Prom from Elbuz via XLSX export or an XML feed, then run the “Prom” template.

    Result: an item finds its card by the Elbuz product code. A product without a card gets one in the service category, remembered by the internal Prom product : later orders find it. Orders don't update the price, stock or name of found cards.

    Two Prom accounts — one order queue

    What to turn on: two “Prom” templates, each with its own “Token”.

    Result: accounts are read independently, each with its own “from date” marker. Documents share one list, told apart by the “Source: name” column. Each template has its own service category. A customer of both accounts gets one contact card. No duplicate orders even if one account has two templates: all Prom templates share the evo_market source code.

    Pause receiving orders, then catch up

    What to turn on: switch the badge in the template form header to “Disabled”, and after the pause back to “Active”.

    Result: the first run after it's enabled imports the orders created on Prom during the pause and updates the statuses of already imported orders created after the marker.

    What to do when an import goes wrong

    Common problems
    What you seeWhyWhat to do
    “401 Not Authenticated” in the log The token has expired or is wrong Extend the token or create a new one and paste it into the “Token” field (where to get the token)
    Prom responds with an access denial The token has no rights to the Orders and messages group Give the token read access to this group
    “API token not specified” The “Token” field is empty Paste the token and save the template
    The run finished, but there are no orders No new orders have appeared since the last import Check the “Orders received” line (log)
    Order items land in “Products - evo_market - …” The catalog on Prom wasn't uploaded from Elbuz and has no product code Export the catalog from Elbuz (matching)
    An order is canceled on Prom but not in Elbuz The order is older than 7 days, so the run no longer re-reads it; or a manager changed the status after the cancellation Change the status manually (what is updated)

    If the run broke off or was stopped

    A Prom run saves the pages it reads to temporary files and doesn't touch the database until it has read all pages. General rules for a break: in the overview.

    • Break while paging — nothing appears in the database, and the “from date” marker stays in place. The next run reads the same range.
    • “Stop” takes effect before the next page: the log shows “Operation aborted by user!”, what was read is discarded, and nothing gets into the database.
    • Break while writing — what was already written stays: customers, products, documents, lines, and, at the end, the date marker. A repeat run reads the same range, recognizes existing documents by number and doesn't duplicate them.
    The “Stop?” → page → pause loop is page reading; the database doesn't change in it. Writing happens only after Prom stops returning orders; “Stop” skips writing, and what was read is discarded.
    noyesnoyesnoyesyesnoTemplate runIs the “Token” field filled in?“API token not specified”orders aren't read“Stop” clicked?“Requesting a list of orders” with thepage numberup to 100 orders per pageDid Prom return orders?1-second pauseAt least one order read?“Operation aborted by user!”what was read is discarded, nothingis written to the database“Data import completed!”“Orders received: N”customers, products, documentsand lines are writtenThe “from date” marker movesforward
    • Action or result
    • Decision: the path depends on the answer

    If the wrong data was imported

    Say the template was run with someone else's token. Everything the run created is tagged with the source — the general rollback procedure:

    What to removeWhere to look
    Documentsdocument list, filtered by the “Source: name”, “Source: code” or “Source: ID” columns
    Product cardsbase catalog, the “Source: code”, “Source: name”, “Source: ID” columns; also, all new cards are in the service category “Products - evo_market - template name”
    Contactscontacts directory, the “Source - Code” and “Source - name” columns

    Documents deleted in bulk go to the “Document trash”; the “Undo” button restores the batch within 30 days. Bulk deletion doesn't touch posted documents: “Posted documents were not deleted (N). Cancel the posting first.”

    Deleting documents doesn't move the “from date” marker back: the next run imports orders from the last 7 days again, but not older ones. If you deleted them by mistake, restore the batch from the “Document trash” before 30 days pass.

    FAQ

    Why aren't Prom products imported?

    This connection brings in only orders. The Prom catalog is imported separately — via XLSX import (EVO) or YML.

    Does the order status change on Prom when I process it in Elbuz?

    Yes, if “Send order status to the marketplace” is on and your statuses are mapped to Prom codes (status on Prom). Changes on Prom reach an already imported order while it's no more than 7 days old.

    Why do orders appear with a delay?

    Prom doesn't send instant notifications: Elbuz fetches orders every 5 minutes, so the delay is usually up to 5 minutes. It's longer when another import, including a manual one, was running at that moment: the pass is skipped until the next one (automatic import).

    How long is a Prom token valid?

    From one day to one year — you set the period when creating it. Before it expires, extend it in your Prom account or paste a new token into the template.

    Can I re-read orders from an arbitrary date?

    Yes. Enter a date in the “Import orders from date” field in the “Advanced” section — the next run re-reads orders from it (run volume).

    Where it is and who has access

    Menu
    Operations → Data import → template of the “Prom.ua (API)” type
    Access right
    the “Import” window in “Group permissions”
    Prepare
    an token from your Prom company account

    One template is one connection to one Prom account. The Prom template has no “What to import” card with checkboxes: the connection always fetches orders and only orders.

    Connection card of the Prom.ua import template with the Token field
    1Token field
    1. Token field — paste the API token issued in your Prom.ua account.

    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