Definition
Exporting and importing a catalog is the process of transferring product data between a seller's accounting system and the Kaspi.kz platform as files or via API to create and update product cards, prices and stock levels.
How the process works: formats, stages and scenarios
The process includes three main stages: preparing the source file, transmitting it to the platform and validating the results. Technically this is implemented in four ways:
- Manual upload through the Kaspi seller cabinet (Excel or CSV) — an easy start for a small assortment.
- Bulk export/import on a schedule via FTP/HTTP with CSV or XML using a predefined template.
- API integration — longer setup, provides prompt synchronization of stock and prices.
- Intermediate integrators or ETL tools (for example, AWW) — automate transformation and validation of data between 1C, warehouse and Kaspi.
A typical file structure for bulk upload includes fields: SKU, Name, Article, Price, Stock, Brand, Barcode (EAN), Category, Image URL, Description. Before sending, the file should be encoded in UTF-8 or CP1251 depending on the seller cabinet requirements.
After upload, the platform validates according to a set of rules: SKU uniqueness, correct category, price format compliance, availability of the image URL. The validation result is returned as a report with counts of accepted and rejected records and descriptions of errors.
Why this is needed for the seller: concrete reasons and examples of impact on sales
Working with the catalog directly affects the visibility and conversion of product cards. Practical benefits:
- Stock synchronization prevents order cancellations. Example: a seller with 2,000 SKUs updated stock manually once a day and had 3–5% cancellations due to shortages. After automatic export via API every 15 minutes, cancellations dropped several times.
- Fast price updates during promotions. Example: when launching a promotion a seller with 1,200 SKUs changed prices in bulk in a file and uploaded in 15 minutes, whereas manual edits would have taken 2 days and caused lost margin.
- Product quality: correct attributes and good images improve CTR and conversion. A seller who added 3 images and detailed characteristics for 500 SKUs saw an increase in conversion in visible search results.
- Labor savings: bulk upload saves staff time. Example estimate: updating 5,000 items manually may take several working days; automated upload fits in hours.
In addition, a properly prepared export is needed for fulfilment operations (FBS/FB services), participation in platform promotions, analytics and for maintaining competitiveness in the Buy Box.
Examples of common errors and situations on Kaspi.kz
Common issues sellers encounter during export/import include:
- Incorrect category mapping: items are placed in the wrong category or categories are specified by name instead of using platform IDs — leads to rejection or low discoverability.
- Missing or invalid EAN/barcode: required for many categories; records without valid EAN are rejected or marked as incomplete.
- Duplicate or non-unique SKU: creates conflicts and incorrect stock updates.
- Wrong price format or currency mistakes: decimal separators, wrong currency code (Kaspi.kz uses KZT for Kazakhstan listings) — causes validation errors or incorrect pricing.
- Image link problems: inaccessible URLs, HTTP instead of HTTPS, or images behind auth — images are not imported and cards lose attractiveness.
- Missing mandatory attributes per category (size, color, country of origin, etc.) — platform rejects records or marks them as incomplete.
- Encoding issues (CP1251 vs UTF-8) that corrupt Cyrillic names and descriptions.
- Partial acceptance: platform accepts some rows and rejects others; if not handled correctly, this leads to inconsistent catalog state.
Examples of situations on Kaspi.kz:
- A seller uploaded a file with semicolon-separated values but the seller cabinet expected commas — all lines were parsed incorrectly and SKU fields shifted.
- Bulk price update with wrong decimal separator increased prices tenfold due to misplaced point/comma, leading to lost sales until corrected.
- During a promotion, delayed stock sync caused several orders to be cancelled because the product was marked as available while actual stock had run out.
Practical tips and a checklist for correct export and import
Checklist before the full upload:
- Backup the current catalog and keep versioned source files.
- Use the platform template and required field names/IDs; prefer numeric category IDs over text names.
- Set and confirm the correct file encoding (UTF-8 or CP1251) and field delimiter.
- Validate a small sample (10–100 rows) before the full import.
- Ensure image URLs are public (HTTPS) and return HTTP 200.
- Include mandatory attributes for each category to avoid rejections.
- Monitor validation reports and fix only rejected rows for re-upload where possible.
- Automate repetitive transformations (price rules, SKU generation, category mapping) with scripts or ETL tools like AWW.
- Log all uploads and track the result identifiers from the platform for troubleshooting.
- Schedule regular incremental syncs for stock and prices; keep a fall-back manual process in case of integration failure.
Technical points and recommendations for integration
When configuring integration, pay attention to:
- API rate limits and batching: respect platform throttling, batch updates to reduce overhead and implement exponential backoff on errors.
- Authentication and security: use secure tokens, rotate keys and transmit all data over HTTPS.
- Idempotency: design jobs so repeated requests do not produce inconsistent states (use timestamps, update flags or upsert logic).
- Field formats and lengths: trim long descriptions, keep attribute formats consistent with platform requirements.
- Error handling: parse validation reports automatically, generate actionable tasks and retry only corrected rows.
- Data normalization: harmonize units (e.g., weights, sizes), currencies (KZT) and measure separators according to Kaspi expectations.
- Testing: run integration in a sandbox or with a limited subset, verify edge cases like out-of-stock transitions and price promotions.
- Monitoring and alerts: set up alerts for failed jobs, high rejection rates or sudden drops in accepted records.
- Consider using integrators/ETL tools (AWW) to map 1C, warehouse systems and other sources to Kaspi formats and to handle scheduled transforms.
- Plan for localisation specifics in Kazakhstan: language, measurement units, taxes and required legal attributes.
Brief summary and a practical tip
Correct export and import of your catalog is the foundation for stable sales on Kaspi.kz: it ensures accurate availability, correct pricing, better product presentation and eligibility for promotions and fulfilment. Start small, automate what repeats, and monitor validation reports constantly.
Practical tip: before any large change, run a short A/B test — upload a representative sample of SKUs with the full set of attributes and images, measure the effect on visibility and conversion, then scale the process with the same validated template.
Часто задаваемые вопросы
- Which encoding and file format should I use for bulk upload to Kaspi.kz?
- Use the format supported by the seller cabinet — usually CSV (comma or semicolon), Excel (.xlsx) or XML following the platform template. For encoding, UTF-8 is most commonly required, but some seller cabinets accept CP1251 — check the specific interface requirements before exporting. Incorrect encoding corrupts names and descriptions, so always test on a small sample.
- What should I do when there are errors in the validation report (for example “incorrect category” or “missing EAN”)?
- Download the detailed report and fix records by the row numbers listed in the error file; correct the source file or the mapping in your integrator and re-upload only the corrected rows. If the platform accepted part of the records, synchronize statuses and check dependencies (for example mandatory attributes per category). For mass fixes, automate corrections with a script or an ETL tool to avoid manual mistakes.
- How often should I synchronize stock and prices and which method is better — FTP, API or manual upload?
- For a small assortment, manual or scheduled FTP/HTTP updates once a day are sufficient. For dynamic inventory and prices, API integration with real-time updates or updates every few minutes is recommended. API provides lower latency and fewer conflicts over stock, while FTP/CSV is suitable for less critical items. Choose the method based on volume, turnover speed and the capabilities of your accounting system.
- How should I transfer images correctly and what to do if I get an “image link inaccessible” error?
- Provide direct public HTTPS links to images and ensure the URL returns HTTP 200 and the file is accessible without authorization. Check Kaspi's requirements for image format and size and, if necessary, host files on your CDN or a storage service with persistent links. If a link is inaccessible, upload the image in the seller cabinet or fix the path and re-run validation.
- How to correctly map categories and mandatory attributes when bulk uploading the catalog?
- Use category identifiers from the Kaspi directory, not only text names, and prepare a mapping between your assortment and the platform's category tree. Fill mandatory attributes (size, color, country of origin, etc.) for each category; otherwise records will be rejected. For large catalogs, automate mapping in an ETL tool and test on a sample before a full upload.
