PlatformMarketplacesPricingDashboardStart for free
Orders

Get order

Returns an order with its lines, payments and totals.

GET
/v1/orders/{orderId}

Returns an order by id, with its lines, payments, status on separate axes and totals in components. Use it after order.created or order.updated, or to open an order from the list.

  • Totals: nothing is recomputed. totalInCents is the marketplace total and roundingAdjustmentInCents is the gap to the sum of the components (see Totals). netInCents is null when the marketplace does not say.
  • Unlinked line: linkState: "unlinked" means marketapi did not find the binding. listingId, variantBindingId and variantId are null, and externalListingId, externalVariantId and externalSku keep the identity of the item on the marketplace.
  • Reasons: statusReasons explains the state, for example who cancelled. The message is free text from the marketplace and only comes here: the webhook carries the code.
  • No personal data: hasBuyerContact says whether a buyer is stored. The data comes out through Get buyer.

Common errors

  • 404 NOT_FOUND: the order does not exist or belongs to another account.

Authorization

api_key
headerAuthorizationBearer <token>

API key (mk_...)

Path Parameters

orderId*string

Identifier of the order, as the API returns it.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

The order with its lines and payments. It carries no personal data: the buyer is hasBuyerContact here and comes out of /buyer.

application/json
  1. response

A sale made on a marketplace: status on four axes, totals in components, the lines sold and the payments. No personal data.

id*string

Order identifier.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
sellerId*string

Seller that made the sale.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
connectionId*string

Marketplace connection the order came from.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
marketplace*string

Marketplace of the connection.

Value in"mock""mercadolivre""magalu""amazon""tiktok""shopee"
externalId*string

Order id at the marketplace (Mercado Livre: the pack_id).

placedAt*string

When the buyer placed the order.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
paidAt*|

When the payment was confirmed. null until then.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
closedAt*|

When the order closed (completed or cancelled). null while open. The buyer personal data retention counts from here.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
deliveredAt*|

When the order was delivered. null until then.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
status*string

Whole-order state. open: still moving. completed: done. cancelled: called off.

Value in"open""completed""cancelled"
paymentStatus*string

Payment axis, independent of the others.

Value in"pending""authorized""paid""partially_refunded""refunded""cancelled"
fulfillmentStatus*string

Delivery axis, independent of the others.

Value in"pending""ready_to_ship""shipped""delivered""not_delivered""cancelled"
invoiceStatus*string

Invoice (NF-e) axis. The invoice routes move it; until then it stays at not_required or pending.

Value in"not_required""pending""submitted""accepted""rejected"
statusReasons*array<>

Normalized reasons for the current state, such as why it was cancelled. Empty when there is nothing to explain.

totals*

The amounts of the order, as components.

lines*array<>

The items sold.

payments*array<>

The payments of the order. Empty until the marketplace reports one.

hasBuyerContact*boolean

Whether a buyer is stored for this order. Read it with GET /v1/orders/{orderId}/buyer; every read is logged.

sourceUpdatedAt*string

When the marketplace last changed the order, as it reported. An older notification never overwrites a newer one.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
createdAt*string

When marketapi first stored the order.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updatedAt*string

When marketapi last changed the order.

Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
curl -X GET "https://example.com/v1/orders/5f3b2c1a-9d8e-4a7b-8c6d-1e2f3a4b5c6d"
{  "id": "1d2e3f40-5161-4728-9a3b-4c5d6e7f8a9b",  "sellerId": "3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01",  "connectionId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",  "marketplace": "mercadolivre",  "externalId": "2000009876543210",  "placedAt": "2026-10-18T14:20:00.000Z",  "paidAt": "2026-10-18T14:21:30.000Z",  "closedAt": null,  "deliveredAt": null,  "status": "open",  "paymentStatus": "paid",  "fulfillmentStatus": "ready_to_ship",  "invoiceStatus": "pending",  "statusReasons": [],  "totals": {    "currency": "BRL",    "subtotalInCents": 499900,    "shippingPaidByBuyerInCents": 2500,    "discounts": [      {        "amountInCents": 5000,        "fundedBy": "seller",        "type": "coupon"      }    ],    "taxesInCents": 0,    "feesInCents": 60588,    "totalInCents": 497400,    "netInCents": 436812,    "roundingAdjustmentInCents": 0  },  "lines": [    {      "id": "2e3f4051-6272-4839-8a4b-5c6d7e8f9a0b",      "externalId": "2000009876543210",      "externalListingId": "MLB123456789",      "externalVariantId": "MLBU1234567",      "externalSku": "IPH16-BLK-128",      "listingId": "0e2ce906-a6ab-4101-9461-4168c8b6b902",      "variantBindingId": "cb064b64-2f63-4c3e-aa42-f11ea0f82b17",      "variantId": "47c9f819-fcf6-4478-b21a-678ecc594a11",      "linkState": "linked",      "quantity": 1,      "unitPriceInCents": 499900,      "discounts": [        {          "amountInCents": 5000,          "fundedBy": "seller",          "type": "coupon"        }      ],      "fees": [        {          "type": "commission",          "amountInCents": 59900,          "rateBps": 1200,          "externalType": "sale_fee"        },        {          "type": "fixed_fee",          "amountInCents": 600,          "rateBps": null,          "externalType": null        }      ],      "taxes": []    }  ],  "payments": [    {      "id": "3f405162-7383-494a-9b5c-6d7e8f9a0b1c",      "externalId": "9988776655",      "method": "credit_card",      "installments": 3,      "amountInCents": 497400,      "status": "paid",      "paidAt": "2026-10-18T14:21:30.000Z"    }  ],  "hasBuyerContact": true,  "sourceUpdatedAt": "2026-10-18T14:21:31.000Z",  "createdAt": "2026-10-18T14:21:35.000Z",  "updatedAt": "2026-10-18T14:21:35.000Z"}

List orders GET

Lists the account orders, newest first.

Get buyer GET

Returns the personal data of an order's buyer.