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
| Where | What to do |
|---|---|
| Kaspi seller account | Sign in to the web version of your Shop account with the phone number and password from the Kaspi Pay mobile app |
| Same place | The “Настройки” (Settings) section → “Токен API” (API token) tab → the “Сформировать” (Generate) button |
| Same place | Copy the generated token |
| Elbuz | Import 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.
Kaspi partner help: How to get an authorization token in the Kaspi.kz Shop.
How to connect, step by step
- 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”.
- 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.
- Open a few orders and compare the items, totals, customer and status.
What goes into the order
| Kaspi data | Document field in Elbuz |
|---|---|
| order number | External number (used to recognize the order again) |
| customer's first and last name | First name, last name (capitalized) |
| customer ID | Link between the contact and the source |
| mobile phone | Phone |
| delivery address as one line | Delivery address |
| order total | Document total |
| payment method | Payment method and payment type |
| order state and status | Document status (see the status table) |
| creation date | Order 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.
- 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 Kaspi | Document status in Elbuz |
|---|---|
| new; approved by the bank | New |
| awaiting signature; accepted by the seller | Approval |
| completed; archived order | Done |
| returned | Returned |
| canceled | Canceled |
| awaiting cancellation | Awaiting cancellation |
| awaiting return | Awaiting return |
| awaiting a return decision | Awaiting 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 line | What 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:
| Column | What 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.
1
Automatic loading- 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
| What you see | Why | What 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.
- 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.
1
Token field- Token field — the only connection setting; paste the Kaspi API token here.
Related topics
- If an order got attached to the wrong customer or product — importing orders through the API.
- If you need to understand what happens to the data after a run breaks off — data import overview.
- If you also sell on Ukrainian marketplaces — orders from Prom.ua.
