↑↓ selectEnter openEsc close

    1. Elbuz
    2. Kazakhstan marketplaces

    How to import orders from Kaspi.kz into Elbuz

    15 min readUpdated

    Elbuz pulls orders from your Kaspi.kz store through the API by token and turns them into documents handled in one queue with other channels.

    When you need this:

    • Kaspi orders live in a separate account — they come into Elbuz documents with the customer and items.
    • A customer orders again — they're matched to one contact by phone.
    • Orders should arrive on their own — every 5 minutes Elbuz picks up new ones from all six Kaspi states.
    • Items should land on your cards — products are looked up by SKU and name.

    Where to start: generate a token in your Kaspi account and paste it into the “Kaspi” template.

    What the Kaspi connection does

    • Orders — the customer, phone, address, total, payment method and status go into a “Customer order” document.
    • Items — they find your product cards, and unknown ones are created in a hidden service category.
    • Statuses — Kaspi states and statuses are converted to yours with no setup.
    • Schedule — each run picks up new orders without duplicates.

    The catalog is not imported from Kaspi: products arrive only as order lines.

    What you need from Kaspi

    You need one value — the Token, an API access key that you generate in your seller account.

    Where to get the token: step by step

    WhereWhat to do
    Kaspi seller accountSign in to the web version of your Shop account with the phone number and password from the Kaspi Pay mobile app
    Same placeThe “Настройки” (Settings) section → “Токен API” (API token) tab → the “Сформировать” (Generate) button
    Same placeCopy the generated token
    ElbuzImport window → your “Kaspi” template → the “Connection” card → the “Token” field

    Only the company director can create a token. Generating it again doesn't change the token, so you can copy it again at any time.

    A Kaspi token never expires. Whoever has it gets data on your orders and products: give the token only to the person setting up the integration, and don't send it in open chats.

    How to connect, step by step

    1. Create a “Kaspi” type template. There is no “Import orders” checkbox: every run picks up orders. Want to check first? Switch the “Active” badge to “Disabled”.
    2. 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, up to 14 days back. Don't want to wait? Click “Import”. The Kaspi template has no “Test connection” button — whether the token worked is visible in the log.
    3. Open a few orders and compare the items, totals, customer and status.

    What goes into the order

    Kaspi dataDocument field in Elbuz
    order numberExternal number (used to recognize the order again)
    customer's first and last nameFirst name, last name (capitalized)
    customer IDLink between the contact and the source
    mobile phonePhone
    delivery address as one lineDelivery address
    order totalDocument total
    payment methodPayment method and payment type
    order state and statusDocument status (see the status table)
    creation dateOrder date on the marketplace

    Kaspi doesn't pass the email — only the phone. The customer is recognized by phone and by their Kaspi ID, so a person's repeat orders gather under one contact.

    Order items

    Kaspi returns items separately: for each product Elbuz makes several requests — the line list, the Kaspi product card, the item from your seller price list. So a large batch of orders imports noticeably slower than you'd expect. Each line gives the name, SKU (the item code in your Kaspi price list), price, quantity and line total.

    Why the import is slower than it seems: the two columns are the two sides of the exchange, time runs from top to bottom
    KaspiElbuzloop[For each product in the order]There are many times more requeststhan orders — hence the slownesslist of ordersorders without itemslist of order lineslinesKaspi product cardcard dataitem from your seller price listSKU and price
    • Request or action
    • Reply
    • loop — repeats
    • Note

    Kaspi doesn't pass the product category. The item is looked up among your products by SKU together with the name, or by the name alone. If it isn't found, it gets a card in the service category “Products - kaspi_kz - your connection name”. The category is hidden and excluded from exports.

    Such a card has only the name, SKU, price and quantity, with no description, photos or attributes. To keep the service category from filling up, make sure the SKUs in your Kaspi price list match the SKUs in Elbuz. The general process: how items find a product.

    How Kaspi statuses become yours

    Kaspi has two concepts: the state (where the order is in the process — new, awaiting signature, pickup, delivery, Kaspi Delivery, archive) and the status (what happened to it — approved by the bank, accepted by the seller, completed, returned, canceled). Both are converted to your statuses by built-in matching:

    State or status in KaspiDocument status in Elbuz
    new; approved by the bankNew
    awaiting signature; accepted by the sellerApproval
    completed; archived orderDone
    returnedReturned
    canceledCanceled
    awaiting cancellationAwaiting cancellation
    awaiting returnAwaiting return
    awaiting a return decisionAwaiting return decision

    Purchases on credit and prepayment go into different payment types of the document. The payment status is set to “Pending” — you mark the actual payment yourself.

    The manual matching buttons in the “Related settings” card save rules for this template and supplement the built-in matching: they only apply where it found nothing — say, for another payment method or a state that isn't in the table.

    Automatic import and history depth

    Kaspi has no instant notifications, so Elbuz polls it: every 5 minutes the system task “Marketplace orders” fetches orders of all active Kaspi templates with a token. No template schedule is needed; the interval is set in the task's row in the “Job schedule” window (scenario). If another template is importing just then, even manually, the pass is silently skipped.

    Which orders a run picks up

    • Six states, each with its own request — new, awaiting signature, pickup, delivery, Kaspi Delivery, archive. This is the same on the first connection and on regular runs, so an order that moved from “new” to another state between runs is still imported.
    • From the start date, but at least 7 days back. Every state that returned orders records the date: the latest creation date among them. A run takes the earlier of the two — that date or a week ago.
    • No further back than two weeks. The first import takes orders from roughly the last 14 days. If the template stayed disabled for a month, the next run also takes only the last two weeks.
    • Statuses of already imported orders are updated — for orders that fall within the run's window. Your status changes only after a new change on Kaspi — who overwrites whom.

    Connect Kaspi as early as possible: history is limited to two weeks, and every day of delay means orders that can no longer be pulled in.

    How to check that the import worked

    Log lineWhat it means
    “Requesting a list of orders #1 NEW”A request for one page of orders in the state named at the end of the line. Elbuz asks for pages of 1,000 orders. These lines go in turn for NEW, SIGN_REQUIRED, PICKUP, DELIVERY, KASPI_DELIVERY and ARCHIVE — both on the first connection and on regular runs.
    “Orders received: N”How many orders Kaspi returned in this state, including those already in Elbuz.
    “Total items imported: N”How many new product cards were created for items not found in your catalog. These cards go into the service category.
    “Total orders imported: N”How many new documents were created.
    “Data import completed!” and “Time elapsed: …”The run reached the end. The same time appears in the template list, in the “Last import” column.
    • Skipped — the difference between “Orders received” and “Total orders imported”: they are already in Elbuz.
    • “Received” is there, “Total orders imported” isn't — no new documents were created.
    • Not even “Received” — Kaspi returned no orders for this state and period.
    • “Data import completed!” doesn't mean there were no errors — check the log above it (troubleshooting).

    In the document list, Kaspi orders show up in these columns:

    ColumnWhat it holds for a Kaspi order
    “Source: name”The name of your Kaspi template
    “Source: ID”The number of this template
    “Document number (site)”The order ID as the Kaspi API returned it
    “Document status (site)”The order status in Kaspi as a code, as it arrived: APPROVED_BY_BANK, ACCEPTED_BY_MERCHANT, COMPLETED and so on

    Scenarios

    Start managing Kaspi orders in Elbuz

    What to do: create a “Kaspi” type template, paste the token into the “Token” field and run the import.

    Result: Elbuz goes through all six states starting 14 days back. Orders become documents, customers become contacts, and unknown items become cards in the hidden service category. The start date is recorded only if at least one order arrived; otherwise the next run again starts 14 days back.

    New orders should appear without a manual run

    What to do: nothing beyond the token and the “Active” state. A hint in the “Related settings” card reminds you of this — there's no “Schedule setup” button there.

    Kaspi import template: the Related settings card with the automatic order loading hint and mapping buttons
    1Automatic loading
    1. Automatic loading — Elbuz fetches Kaspi orders by itself every 5 minutes, so the template needs no schedule of its own.

    Result: every 5 minutes a run requests the six states at least 7 days back and no further than 14: new orders become documents, and already imported ones get their statuses updated.

    Items should land on your cards, not in the service category

    What to do: name your products in Elbuz the same way as the items in your Kaspi seller price list, and align the SKUs.

    Result: a found item is recorded with your card. An item that isn't found gets a card in the service category, which remembers the Kaspi product code — the next orders with this product land on that card, without duplicates.

    What to do when orders don't arrive

    Common problems
    What you seeWhyWhat to do
    “API token not specified” The “Token” field is empty Paste the token and save the template (where to get it)
    Authorization error from Kaspi The token was copied with a space or with its end cut off; it has no expiry date Copy the token again from the “Токен API” (API token) tab
    Kaspi error text in the log An error on the first page of a state stops the run without saving that state; on later pages the earlier pages are saved and the run moves on to the next state Run it again — what wasn't saved will arrive (interrupted run)
    “Kaspi: could not get the items of order N — the orders page was not saved; it will be loaded on the next run.” Kaspi didn't return the product data; the page isn't saved so that there are no documents without items Nothing: the next run will pick up this page
    No orders from last month History goes back no further than two weeks Manage older orders in your Kaspi account (history depth)

    If a run breaks off

    For each state, Elbuz first pulls all pages with items into a temporary file, then in one pass writes contacts, cards, documents, items and finally the start date. Each of the six states is saved independently. The general rules are in the overview.

    Both branches go through six states: the left one is the first connection, starting 14 days back; the right one is a regular run, starting from the start date, but at least 7 days back. From there the path is shared: a stop check before every page, a database write after every state, and a Kaspi error or a stop on the first page of a state ends the pass over states without saving that state
    no, first connectionyesyesyesno, earlier pages arrivednoyes, line in the logyesno, earlier pages arrivednoyesnono, nothing is savedyesyes, next statenoKaspi template runIs the start date already recorded?Queue of six statesNEW, SIGN_REQUIRED, PICKUP,DELIVERY, KASPI_DELIVERY,ARCHIVEstarting 14 days backQueue of six statesNEW, SIGN_REQUIRED, PICKUP,DELIVERY, KASPI_DELIVERY,ARCHIVEfrom the start date, but at least7 and at most 14 days backWas stop clicked?Operation aborted by user!the page isn't requestedIs this the first page of the state?The run ends without saving thisstateand without the line Data importcompleted!Did at least one order arrive?Request a page of up to 1,000orderstogether with itemsDid Kaspi return an erroror not return an item's product?Is this the first page of the state?The state isn't saved,the remaining states aren'trequestedData import completed!Page - to a temporary fileAre there more pagesby the Kaspi counter?Any states left in the queue?Write to the database: contacts,cards,documents, items, start date
    • Start or end
    • Action or result
    • Decision: the path depends on the answer
    • Stop is checked before every page: pages already received for the current state are saved, and the next states aren't requested. The log shows “Operation aborted by user!” without “Data import completed!”.
    • A break before the start date is written — the next run starts from the old date; documents already created are recognized by their Kaspi ID.
    • A break between a document and its items leaves the document without products, and a rerun won't add them. Delete that document — a new one appears when Kaspi returns this order again.

    How to remove documents from a faulty run

    Filter the document list by “Source: name” (or “Source: ID”) and the run time, select the documents and click “Delete selected documents” (general rollback process).

    • Posted documents aren't deleted: “Posted documents were not deleted (N). Cancel the posting first.”
    • Deleted documents go to the “Document trash”: the “Undo” button in the “Documents deleted: N” message restores the batch, and the trash keeps it for 30 days. If the document's former internal ID is already taken, it gets a new one, and the number stays the same.
    • Contacts and product cards aren't deleted along with the documents; cards for unknown items stay in the service category.
    • A restored document keeps the Kaspi order ID and won't be duplicated. A deleted order that arrives from Kaspi again gets a new document — on regular runs, only orders no older than the start date.

    FAQ

    Can I import products from Kaspi into the catalog?

    No, the connection brings in only orders. Products arrive as order lines, and unknown ones as cards in the service category (items).

    Why weren't last month's orders imported?

    Elbuz takes history no further back than two weeks; older orders aren't imported.

    The order changed in Kaspi — why is the document in Elbuz outdated?

    A run re-reads orders at least 7 days back and no further than 14 — older ones won't get a status update. Your status changes only after a new change on Kaspi (who overwrites whom).

    Orders appear with a delay — why?

    Kaspi doesn't send instant notifications: Elbuz picks up 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.

    Why does a contact from Kaspi have no email?

    Kaspi doesn't pass the email — only the phone. The contact is recognized again by the phone and the customer's Kaspi ID.

    Where it is and who has access

    Menu
    Operations → Data import → a “Kaspi” type template
    Access right
    the “Import” window in “Group permissions”
    Prepare
    an token from the web version of your Kaspi.kz Shop account

    One template is one connection to one Kaspi store.

    Kaspi import template: the Connection card with the Token field
    1Token field
    1. Token field — the only connection setting; paste the Kaspi API token here.

    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