Capabilities
How to know what each Connection can do, and what happens when it cannot.
Each marketplace does different things. One takes coupons, another does not. One lets the seller start a conversation, another only lets them reply. marketapi does not hide this: each Connection tells you, operation by operation, what it can do.
One capability per operation
Every route that talks to the marketplace depends on a capability: listings.publish, inventory.publish, orders.import, invoices.submit, questions.answer, promotions.manage and so on. Read the Connection's capabilities before showing an action in your app:
status | Means | What the route answers |
|---|---|---|
available | the Connection can | goes on as usual |
unsupported | the marketplace does not offer it | 422 CAPABILITY_UNSUPPORTED |
not_granted | the marketplace offers it, but a permission is missing | 403 CAPABILITY_NOT_GRANTED |
The error comes before the job, with details.marketplace and details.capability. On a batch route that touches several Connections, the job is created and only the item of the Connection without the operation fails.
With not_granted, ask the seller to connect again, granting the missing permission.
Marketplace facts
Besides operations, the Connection carries declarations: facts that change how an operation behaves.
| Declaration | What it says |
|---|---|
inventory.scope | whether stock belongs to each offer line or is shared by offers |
inventory.kitStockComputedByMarketplace | whether the marketplace computes a kit's stock on its own |
listings.offersPerMarketplaceProduct | whether the same content takes one offer or many |
invoices.scope | at which level the NF-e is delivered: order, package or delivery |
timezone | the time zone of dates the marketplace sends without one |
pii.retentionMaxDays | how long buyer data may be kept |
What only one marketplace has
Part of each marketplace has no match in the others: its own shipping type, a price automation. For that there are two paths, both safe:
marketplaceOptions: options of one marketplace, kept per marketplace, on the listing and on the Connection. They go along with the publication.- Native operations: the Connection lists the marketplace's own operations that marketapi exposes, with the effect and permission of each. You run them in a job. It is not a proxy: only what is on the list exists.
Call limits
Each marketplace limits how many calls per minute an app can make. marketapi respects that limit for you. When the quota runs out, the job waits and goes on later. It does not fail because of that.
In the documentation
Every endpoint page that talks to the marketplace shows, at the top, the support of each marketplace. The full table is in Marketplace support. It is the product overview. The decision for a specific Connection is always the answer of its capabilities.
Endpoints in this phase
| To | Endpoint |
|---|---|
| See what the account can do | Capabilities |
| Marketplace options | On the Connection · On the listing |
| Native operations | List · Get · Run |