How to connect Kaspi.kz to the portal: API token, orders, price-list stockBeta

This integration is in beta: it follows the marketplace's official documentation, errors are possible — check orders and stock in the marketplace's seller account.

Kaspi.kz connects with the API token from your seller account. The portal pulls orders onto your kanban in tenge, accepts and cancels them in Kaspi, prints the Kaspi Delivery waybill and completes the order with the buyer's code. Kaspi does not accept stock and prices through an API, only through a price list: the portal gives you a link to an XML file and Kaspi picks it up itself once an hour.

The Kaspi seller cabinet may not be available in English, so the names of its sections are given below as they appear in the cabinet, with a translation in brackets.

1. What the integration does

The integration follows the official Kaspi guide. It has not yet been verified against a live cabinet: the price list format has been checked only against the example in the guide.

2. Before you start

• A Kaspi seller cabinet (Kaspi Магазин, "Kaspi Shop") with an active contract.
• An API token, issued by Kaspi.
• Point-of-sale codes (storeId) from the cabinet, in the section "Склады и магазины" ("Warehouses and stores").
• The SKUs of your products in the Kaspi cabinet must match the SKUs of your products in the portal: Latin letters and digits, up to 20 characters.
• The Web Plus plan: the "Marketplaces" section is available on it (currently in beta).
• The marketplace connections permission for your role in the workshop.

3. How to get the token

1. Open your Kaspi seller cabinet.
2. Go to "Настройки" → "Токен API" ("Settings" → "API token") and create a token.
3. Copy the token. If Kaspi asks you to request API access first, follow the steps in its guide: guide.kaspi.kz.

Give the token only to the portal. If it leaks, issue a new one and replace it in the connection.

4. Connect in the portal

1. Open "Marketplaces" → "Connections" and click "Connect" next to Kaspi.kz.
2. Paste the token. The store currency (tenge) and time zone (Almaty) are filled in automatically.
3. The portal checks the connection. The token is saved only after a successful check.
4. In "Connection settings" fill in "Points of sale (storeId)": the codes from the Kaspi cabinet, separated by commas if there are several. The price list cannot be built without them.
5. Turn on the kinds of write you need: "Order actions" (accept, cancel, "Handed over"), "Stock" (required for the price list), "Prices" (our price goes into the price list).

Kaspi has no warehouse choice: stock is tied to the points of sale in the price list.

5. Stock and prices: the price list

Kaspi has no stock and price API. Instead, Kaspi downloads an XML file from a link and updates stock and prices once an hour, if the file has changed. So changes do not arrive instantly.

1. In the Kaspi connection settings, find the "Price list link for the Kaspi cabinet" block.
2. Make sure the block shows the status "Price list ready". If not, the reason is written next to it: usually the "Stock" toggle is off or no points of sale are set.
3. Click "Copy".
4. In the Kaspi cabinet: "Товары" → "Загрузить прайс-лист" → "Автоматическая загрузка" ("Products" → "Upload price list" → "Automatic upload"). Paste the link.

What goes into the file:

• Product stock: the quantity of the item in finished goods stock, or the number you set (the "From finished goods stock", "Made to order" and "Manual" modes, as with other marketplaces). "Made to order" with a production time becomes a pre-order of up to 30 days.
• Price in whole tenge: our price if "Prices" is on, otherwise the price currently on the marketplace.
• The points of sale from the settings.

What does not go into the file: products with no stock, no price, a SKU that does not fit Kaspi's rules (Latin letters and digits, up to 20 characters), and duplicate SKUs. The list of skipped products with the reason is shown under the link: open "Left out of the file".

"New link". The link contains a secret. If it ended up where it should not have, click "New link": the old link and this connection's notification address stop working immediately, and you will need to paste the new link into the Kaspi cabinet again.

If you turn "Stock" off, the file stops being served (Kaspi gets "not found") and stock in Kaspi stops updating.

6. Orders

• Currency. Kaspi orders are always in tenge. If your workshop currency is also tenge, the rate is 1 and totals are not converted. Otherwise the total is converted to your workshop currency at the rate fixed when the order was first loaded.
• Stock. If a line is linked to a warehouse item and there is enough of it, the order goes to "Packing" and the stock is written off once. If the order is cancelled, the stock is returned once. An order that arrives already completed does not write off stock.
• Deadline. The date by which the order must be handed over appears in the order card, the calendar and "To-do".

Actions on the order page

All actions go through a queue, and the result and a clear hint if something fails are shown in the "Log".

• "Pack": accepts the order in Kaspi. For Kaspi Delivery the portal then marks the order as packed and sends the number of parcels.
• Waybill: the Kaspi Delivery waybill as a PDF.
• Cancel: pick the reason from Kaspi's list (the buyer refused, could not reach the buyer, item out of stock) and optionally add a comment. Kaspi allows cancelling only an accepted order; otherwise it returns an error, and its text appears in the log.

"Handed over": completing an order in two steps

Kaspi closes an order only with the code that the buyer tells you. The "Handed over" button is visible when the order is waiting to be handed over or is already in delivery.

1. Step 1. Click "Handed over", then "Send code to buyer": Kaspi sends the buyer a code in its app. You see "Code sent to the buyer". You can send the code again.
2. Step 2. The buyer tells you the code. Enter it (1 to 16 characters) and click "Complete order". The order is closed in Kaspi, and the card moves to "Done" after the next sync.

If the button says the order cannot be completed right now, first accept the order and hand it over to the buyer. If writing to the marketplace is off, the portal tells you which toggle to turn on.

7. Limitations

• Stock and prices are updated once an hour; Kaspi does not pick them up faster.
• You cannot get your product list from Kaspi: products in the portal are linked to warehouse items manually.
• You cannot create or change a product card: only in the Kaspi cabinet.
• An order can be completed only with the buyer's code.
• An order can be cancelled only after it has been accepted.
• The live Kaspi cabinet has not been verified yet, so check your first orders carefully.

8. Common errors

9. Security

• The token is stored encrypted and is not shown after saving.
• The price list link contains a secret: do not show it to anyone. "New link" revokes the previous one.
• The buyer's code is not stored: after the order is completed it is erased from the log entry.
• Writing to Kaspi is enabled separately: by default the portal only reads.
• You can pause the connection.
• Permissions: "Marketplace orders", "Marketplace listings", "Marketplace finance".

10. Changes

• 26.10.2026: first version of the guide.