How it works
The whole journey, from the first seller to the delivered order, and what each part does.
This section follows Acme Store from start to end. Each page is one phase: what happens, what you call and which webhooks arrive. To see the resources and how they link, use the Data model.
The three ends
- Your system only talks to marketapi. It calls the API and gets webhooks.
- marketapi keeps the seller's catalog, talks to each marketplace and turns everything into one format. Money is always in cents, dates have a time zone, and statuses have the same names on every marketplace.
- The marketplaces get what marketapi publishes and tell it when something changes there: an order, a question, a price changed in their panel.
The phases
- Set up and connect. You create the account, the API key and the webhook endpoint. Then you create the seller and send a link. The seller authorizes the marketplace, and a Connection is born.
- Catalog and stock. You register what the seller sells: products, variants, kits, photos and tax data. You say where the stock is and who owns it.
- Publish listings. For each marketplace, you build the content and the offer, validate and publish. If the seller already sells there, you import the listings.
- Stay in sync. Stock goes out to the listings on its own. What changes on the marketplace comes back to marketapi. Mismatches become alerts.
- Sell: the order lifecycle. The order arrives, stock is reserved, you send the NF-e, the label comes out and the order ships. Returns and disputes follow the same path.
- Serve buyers. Questions before the purchase, messages after it, reviews and account health.
- Grow and track. Promotions, fee estimates, competitive price, Ads, metrics and finance.
- Capabilities. How to know what each Connection can do before you ask.
Around everything
Five rules apply in every phase:
| Rule | Where to read |
|---|---|
Whatever talks to the marketplace becomes a job (202). | Tracking jobs |
| Every change becomes a webhook, with ids only. | Receiving webhooks |
Every POST accepts an Idempotency-Key. | Idempotency and limits |
Errors have a stable code. | Errors |
The account isolates everything: another account's id answers 404. | Data model |
Your system never waits for the marketplace. A publication, an NF-e or an answer to a question goes into the queue and answers right away with the jobId. The result arrives as job.completed, job.partially_completed or job.failed. If the marketplace limits calls, the job waits for the quota to come back and goes on. It does not fail because of that.