API Versioning, Rate Limits, and Keys for Marketplace Sellers

API versioning is the practice of releasing changes to an API as separate versions, each with a date until which it keeps working. A seller's software uses your marketplace API to send you offers and stock levels and to collect orders, with no one clicking anything.
Other companies depend on your API from the day the first seller connects to it. Every change you make to it gives work to companies that don't report to you. When they fall behind, the lost sales show up in your numbers.
Before launch, you need a policy on how often you may break the API. You also need rules for how many calls each seller may make and for how you issue and cancel API keys.
This article breaks down:
- What does a breaking change to your marketplace API cost your sellers?
- Which API versioning strategy should a marketplace choose?
- How do you set rate limiting when 300 sellers share one API?
- How should a marketplace issue and revoke API keys for sellers?
Key insights
- A breaking change to your marketplace API costs your sellers about 210 person-days for a fix that takes you one day. If 10% of sellers fall out of sync for two weeks, you lose €60,000 of commission, and they lose €440,000 of revenue.
- The API versioning strategy a marketplace should choose is an explicit version with a parallel window, backed by a written deprecation policy. You also need a count of the sellers still on the old version, or you won't switch off a version that carries €180,000 of monthly commission.
- To set rate limiting for 300 sellers, size the limit for the peak hour and cap each seller's share of it. Sellers with 200,000 offers make 33 calls an hour on average and 400 in the morning peak.
- A marketplace should issue API keys with a written list of what they can reach, and it should let two keys work at once during rotation. A seller's keys have to stop working the moment the account is suspended or closed.
What does a breaking change to your marketplace API cost your sellers?

A breaking change is a change that forces sellers to rewrite their integration before it works again. Renaming a field, adding a required field, and changing an order status all count.
This chapter uses the series' standard example, and every number in it is hypothetical. Your marketplace has 300 sellers, 200,000 active offers, and 10,000 orders a month. A €1,000 cart and a 12% commission give you €10 million of GMV a month.
Sellers reach your API by three routes, and the chapter on the marketplace seller panel describes each of them. In this example, 210 sellers work through integrators, and 60 use the panel and file uploads. The remaining 30 have their own integration.
Say you change one field, and the fix takes your team one day. Each of the 30 sellers with their own integration spends three developer days on it. That's 90 days of work.
About a dozen integrator companies each spend ten days on a release and a test. That adds another 120 days.
Your one-day fix costs 210 person-days outside your company. That's close to a year of one developer's work, spread across about forty companies. None of them had the work in their plan for the quarter.
Some of them won't finish in time. Suppose 10% of your sellers stop updating prices and stock levels for two weeks. They carry 10% of your GMV, or €1 million a month.
Two weeks of that is €500,000 of GMV. You lose €60,000 of commission, and the sellers lose €440,000 of revenue.
Treat the number of breaking changes as a budget line. Set it in the open at one a year, two, or four. Going over it then needs a board decision.
What should a marketplace API integration cover besides offers and orders?

Sellers ask what your API can do. Also ask what it can't do. Someone on your team does each missing operation manually.
Some platforms' APIs handle only offers and orders. Commission setup, promotions, seller registration, seller users, and payouts stay in a console where someone clicks through them. Other platforms let you change all of these through the API.
A change to the commission grid for 300 sellers, with five category rows each, means 1,500 edits. Each edit takes two minutes, and the whole change takes 50 hours.
You lose more than a week of one person's time every time you correct your rates. If the console doesn't record who changed what, you have to reconstruct every change before you can check rates against signed contracts. The chapter on commission rate drift covers that check.
Before you sign, write down six objects you want to change in bulk for a marketplace API integration:
- Commission rates and their negotiated exceptions.
- Promotions that sellers join or fund.
- Seller registration and verification.
- Users inside a seller account.
- Seller payouts and their release.
- Catalog rules for categories and attributes.
Next to each object, mark whether the API can change it without a person in the loop. Then convert every "no" into hours per month.
Which API versioning strategy should a marketplace choose?

