A marketplace API is a software interface that provides a seller with methods to manage products, stock levels, prices and orders directly from their own system, without manual input via the web interface.
How a marketplace API works
APIs operate by exchanging requests and responses over HTTP/HTTPS. The seller sends a request to a specific endpoint with an authentication token, passes data in JSON or XML format, receives the result and processes it within their system.
- Authentication: most commonly OAuth or Bearer tokens. Tokens are time-limited; a typical lifetime is 1 hour (3600 seconds), after which refresh is required.
- Methods: catalogue management (create, update, delete SKUs), stock and price updates, retrieving order lists, confirming shipments, handling returns and tracking.
- Data format: JSON for main operations; some integrations allow CSV for bulk uploads.
- Errors and codes: 200/201 — success; 400 — bad request/data error; 401 — authorization problem; 429 — rate limit exceeded; 500 — internal marketplace error.
- Rate limits: most platforms have rate limits. Typical values: 60–300 requests per minute for a standard account; higher volumes may require a dedicated plan.
Why a seller needs an API
An API saves manual work and reduces errors when selling at scale. Specific benefits for sellers in Kazakhstan using Kaspi.kz include:
- Stock synchronization: with multiple sales points and warehouses, manual tracking leads to mismatches. An API enables near real-time stock updates — for example, when processing 500 orders per day updates can be pushed every 1–5 minutes.
- Automated order processing: instead of downloading orders manually each morning, systems retrieve new orders via API and create tasks in the CRM. For shops with 200–1,000 orders per day this saves dozens of hours weekly.
- Bulk price and promotion updates: changing prices for 1,500 SKUs via the UI can take days; via API you can send batch updates of 100–500 SKUs per request and finish in minutes.
- Status monitoring and logistics integration: receiving shipment statuses and tracking numbers via API reduces customer inquiries and lowers Late Shipment metrics.
Examples of integration with Kaspi.kz (real scenarios)
Kaspi.kz provides sellers with methods to work with catalogues, orders and logistics. Below are real scenarios frequently encountered by sellers in Kazakhstan.
- Example 1 — synchronizing 10,000 SKUs: a large electronics seller needs to keep 10,000 SKUs up to date with attributes, prices and stock. Key steps: map marketplace attributes to internal ones, split uploads into batches (100–500 SKUs), use incremental updates (send only changed fields), and schedule full exports for nightly reconciliation. Consider using background queues and monitoring for failures to avoid long-running API calls.
- Example 2 — high-volume order flow (500–2,000 orders/day): orders arrive around peak times. Best practice is to poll orders via API periodically or subscribe to webhooks if available, automatically create picking tasks in the WMS/CRM, confirm shipments through the API and send tracking numbers back to Kaspi.kz to minimize customer inquiries.
- Example 3 — multi-warehouse management and reservations: when you have several warehouses and pickup points, reserve stock during checkout and update the marketplace after confirmation. For returns, implement endpoints to change item condition and restock or mark as return-in-process.
Practical tips for integration and debugging
- Start with a sandbox or test account. Validate payloads against the marketplace's schema before sending to production.
- Implement idempotency for critical operations (order confirmations, stock writes) to safely retry requests.
- Use background workers and queues for long-running tasks; avoid synchronous heavy operations in web request cycles.
- Log requests and responses (including request IDs and timestamps) for auditing and troubleshooting, but never log secrets or full tokens.
- Monitor metrics: request success rate, average latency, 4xx/5xx error counts, and rate-limit hits. Alert on anomalous spikes.
- When debugging, save failing payloads and full error responses; reproduce locally against the sandbox when possible.
Limits, security and access control
Be aware of both technical and organizational constraints:
- Rate limits and quotas: design your integration with rate limiting and batching in mind. For peak loads use queues and backpressure strategies.
- Least privilege: issue API keys with limited scopes. Separate credentials for read-only operations and write operations.
- Secure storage: store client secrets and tokens in a vault or Secrets Manager. Rotate keys regularly and log access to credential stores.
- Transport security: always use HTTPS. Validate TLS certificates and pin public keys if needed for extra protection.
- Access control: manage user and service access via RBAC; keep an audit trail of who changed integration settings.
Common errors and how to avoid them
- 400 — validation errors: validate payloads on the client side before sending. Maintain schema versions and handle deprecated fields.
- 401 — auth failures: implement token refresh flows and monitor auth errors. Ensure system clocks are in sync to avoid signature/time-based failures.
- 429 — rate limit: apply exponential backoff, honor Retry-After headers and batch changes to reduce call volume.
- 500 — server errors: retry with backoff, but also alert the team when these persist. Keep operations idempotent to safely retry.
- Data mismatch: keep a reconciliation process: regular full exports and compare hashes or row counts to detect drift between systems.
Conclusion
Integrating with a marketplace API like Kaspi.kz is essential for scaling sales, improving accuracy and automating routine operations. Start with small, well-tested flows, add monitoring and retries, and iterate on performance and error handling. With proper design you’ll reduce manual work, improve customer experience and safely grow volumes.
Часто задаваемые вопросы
- How should I update product stock via the API to avoid mismatches between the warehouse and the marketplace?
- Update stock in batches with timestamps: send the current "last_updated" value and use idempotent requests so retries don’t create discrepancies. Implement reservation while an order is being processed and send an update immediately after shipment confirmation; under high load synchronize every 1–5 minutes. Log mismatches and perform periodic full catalog reconciliations.
- How to implement secure authentication and automatic token refresh for marketplace integration?
- Use the marketplace-recommended mechanism — OAuth2 or Bearer tokens — and store client secrets in a secure vault/Secrets Manager. Implement refresh-token exchange when receiving 401 and automate token rotation with error logging; always transmit tokens over HTTPS and restrict key permissions to what’s necessary. Monitor token TTL (typically ~3600 seconds) and schedule refreshes in advance.
- Which API error codes should be handled first and how to react to 429 and 500?
- Handle 400 for data errors (validate payloads before sending), 401 for auth issues, 429 for rate limits and 500 for internal service errors. For 429 apply exponential backoff and respect the Retry-After header; for 500 perform retries with increasing intervals and alert the team if errors persist. For 400 log the response body and fix validation on the sender side. Always implement detailed request/response logging for post-mortems.
- How to reduce the number of API calls during bulk price and stock updates?
- Use bulk endpoints or CSV uploads if the marketplace supports them, and aggregate changes by interval (e.g., minute-based batches). Cache immutable data locally and send diffs — update only changed fields instead of full records. Subscribe to webhooks for marketplace events to avoid constant polling.
- What rate and data volume limits should be considered when integrating with Kaspi and other Kazakhstani marketplaces?
- Typical limits are around 60–300 requests per minute for a standard account; for high volumes request a dedicated plan. Consider payload size limits, pagination when exporting orders and delays for bulk processing; design with retry logic and queues for peak loads. Before deployment agree on SLA and limits with the marketplace to avoid throttling during business hours.
