Skip to content
← All articles
10 min read

Wildberries and Ozon seller API integration: tokens, limits, queues and stock sync

To integrate with the Wildberries and Ozon seller APIs reliably, treat them as slow, rate-limited external systems. Keep tokens with minimal rights, send requests through a queue with backoff on 429, write stocks as absolute values, store raw responses and alert on silence. This article walks through each of those decisions.

Tokens and permissions: what to create and where to keep it

Both marketplaces authenticate with credentials issued in the seller's cabinet. Wildberries uses an API token sent in the Authorization header. Ozon uses a pair: a Client-Id and an Api-Key sent as two headers. Neither is a user login, so a leaked key works from any machine until you revoke it.

Wildberries tokens are scoped by category, for example marketplace, prices, statistics, content, analytics, supply, returns and others, and by read-only or read-write mode. Ozon keys also carry a role. Create a separate token per integration and give it only the categories it needs. A stock synchronizer should not be able to change prices, and a reporting job should not be able to write at all.

Wildberries documentation states that a token lives for 180 days after creation. After that, requests start failing with 401. Put the expiry date in your own settings table and alert a few weeks ahead. An expired token is the most boring and the most common reason an integration stops overnight.

Keep keys in environment secrets or a secret store, never in the repository or in the database in plain text. If several seller accounts connect to one service, store each one encrypted with a record of who added it and when it expires.

  • One token per integration and per environment, never a shared admin key.
  • Minimum categories; read-only wherever you do not write.
  • Expiry date stored next to the token, with an alert before it.
  • Rotation procedure written down: create new, deploy, check, revoke old.
  • A health check that makes one cheap authorized request per account and reports 401 and 403 separately.

Rate limits and 429: why a plain retry loop is not enough

Both APIs limit request frequency, and the limits differ by method group. When you exceed them you get HTTP 429. Wildberries documents response headers for this case: X-Ratelimit-Retry tells how many seconds to wait, X-Ratelimit-Limit is the size of the request burst, and X-Ratelimit-Reset is the time to refill. Retrying earlier just produces new 429s.

We do not quote numeric limits here on purpose. They are set per method, they change, and the only source worth trusting is the current reference for the exact method you call. Read it before you design the schedule, and keep the numbers in configuration, not in code.

The practical rule: do not let application code call the marketplace directly. Put one rate limiter per account and method group in front of the HTTP client. Take the wait from the response headers when they exist, and use exponential backoff with jitter when they do not. Many workers hammering one account at once is the usual way to get a flood of 429s.

Treat 5xx and timeouts differently from 429. They are not a signal to slow down by a known interval, and the request may have been executed anyway. That leads straight to the idempotency question below.

Queues and background jobs instead of calls from request handlers

A user clicking a button in your admin panel must not wait for a marketplace response. Write a job into a table in Postgres, return immediately, and let a worker send it. The details of such workers are in our article on background jobs and queues in Go.

A jobs table with status, attempt count, next attempt time and last error is enough for most sellers. A worker takes a batch with row locking, sends it through the rate limiter, and either marks it done or schedules the next attempt. You do not need a message broker until volume forces it.

Split work by purpose. Orders and stock changes are time-critical. Catalogue, prices and reports can wait. Give them separate queues, or priorities, so a long report download does not delay a stock update.

Pull and push both exist. Orders come in by polling a list method from a saved cursor or timestamp, stocks go out by a write method. Save the cursor only after the page has been processed, and process with overlap, so a crash cannot skip an order.

Idempotency: what happens when a request times out

A timeout does not tell you whether the marketplace applied the change. If you retry blindly, some operations are harmless and some duplicate work. Do not assume the marketplace deduplicates for you unless the method reference says so for that method. The general approach is described in API idempotency and retries.

Design your side so repeating is safe. For stocks this is simple: always send the absolute quantity you want, never a delta. Sending the same number twice changes nothing. Sending a delta twice breaks the stock.

For anything that creates things, such as a supply, a label or a shipment document, keep your own operation record with a unique key. Before sending, check whether that key already has a result. After an uncertain failure, ask the marketplace for the current state of the object rather than creating it again.

For incoming data use your own unique constraint. An order is identified by its marketplace id plus the account, so a second import of the same page updates the existing row and never creates a second order.

Stock synchronization: the part that loses money

Stock sync is the most valuable and the most dangerous integration. Oversell and you get cancelled orders and penalties from the marketplace. Undersell and you lose revenue. Decide first where the truth lives: usually your warehouse system or accounting database, with marketplaces as copies.

Keep an internal table of available quantity per product, and a log of every change with its reason: sale, return, receipt, manual correction. Compute the number to publish from this table, subtract a reserve, and push the result. Record what you last sent to each marketplace, so you push only what changed and can explain any discrepancy later.

Updates should be batched. Both APIs accept several products per request and limit the batch size and request rate. Check the exact figures in the method reference. Collapse repeated changes of one product into one pending value, because only the last quantity matters.

