Orders

This section describes the order process between Mirakl Connect and the channel, and the APIs and events the connector must implement. It covers the whole life of an order once a buyer places it on a channel:

• how to keep the copy of the order in Mirakl Connect current, as the order moves through the acceptance, the shipment, and the delivery,
• how to carry out the actions Mirakl Connect requests, which are to accept, ship, cancel, and refund,
• the carriers and the documents that go with the fulfillment,
• how to anonymize the order data once it is no longer needed.

A buyer places the order on the channel, and your connector reports it to Mirakl Connect.

As a pre-requisite, a store must be linked to the seller's organization before your connector can push orders. Read Stores, where the import brings the store in and the seller's link activates the order flow.

A fulfilled order can later lead to a return if the channel supports it.

An order is the purchase of a buyer on the channel. It carries the shipping destination in shipping_info, optional billing information, a fulfillment type, a lifecycle status, and one or more order lines.

Its channel_order_id identifies it within the store it belongs to. Combined with the channel_id, it forms the order's global identifier in Mirakl Connect. On a store that carries sub-channels, the sub_channel_code completes that identity, because two sales channels of one channel can issue the same channel_order_id. Read Naming the sub-channel of an order.

An order line is one distinct product in a given quantity. Each line carries:

• its own channel_order_line_id, unique across all the channel's orders, not only within its own order,
• a product, which holds the seller's product id, the title, and an optional thumbnail,
• a quantity,
• a price, which is the total of the line, tax excluded, the unit price multiplied by the quantity. The taxes are listed separately in taxes, and the shipping in total_shipping_price with its own shipping_taxes.
• the flags can_cancel and can_refund, which state whether the line is currently eligible for each one,
• its own status and its status_reason,
• an append-only list of adjustments.

Set the product id to the seller's own product reference on the channel. The seller reads that value to identify what was ordered. Mirakl Connect stores it, and it returns it as the product_id of a CANCEL and of a REFUND action. So never send an identifier that belongs to the channel's own catalog.

Because each line has its own status, the lines of a single order can sit at different stages. One line can be shipped while another still waits for its shipment.

An order declares who fulfills it, through its fulfillment type:

• FULFILLED_BY_SELLER: the seller ships the order.
• FULFILLED_BY_PARTNER: a fulfillment partner ships it, named by a code.

The Data model holds the full definition, field by field, of the order, the line, and the adjustment.

The status of an order, and independently the status of each line, is a reported snapshot.

Mapping the channel's state onto these statuses is your connector's decision. The contract defines the eight values below, and it prescribes no transition between them. Your connector observes where the order stands on the channel, picks the value that matches, and reports it.

Report only the statuses the channel reaches. As an example, if the channel confirms an order without an acceptance from the seller, your connector never reports the status AWAITING_ACCEPTANCE.

• AWAITING_ACCEPTANCE: placed, and waiting for the seller to accept or refuse it.
• AWAITING_FRAUD_CHECK: pending a fraud verification before it is confirmed.
• AWAITING_PAYMENT: the payment is not confirmed yet.
• AWAITING_SHIPMENT: waiting for the seller to ship it.
• SHIPPED: handed to a carrier.
• DELIVERED: delivered to the buyer.
• CLOSED: the lifecycle is complete, because the order is delivered, cancelled, or refunded.
• CHANNEL_SPECIFIC: a channel status with no standard equivalent in Mirakl Connect. Use status_reason to carry the detail.

When a status is terminal or exceptional, most often CLOSED or CHANNEL_SPECIFIC, a status_reason explains how the order got there:

• ACCEPTANCE_TIMEOUT: the seller did not accept within the acceptance deadline.
• AUTOMATICALLY_CLOSED: the channel closed the order automatically.
• CANCELED: the order was cancelled.
• FRAUD_CHECK_FAILED: the order failed the fraud verification.
• FRAUD_CHECK_TIMEOUT: the fraud check was not complete within the deadline.
• PAYMENT_TIMEOUT: the payment did not arrive within the deadline.
• REFUNDED: the order was fully refunded.
• REFUSED: the seller refused the order.
• REFUSED_PAYMENT: the payment was refused.

Order management runs in two directions at once, and a connector has to build both.

Synchronize the channel's state into Mirakl Connect. The connector watches the sales channel and pushes each order into Mirakl Connect as the order changes, through the upsertOrders API. This call is synchronous: a success is a 2xx returned immediately, not a queued acknowledgement. The connector sends the order whole every time, because there is no PATCH, so each call restates the order's current data, with its full list of lines and adjustments. Mirakl Connect versions the updates by the channel_updated_at of the order, so it silently ignores an update whose timestamp is older than the value it already stores. This anti-replay guard keeps a late or replayed message from regressing the state.

Carry out the actions Mirakl Connect requests. Some changes start in Mirakl Connect rather than on the channel, when a seller decides to accept an order, create its shipment, cancel it, or issue a refund. Mirakl Connect sends the connector an OrderActionEvent that names the action to perform, with an action_id to track it. The connector then performs the action on the channel, reports the final outcome through the updateActionStatus API, and reflects the new state back through upsertOrders.

Mirakl Connect delivers the OrderActionEvent like every other event, on the transport you configure.

A single OrderActionEvent carries every action Mirakl Connect can request, and its type says which one. Every OrderActionEvent carries the field action_id in its data, whatever its type. For each action, the connector:

1. performs it on the channel, such as to accept the order or book the shipment,
2. reports the outcome with updateActionStatus on the action_id, either SUCCESS, or FAILED with one or more bounded ActionError codes and a message that a human can read,
3. reflects the new state back with upsertOrders, so that the copy of the order in Mirakl Connect matches what the action produced.

