Fetch one order from the marketplace it was placed on and store it in eDesk, given the order
ID the marketplace itself quotes. This is the API behind the "Pull Order by ID" screen in
eDesk, and it takes the same two values that screen asks for: the channel and the order ID.
Use it when an order is missing from eDesk and you do not want to wait for the next
scheduled import - a buyer is asking about an order your agents cannot see, or an order that
arrived while a channel was disconnected.
The call is idempotent. If eDesk already holds the order nothing is fetched and the stored
order is returned with meta.status of existing; if it does not, the marketplace is asked
and the imported order comes back with meta.status of imported. Either way data is the
order in the same shape as GET /sales-orders/{salesOrderId}.
data.id is the eDesk sales order ID the order was stored under. Keep it: it is what every
other endpoint takes the order by - GET /sales-orders/{salesOrderId},
PUT /sales-orders/{salesOrderId}, /sales-orders-tracking-links/{salesOrderId} and the
sales_order_id on a ticket.
The order is fetched while you wait, so this call is as slow as the marketplace is - allow
for tens of seconds - and it counts as a single request against your rate limit. The
marketplace's own rate limits apply on top of yours.
Supported marketplaces
Only the marketplaces below can be pulled from. Anything else is rejected with error code
4013. seller_order_id is the ID that marketplace quotes, which is not always the number
the buyer sees:
| Marketplace | What to send as seller_order_id | Example |
|---|---|---|
| Amazon | Amazon Order ID | 026-1234567-1234567 |
| eBay | OrderID, ExtendedOrderID or OrderLineItemID | 110512345678-9876543210 |
| Magento | Order increment ID | 100000123 |
| Shopify | Order name as shown in Shopify, or the bare order number | #1001 |
| BigCommerce | Store order ID | 1234 |
| Walmart | Customer order ID | 1796277083022 |
| Cdiscount | Cdiscount order number | 1234567890 |
| Mirakl | Suffixed logistic order ID, not the commercial order ID | 6730178216_1-A |
| Kaufland | Order unit ID, or the order ID to import every unit of an order | 123456789 |
| Otto | salesOrderId (a UUID) or the short orderNumber | 4f6a1c2e-... |
| Allegro | Checkout form ID (a UUID) | dcb2f0a5-... |
| Bol | Bol order ID | C0008LCLRW |
| Fnac | Fnac order ID | CV65PRPWGJEB2 |
| Darty | Darty order ID (Darty sellers use a Fnac-type channel) | 127901946_314946-A |
| ManoMano | Order reference | M260893258161 |
When no order comes back
A 404 means the marketplace was asked and had no such order - check the ID, and that it
belongs to the channel you named. A 400 means the call never got through: the channel
connection has expired, the marketplace is rate limiting or temporarily down. In both cases
the response carries a sentence explaining what happened that is safe to show to a user -
in error.details on a 404, and in error.message on a 400.
Pulling orders is a paid feature. An account without it gets a 403, the same way the
"Pull Order by ID" screen is hidden from it.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||