Do a full reconciliation on a schedule: read stocks back from the marketplace and compare with what you believe you sent. Event-based pushing drifts over time, and the periodic comparison is what catches it. For the bigger picture of connecting to accounting systems see 1C and marketplaces.

  • Single source of truth for quantity, with a change log.
  • Absolute quantities only, never deltas.
  • Reserve buffer per product or per marketplace.
  • Debounced batches: last value wins.
  • Scheduled reconciliation against marketplace data.
  • Manual pause switch per account for emergencies.

Errors, raw responses and monitoring

Classify errors, because each class needs different handling. 400 is your bug or bad data: do not retry, show it to a person. 401 and 403 mean token or rights: stop the queue for that account and notify. 429 means wait. 5xx and timeouts mean retry with backoff. Never treat all of them as a single failure.

Store the raw response body of important calls, with the request id, account, method, status and time. Marketplace documentation and real answers drift apart, and a field you do not map today may matter next quarter. When a seller asks why a stock was wrong at 14:05, the stored request and response answer it in a minute.

Keep raw data in a separate table with a retention period, and mask secrets. Store the original JSON next to your parsed columns, so you can reprocess history after you fix a mapping bug without calling the API again.

Monitor outcomes, not only process health. Useful signals are: the age of the oldest unprocessed job, the share of 429 and 5xx answers, the time since the last successful order pull per account, and the number of products whose published stock differs from internal stock. Silence is the worst failure, so alert when nothing arrives. More on this in software maintenance after launch.

  • Age of the oldest pending job.
  • Share of 429 and 5xx per account and method.
  • Time since last successful order pull.
  • Count of stock mismatches found by reconciliation.
  • Days to token expiry.

When you do not need your own integration

If you sell on one marketplace, your catalogue is a few dozen items and you update stocks by hand once a day, a spreadsheet and the cabinet are enough. Custom code adds maintenance cost you will not recover.

Ready-made seller services and connectors cover standard needs well: unified stock across marketplaces, order lists, basic reports. If one of them fits your process and the price per month is acceptable, use it. Your own code starts to pay off only when the logic is not standard: unusual reserves, bundles, several warehouses, your own accounting system.

Also check whether your accounting or ERP system already has an exchange module for marketplaces. If it does, evaluate it before writing anything, and read the comparison in the 1C and marketplaces article.

When to bring in a contractor

It makes sense when several accounts or marketplaces must share one stock, when orders have to flow into your own CRM or warehouse system, or when mistakes already cost money through oversells and cancelled orders. It also makes sense when nobody on your team can maintain a queue worker and watch it.

Ask for the things in this article: token scoping, rate limiter, jobs table, absolute stocks, raw response storage, reconciliation and alerts. A contractor who cannot explain how a timeout is handled has not built this before. Our system integration work follows exactly this approach, and the design principles are in API design for integrations.

Keep access in your hands: tokens in your accounts, repository in your organization, documentation of runbooks. The integration should keep working if you change the contractor.

Questions

FAQ

Didn't find an answer — ask on the call or in Telegram.

How do I connect to the Wildberries API?

Create a token in the seller cabinet with only the categories you need, and send it in the Authorization header. Documentation says a token lives for 180 days, so track expiry. Call the host of the method group you use, as listed in the reference, and handle 401, 403 and 429 separately.

How does the Ozon Seller API authorization work?

You generate a key in the seller cabinet and send two headers on every request: Client-Id and Api-Key. The key has a role that limits available methods. Use a separate key per integration, store it as a secret and revoke it at once if it leaks.

What should I do when the Wildberries API returns 429?

Stop sending to that method group and wait. Wildberries returns X-Ratelimit-Retry with seconds to wait, plus X-Ratelimit-Limit and X-Ratelimit-Reset. Read them, delay the job, and add jitter. Retrying early only produces more 429 responses. Keep limits in configuration, not code.

How do I synchronize stocks between Wildberries and Ozon?

Keep one internal quantity table with a change log, compute the published number from it, and push absolute values in batches to each marketplace. Remember what you sent, collapse repeated changes, and run a scheduled reconciliation that reads stocks back and compares them with your records.

Do I need a queue for the marketplace API?

Yes, once more than one process or user triggers requests. A queue gives you one place for rate limiting, retries, priorities and an audit trail. A jobs table in Postgres with a worker is enough for most sellers; a separate broker is rarely needed at the start.

Should I store raw API responses from Wildberries and Ozon?

Yes, for important calls. Keep body, status, method, account and time, with a retention period and masked secrets. It lets you explain past errors, reprocess history after fixing a mapping, and notice fields that appear in answers before they appear in documentation.

Related service

CRM, ERP and API integrations built for your workflows

When teams copy data between systems by hand, delays and mistakes become part of the process. We automate the exchange and make its status visible to the people running it.

Learn about the service
Other articles
Contact

Shall we discuss your task?

Thirty minutes on a call — and you understand the architecture, timeline and engagement format. No obligations.

Or message us on Telegram →Follow our Telegram channel →

Enter your Telegram or email so we can reply.

We reply within 15 minutes.