When you release a version of your API, you promise that what works today keeps working until a date you name.
Large business software vendors give the longest notice. They announce a breaking change 12 to 24 months before it takes effect and write the period into the contract. The IT team at your largest seller will measure you against that notice period.
The Sunset HTTP header, defined in RFC 8594, lets your API return the shutdown date in every response. The seller's developer then sees the date in their logs, without searching for an email from last year.
Vendors keep the promise in three ways. Each way puts the cost of a change on a different party.
1. Explicit version with a parallel window
You release the new version next to the old one and give the old one a shutdown date. Until that date, you maintain two APIs.
Choose this API versioning strategy when your large sellers have their own IT teams. You pay for the window, and the sellers get a fixed date to plan around.
2. No versions, additions only
You only add to the API and never remove or rename anything. The seller doesn't touch their integration for years.
Your API still carries every field you added five years ago. This way fits a narrow API that rarely changes.
3. No versions, with deprecation notes
You mark a field as retired in the documentation, with a date and a replacement. Each seller who connected has to keep up with the changes alone.
It's the cheapest way for the vendor. Your 300 sellers pay the most under it, because each of them has to follow someone else's technical document. No one should choose it on purpose.
How do the 3 API versioning strategies compare?
The table compares the three ways on the same points. Start with the first row, because who pays for a change shapes most of the other answers.
What does each strategy decide? | Explicit version with a window | No versions, additions only | No versions, deprecation notes |
|---|---|---|---|
Who carries the cost of a change (party) | you, for the length of the window | you, with no end date | the seller and the integrator |
How many APIs you maintain at once (count) | 2 during the window | 1, and it keeps growing | 1 |
Breaking changes you can realistically make (per year) | 1 to 2 | 0 | as many as the sellers will accept |
Count of sellers left on the old version (report) | required | not needed | needed, and rarely there |
When to choose it (situation) | large sellers with their own IT | a narrow, stable API | never on purpose |
What belongs in an API deprecation policy?
API versioning best practices start with a deprecation policy you can show in writing. It answers five questions:
- What you count as a breaking change.
- How long the old version stays available.
- Where you announce the change.
- Who counts the sellers still on the old version.
- What you do with the sellers who don't migrate in time.
You can settle the first four in one meeting. The policy holds only if you answer the fifth.
If you don't count who is left, you won't keep the shutdown date. Suppose 8% of your sellers miss the deadline. That's 24 companies, and they carry 15% of your GMV, or €1.5 million a month.
Switching them off costs you €180,000 of commission a month. You won't do it, and the date slips. Sellers then stop believing your deadlines.
You have three ways out:
- Extend the deadline for everyone, and pay to keep the old version alive with no end date.
- Switch off on schedule, and lose the GMV of the sellers who missed it.
- Give individual extensions, and pay for them in support hours.
Only individual extensions have an end date. Each exception needs a named seller, a new date, and no automatic renewal. That's the default to pick.
The new version is sometimes narrower than the old one. A published comparison of two versions can show operations that exist only in the version being retired, such as bulk stock updates. The seller would lose a function they use and refuse to migrate, with good reason.
Publish a full comparison of both versions before you announce a window. Keep the window closed while any row says "not available".
How do you set rate limiting when 300 sellers share one API?

