Topic
What Amazon, Etsy, Walmart, and eBay actually give you — auth models, data gaps, and the integration problems that only show up once you're multi-marketplace.
5 guides, written from real builds.
Marketplace integration is reconciliation work: someone else's model of an order, a shop, a buyer and a credential, mapped onto yours. The second marketplace is where it starts to hurt, because the abstraction you wrote for the first has assumptions baked into it — that a stored refresh token stays valid, that a buyer has a phone number, that orders only ever come into existence — and the next marketplace does not share them.
If you are building for more than one marketplace, the four auth models set side by side is the place to start: Amazon's roles and second token for buyer PII, Etsy's mandatory PKCE, Walmart's missing refresh token and headers in place of an Authorization header, eBay's RuName where a redirect URL should go — and then what all of that means for your account schema.
Etsy earns its own guide. Its refresh token rotates on every refresh and kills the previous one, so one failed write or two overlapping syncs can disconnect a shop for good, with only a human re-login to bring it back. Why a working Etsy integration rots after a few weeks covers the crash window, the race between a scheduled pull and a manual Sync now, the fix (cache the access token, refresh only near expiry, lock per shop), and the scope-frozen-at-consent rule that turns adding write access into a re-login.
If you are pushing marketplace orders into a carrier, you will hit a required consignee phone that the order payload does not contain — Etsy and Walmart do not return one. What each marketplace actually returns in place of a buyer phone sets out the three options, which one to pick, and why the fallback number's country is not a detail.
If you are building support tooling, stop looking for the endpoint that returns what buyers wrote — Amazon's Messaging API only sends. The email-relay pattern for ingesting buyer messages explains why the read side does not exist, the wrong turns worth skipping (Notifications, scraping), how to match a message to its order and seller account, how to avoid processing the same email twice, and where you cannot reply.
The last one is structural: every row looks fine and the total is wrong. Rows for orders that no longer exist upstream is about the gap in upsert-only syncs — why the sync cannot see it, why a single 404 is a hypothesis rather than a verdict, why you retire rather than hard-delete, and the sibling bug of pulling an incremental sync on created date.
These are the problems that only show up once you are multi-marketplace, which is why they sit in one place here. Building integrations like these is what I do.
Marketplace APIs
If you're integrating more than one marketplace, the authentication layer is where your abstraction breaks first. All four use OAuth 2.0 on paper, and no two behave the same way in practice. Here's what actually differs — token lifetimes, rotation, credential ownership — and how those differences should shape your database schema.
Marketplace APIs
Your carrier API rejects the shipment because the consignee phone is missing, and the order payload simply doesn't contain one. That's not a bug in your integration — Etsy and Walmart don't return a buyer phone at all, and Amazon's is a relay number. Here's what each marketplace actually gives you and how to satisfy the carrier without inventing data.
Marketplace APIs
Your Etsy integration works for weeks, then a shop quietly stops syncing and only a human re-login fixes it. That is the rotating refresh token: Etsy issues a new one on every refresh and kills the old, so a crashed write or two concurrent syncs orphan the shop. Here is the mechanism, the scheduled-vs-manual sync race, and the cache-plus-lock fix.
Marketplace APIs
You went looking for a Selling Partner API endpoint that returns the messages buyers send you, and there isn't one — Amazon's Messaging API only sends. Here's why the read side doesn't exist, and the email-relay ingestion pattern that gets buyer messages into your own app instead, matched to the right order and the right seller account.
Marketplace APIs
Marketplace syncs are almost always written as upserts, which means they can create and update rows but can never remove one. When an order disappears upstream — a receipt that starts 404ing, an order that ages out — it lives in your database forever, quietly inflating counts and revenue. Here's how to detect phantoms without deleting real data by mistake.
Shahzeb Khan runs Databaaba, a one-person studio that builds marketplace apis integrations for sellers, agencies, and software teams. Every guide here came out of a real client build.