Overview
Orders imported from marketplaces: status, totals and buyer data.
An order is a sale made on a marketplace. marketapi imports the orders of each Connection, keeps the exact amounts the marketplace reported, and tells you by webhook.
The whole journey, from sale to shipping: The order lifecycle.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/orders | List orders |
GET | /v1/orders/{orderId} | Get order |
GET | /v1/orders/{orderId}/buyer | Get buyer |
POST | /v1/connections/{id}/order-imports | Import orders |
POST | /v1/connections/{id}/order-reconciliations | Reconcile orders |
POST | /v1/orders/{orderId}/actions | Run order action |
All of them need Authorization: Bearer mk_your_api_key. See Authentication.
The order is born on the marketplace
The API only reads. There is no POST, PATCH or DELETE for an order. An order arrives in three ways, and all three end up in the same place:
- the marketplace notification, the normal path;
- the import, to bring in a period;
- the reconciliation, to recover what a lost notification left behind.
Receiving the same order again does not duplicate it or send an event. A notice older than what is already stored is ignored.
Status on axes
An order does not have a single status. Each axis moves on its own:
| Field | What it says |
|---|---|
status | open, completed or cancelled |
paymentStatus | from pending to paid, or partially_refunded, refunded |
fulfillmentStatus | from pending to shipped and delivered, or not_delivered |
invoiceStatus | the invoice: not_required, pending, submitted, accepted, rejected |
invoiceStatus only leaves not_required or pending when the invoice routes move it.
Totals
Totals come in components, in cents, and nothing is recomputed. totalInCents is the total the marketplace reported. The gap to the sum of the components stays in roundingAdjustmentInCents:
roundingAdjustmentInCents = totalInCents
− (subtotalInCents + shippingPaidByBuyerInCents + taxesInCents − order discounts)It is 0 when the components add up, and negative when they exceed the total. Fees (feesInCents) stay out of the sum: they are what the marketplace withholds from the seller. netInCents is what the seller receives and is null when the marketplace does not say. marketapi does not compute it.
Unlinked line
Each line has linkState:
linked: marketapi found the binding of the listing sold.listingId,variantBindingIdandvariantIdare set.unlinked: it did not (a listing created outside marketapi, for example). Those three fields arenull, and the line keeps the external identity (externalListingId,externalVariantId) and theexternalSku.
The order is imported either way: an unlinked line breaks nothing. When the binding comes to exist, the next read of the order links the line and an order.updated goes out.
Stock
The Connection order policy (coming soon) sets the effect on stock: paid reserves, shipped writes off, cancelled releases.
Buyer data
The order and the webhook carry no personal data: only hasBuyerContact. Name, CPF or CNPJ, e-mail, phone and addresses come out only through Get buyer. Every access is logged, and the data goes away at the end of the retention period. Each field comes with a state:
| State | What it says |
|---|---|
available | the value is in value |
masked | the marketplace only shows the masked text, in value |
withheld | the marketplace does not show this field |
purged | erased at the end of retention; the order stays |
Webhooks
order.created: the order appeared in marketapi, even if it arrives already cancelled.order.updated: a status, total, line, payment or the link of a line changed.order.cancelled: the order was cancelled. It goes out alone, withoutorder.updated.
The data is { order }, the same order as Get order, with only IDs and fields with no personal data. The reasons in statusReasons come without message (free text from the marketplace): use the code. Invoices and shipments have their own events: Invoices and Shipments.