A rate limit caps how many calls each seller can make to your API. It splits the calls your API can take among 300 sellers who don't know about each other.
The price or stock level of each of your 200,000 offers changes twice a day on average. That's 400,000 updates a day. Sent in batches of 500 items, they make 800 calls a day, or 33 an hour.
Sellers don't spread those calls evenly. Half of the catalog traffic lands in a single hour, because sellers synchronize in the morning or right after a promotion starts.
In that hour, you get 400 calls instead of 33. That's a twelvefold peak.
If you set the limit to the average, sellers get blocked in the peak hour. If you set it to the peak, one seller can use up the whole pool.
Vendors apply limits at three levels at once. One limit sits on each seller's credentials, another on each sending address, and a third on the whole platform.
The platform ceiling is sometimes lower than the sum of the limits for individual sellers. Two aggressive sellers can then take the capacity from everyone else.
When your API refuses a call, the seller's software has to be able to read the refusal. It has to learn that it hit a limit and how long to wait before the next try.
The HTTP standard defines a separate "too many requests" response, status code 429. The waiting time in it is optional. If your API leaves it out, an integrator finds your limit by trial and error.
You have four decisions to make about rate limiting:
- Whether each seller gets their own limit or all sellers share one pool.
- Who approves a higher limit for one seller.
- Whether traffic over the limit gets refused or queued.
- Whether you can see which sellers use up the pool.
A wrong limit costs you canceled orders. A seller who can't push stock levels sells goods they don't have.
If 2% of your 10,000 monthly orders end that way, you get 200 cancellations a month. They cost €200,000 of GMV and €24,000 of commission. The chapter on inventory synchronization covers how stock levels travel.
How should a marketplace issue and revoke API keys for sellers?

API keys are passwords for a program. People logging in are a separate topic, and the chapter on SSO vs MFA covers it.
For API keys, you decide who issues them, what they can reach, and how you take them back.
Keys on the better platforms carry an explicit list of the resources they reach, each with a permission level for reading, writing, or irreversible operations.
Keys issued for posting offers don't reach payouts. When a call fails, the error should name the missing permission. The seller's developer then fixes it alone and doesn't open a ticket that costs your support team fifteen minutes.
In some products, permissions are fixed inside the keys. To change them, you issue new keys, and the seller installs them. Each permission you split out then means more forced swaps.
If a seller can't hold two live keys at once, every rotation means downtime. Sellers then stop rotating their API keys.
If all 300 sellers rotate their keys once a year, you handle 300 swaps. That's more than one per working day.
Each swap takes fifteen minutes of support, or 75 hours a year. That's bearable until a swap needs a click on your side. Every rotation then waits in your support queue.
One rule isn't negotiable: a seller's keys stop working together with their account. A seller who is suspended for poor quality metrics can otherwise keep posting offers through the API. So can a seller in offboarding, who can also keep pulling data.
On paper, neither of them sells with you anymore. The chapter on the marketplace audit log covers what you record about each use of the keys.
How does a seller sandbox shorten the time to a first sale?

