Sell: the order lifecycle

This page follows one Acme Store sale from start to end. Acme Store has 100 black iPhone 16 units, listed on Mercado Livre, Amazon and Shopee. A buyer buys 1 on Mercado Livre.

The sale, step by stepCopy Anchor Link

1. The order arrivesCopy Anchor Link

The marketplace tells marketapi, which creates the order and sends order.created. If a notice gets lost, reconciliation brings the order anyway. You can also import older orders.

An order has its status on separate axes, so you know everything at once:

Amounts come in parts: subtotal, shipping paid by the buyer, discounts (and who paid each one), taxes, fees and the net. All in cents. marketapi recalculates nothing: if the sum does not match the marketplace total, the difference shows up in roundingAdjustmentInCents.

Each order line points to the listing and the Variant sold. If a line has no link yet (a listing made outside marketapi, for example), it stays unlinked with the marketplace SKU. It links on its own once the link exists.

2. Stock reactsCopy Anchor Link

The Connection's order policy decides what happens to the balance. It applies to Variants with inventoryAuthority: marketapi:

Each balance change triggers automatic publication: the other listings get 99 without you doing anything. For a kit, the reservation and the sale go to the components: selling 1 kit reserves 2 cables and 1 charger.

The policy can be turned off. Then you record the movements through the API, as you would with your ERP.

3. The NF-eCopy Anchor Link

marketapi does not issue NF-e. You issue it in your ERP and send the XML:

1. Upload the XML as a file (it is confidential: it never has a URL).
2. Create the order's NF-e with the file id.
3. marketapi checks the key, the amount and the issuer's CNPJ against the order. If something does not match, the answer says why.
4. A job delivers the NF-e to the marketplace. invoice.accepted or invoice.rejected arrives.

Need to change the invoice? Send a new one that replaces the old one.

4. ShippingCopy Anchor Link

A shipment is a package. One order can turn into several packages, and one package can carry items from several orders of the same buyer. Each shipment has a mode:

The usual flow: see the dispatch options, ask for the label (shipment.label_ready arrives), download the file and dispatch. The deadline is in dispatchDueAt. Each change arrives as shipment.updated, and tracking shows the delivery events.

The NF-e locks the shipment. While the shipment shows invoice_required in statusReasons, asking for a label or dispatching answers 409. Send the NF-e first.

5. Buyer dataCopy Anchor Link

Name, tax id, phone and address are kept apart, encrypted. They never go in a webhook or in the regular order read. To see them, call the buyer route: each access is logged.

The data is deleted after the retention period: usually 90 days after the order closes, or less if the marketplace requires it. The order stays, with those fields marked purged.

6. When something goes wrongCopy Anchor Link

• Cancellation. The order goes to cancelled, order.cancelled arrives and the reservation is released.
• Return. The buyer sends the product back. You follow the return tracking and check what arrived. When the unit arrives in good shape, it goes back to stock, once. Events return.created and return.updated.
• Dispute. A claim, mediation, cancellation request or chargeback. The dispute has the deadline (deadlineAt) and the allowed actions (allowedActions): refund, accept the return, send evidence. You read the dispute's messages through the API. Events dispute.created, dispute.updated and dispute.message_received.
• Order actions. Cancel, or another action the marketplace allows, in a job.

Endpoints in this phaseCopy Anchor Link

Webhooks in this phase: order.created, order.updated, order.cancelled, inventory.published, invoice.accepted, invoice.rejected, shipment.updated, shipment.label_ready, return.created, return.updated, dispute.created, dispute.updated and dispute.message_received.