Scopes and rate limits
A key carries only the scopes it was granted. Ask for what the integration uses; the consent page lists each one in plain words and shops refuse broad requests.
Scope
| Scope | Allows |
|---|---|
| offers.manage | Match or propose products, create and update offers and prices. |
| catalog.media | Import images by URL or signed upload, attach them to products. |
| inventory.adjust | Set available stock per SKU, in bulk or one by one. |
| orders.read | Read Wamia orders, slices and their status history. |
| orders.fulfil | Acknowledge slices, mark them prepared, declare inbound shipments and book appointments. |
| returns.handle | Read RMAs and record the shop’s decision. |
| finance:read | Balance, payouts and statements. |
| performance:read | Shop insights: sales, Buy Box share, defects. |
| settings:write | Shop settings the plugin mirrors (handling time, holidays). |
| webhooks.manage | Create, test, pause and replay webhook endpoints. |
Rate limits
Four token buckets per key, refilled continuously and shared across every API instance: reads, writes, bulk writes and a daily budget. Connector keys get the larger budget; custom keys start at the smaller one and shops can request more.
| Name | Custom key | Connector key |
|---|---|---|
| Reads | 60 per minute | 600 per minute |
| Writes | 60 per minute | 300 per minute |
| Bulk writes | 5 per minute | 20 per minute |
| Daily budget | 20,000 per day | 200,000 per day |
A bulk mutation counts once against the bulk bucket whatever its size, and once per item against the daily budget. When a bucket is empty the call answers
RATE_LIMITED with extensions.retryAfterSeconds; honour it and add jitter.Batch limits
- Up to 200 items per call for
apiUpsertOffers,apiDeclareStocksandapiMatchListings; beyond that,BATCH_TOO_LARGE. - Up to 20 image URLs per
apiIngestMediaFromUrlscall, 10 MB per image, 12 images per product. - Prices in millimes as integers; quantities as integers up to 10 000 000.
- Cursor pages return at most 200 items;
nextCursoris opaque — never build one yourself. - Idempotency keys are 8–128 characters and kept for 7 days; a replay inside that window returns the stored answer.
- At most 10 webhook endpoints per key.