A sandbox is a separate copy of your platform for testing, and no order in it reaches a real buyer. The seller can make mistakes there.
You have one more environment to maintain. The chapter on configuration management covers how you set it up.
A seller makes no sales while they test in the sandbox. A seller with their own integration reaches a first sale in 15 working days when three things hold.
The sandbox holds production-like data, and the documentation is complete. The seller also issues their own keys without a ticket.
When they test on production and get keys through a ticket, the same seller needs 35 days. That's 20 working days more.
Your average seller does €33,333 of GMV a month, or €1,587 per working day. Twenty days cost €31,750 of GMV and €3,810 of your commission per seller.
Sixty new sellers a year bring that to €229,000 of commission. New sellers sell below average, and half of that figure is closer to the truth.
About €100,000 of commission a year depends on your sandbox and your documentation. Settle three things about the sandbox before launch:
- It holds production-like data and no real personal data. The chapter on marketplace GDPR covers how to strip it.
- Sellers can test your change in it before the change goes live. If they can't, the migration window gives them a deadline and no way to prepare.
- You know what a sandbox refresh deletes. In some products, the integration settings disappear with it.
Documentation costs you money too. A support bot that sends sellers back to the documentation can name paths that don't exist.
Suppose 30 sellers with their own integration each ask eight questions during rollout. At half an hour per question, that's 120 hours. It adds up to a month of one person's time over a year, and no one has it in their budget.
What does API versioning change in your marketplace?
The number of breaking changes you allow decides how fast the whole platform can change. If you can afford two a year, a new required catalog field and a new order status compete for the same window.
Each seller picks their route, and you maintain all three routes. A change to the integrator route reaches 210 sellers at once.
When you change the rules for sellers, you may have to announce it under the law as well as in a technical notice. The chapter on P2B regulation covers how you have to announce it.
Two technical decisions sit next to this one. The chapter on webhook integration covers how systems tell each other about a change. The chapter on idempotency covers what happens when the same call arrives twice.
How do you check API versioning with a vendor?
Ask these six questions, and ask to see each answer on screen:
- Can you show me your deprecation policy in writing, with the definition of a breaking change, the length of the window, and the place where you announce it?
- Can you show me a report of how many sellers are on the old version today and how much GMV they carry?
- Which of my six bulk objects can I change through the API, and which ones need someone to click?
- What happens when I go over the rate limit in front of you? Does the refusal say it's a limit and how long to wait, and can I see who uses the pool?
- How do I change the permissions of API keys? Do I edit them or replace them? Can two keys work at once, and do a suspended seller's keys stop working right away?
- Can I issue sandbox keys the way a new seller would, and how many steps does it take?
Count every step in the last answer that needs a ticket to you. Each one adds about two days to the seller's calendar.
Which mistakes do operators make with a marketplace API for sellers?
Each of these mistakes shows up months after the decision that caused it. By then, sellers and their integrators have already built on top of it.
1. Changing the API without counting who has to adapt
Your fix takes a day and sets off more than 200 person-days outside your company. Sellers fall out of sync, and you see it as a drop in offer quality.
2. Shutdown date without a count of who is left
Switching off turns out to cost €180,000 of commission a month, so the deadline goes away. Sellers stop taking your next announcements seriously.
3. Migration window opened before the new version caught up
The seller would lose a function they use, and they refuse to migrate. You lose a quarter and your credibility with them.
4. Rate limit set to average traffic
Everything works outside the peak. You need current stock levels most in the peak, and the wrong limit costs you canceled orders there.
5. API keys that outlive the seller's account
A suspended seller still sends offers through the API. You find it at an audit and explain it to a buyer.
What do you still have to settle about your marketplace API?
This article leaves five neighboring decisions to other chapters:
- The route a seller picks, in the chapter on the seller panel.
- Events between systems, in the chapter on webhooks and polling.
- Repeated calls, in the chapter on idempotency keys.
- Environments, in the chapter on development, staging, and production.
- Logins and roles for people, in the chapter on SSO and MFA. API keys are credentials for machines.
This article isn't legal advice. Take three areas to your lawyer:
- Whether a change to the rules for sellers needs a set form and notice period. The chapter on platform-to-business rules covers the mechanism.
- Personal data in test environments, under the rules on data protection.
- Security requirements for digital services, including the record of who used which API keys.
All the numbers above are hypothetical. In your first quarter, measure how many sellers and how much GMV sit behind each version of your API. If you don't know that number, sellers won't believe the date in your deprecation policy.
Summary: How do you change a marketplace API without losing your sellers?
You change a marketplace API without losing sellers by budgeting for breaking changes and versioning them openly. A one-day fix on your side costs your sellers 210 person-days. An explicit version with a parallel window, a written deprecation policy, and a count of who is left keeps that cost under control.
Size rate limiting for the peak hour, when 400 calls arrive instead of 33. Cap each seller's share of that hour.
Issue API keys with a written scope and let two of them work at once during rotation. Tie them to the seller's account. A suspension then switches them off too.
Building a marketplace that hundreds of sellers connect to through their own software?
Frequently asked questions on API versioning
What is API versioning?
API versioning is the practice of releasing changes to an API as separate versions, each with a date until which it keeps working. It lets the software that connected to the old version keep working while its owner migrates. Your sellers and their integrators own that software.
What are API versioning best practices for a marketplace?
API versioning best practices for a marketplace start with a written deprecation policy and a parallel window for the old version. Announce breaking changes 12 to 24 months ahead and return the shutdown date in every response. Count the sellers and the GMV still on the old version before you switch it off.
What is rate limiting in an API?
Rate limiting is a cap on how many calls one client can make to an API in a period of time. It splits the calls your marketplace API can take among all your sellers. Set it for the peak hour, and make every refusal say how long the seller should wait.
Ready to build?
We build marketplaces that give sellers a stable API, with versions, rate limits, and keys you manage without a support ticket.