Five action types apply to orders:

• ACCEPT: accept the order, so that it can move toward the payment and the shipment. The seller accepts or refuses the order, and on an acceptance the order usually leaves AWAITING_ACCEPTANCE.
• CREATE_SHIPMENT: ship the order, or a set of its lines, with a carrier. The event contains the shipping tracking information, and the order, or those lines, moves to SHIPPED.
• CANCEL: cancel the order or some of its lines. A cancellation is recorded on the affected lines as an adjustment of type: CANCELATION, and the cancelled scope closes.
• REFUND: refund the order or some of its lines. A refund is recorded on the affected lines as an adjustment of type: REFUND, and a fully refunded order reports status_reason: REFUNDED.

When the connector cannot carry an action out, it reports FAILED with the matching ActionError code, such as ORDER_IN_WRONG_STATE, CARRIER_NOT_SUPPORTED, MISSING_CARRIER, or WAREHOUSE_ID_REQUIRED.

A channel that runs several sales channels declares them as sub-channels on the seller's store. Read Sub-channels for that declaration.

An order then belongs to one sub-channel, and sub_channel_code names it. The field is optional wherever it appears, and Mirakl Connect carries it on every order action it requests for an order that has one.

Send it on every call that names an order:

• upsertOrders: on each order of the payload.
• upsertReturns: on each return, to name the order the return belongs to.
• uploadOrderDocument and deleteOrderDocument: in the origin node.
• updateAnonymizeAfterDate: on each entry.

Two rules follow from that identity.

A channel_order_id on its own stops being enough. Once one order exists with a sub_channel_code under a given channel_order_id, a call that omits the code no longer resolves to one order. upsertOrders then rejects the creation with a 400 on orders[i].channel_order_id. The other calls answer that several orders match the channel_order_id, and that the sub_channel_code is required.

Act on the sales channel the command names. Every order action carries the sub_channel_code of the order it applies to. Read it, so that your connector acts on the right sales channel, and keep it on the order state you hold.

A refund or a cancellation is recorded as an adjustment on the order line, not as a separate object. Each adjustment carries a channel_adjustment_id, the affected quantity, the amount as price, tax excluded, with the taxes listed separately, any shipping amount, and a business reason.

There are two types:

• type: REFUND: money returns to the buyer, and the ordered quantity does not change.
• type: CANCELATION: units are removed from the line, and Mirakl Connect releases the matching stock reservation.

The reason explains why: CUSTOMER_CANCELATION, OUT_OF_STOCK, RETURN, ITEM_NOT_RECEIVED, AGREEMENT, DEFECT, UNABLE_TO_DELIVER, or CHANNEL_SPECIFIC. When an entire order is refunded, its status_reason becomes REFUNDED.

Mirakl Connect requests every refund through the order REFUND action, and a return changes nothing in that. A refund that compensates a return carries reason: RETURN, and it is still an adjustment on the order line. The return itself holds no refund field, so never record an amount on it.

The connector attaches a file to an order, or to a related entity, with the uploadOrderDocument API. It is a multipart call that carries the file, the origin, which is the channel, the store, and the order's sub_channel_code, and the metadata. The metadata names the channel_document_id of the document, its filename, and its type:

• RETURN_LABEL
• CUSTOMER_INVOICE
• DELIVERY_SLIP
• SHIPMENT_DELIVERY_SLIP
• CHANNEL_SPECIFIC, with a free-text channel_type for the channel's original type

A document that belongs to a return names that return through its entity, with type: RETURN and the id of the return.

Remove a document with deleteOrderDocument. The call names the order and the document in the path, and carries the origin in the body.

The connector shares the list of carriers the channel allows, with the upsertCarriers API, so that a shipment can name a carrier the channel supports. Each carrier has a channel_carrier_id and a display name.

Sharing the list does not guarantee that a CREATE_SHIPMENT action names a supported carrier. Mirakl Connect always tries the value the seller gave, and it sends the display name, never the channel_carrier_id. When your connector reports FAILED with CARRIER_NOT_SUPPORTED, Mirakl Connect maps that value against the list you shared, or against the mapping the seller set in Mirakl Connect, then sends a new CREATE_SHIPMENT action with a value the channel supports.

To meet the obligations on data retention, the connector tells Mirakl Connect when it can anonymize each order's personal data, with the updateAnonymizeAfterDate API. Each entry names an order, through its channel_order_id, its channel_id, and its sub_channel_code, and an anonymize_after date, which must be in the future.

• Sync orders into Connect: how to observe the channel and push each order into Mirakl Connect with upsertOrders, including the lines, the adjustments, the statuses, and the versioning that keeps the updates in order.
• Handle order action events: how to consume OrderActionEvent for the order actions, ACCEPT, CREATE_SHIPMENT, CANCEL, REFUND, and UPLOAD_DOCUMENT, perform them on the channel, and report the outcome with updateActionStatus.
• Returns: how to sync the returns with upsertReturns, carry out the four return actions, and attach the documents of a return.

• Catalog flow: how the offers a seller manages in Mirakl Connect reach the channel. It is the other flow of a linked store, and neither flow gates the other.
• Stores: it owns the store and the channel that scope every order. A store must be onboarded before its orders can flow.
• Data model: the definitions, field by field, of the order, the line, and the adjustment.
• Best practices: the rules on idempotency, retries, and errors that the operations and the events on this page obey.
• REST APIs reference and Event APIs reference: where to look an operation or an event up.