MX Orders lets you create and manage orders — the line items a customer bought, how they're fulfilled (shipped or picked up), and any returns — programmatically. It sits on top of MX Retail: orders are built from your catalog products and flow through to receipts, invoices, and reporting.

Common use cases

• Record an order placed on your web store, POS, or over the phone
• Fulfill an order by shipping it or marking it picked up
• Process a return against a completed order
• Send an order receipt and pull order history for reconciliation

Make your first order

Create an order with the customer's line items. Prices and names come from your MX Retail catalog.

POST /order

{
  "merchantId": 1000157980,
  "lineItems": [
    { "name": "Test Product", "price": 19.99, "quantity": "2" }
  ],
  "sourceType": "Web"
}

Created via POST /order. Provide at least a merchantId and one line item. sourceType records where the order came from (POS, Web, or Telephone). Store the returned order id.

Scenarios

Every order moves through the order statuses below. The scenario picks what you do after it's created.

Before you begin (all scenarios)

• Your catalog products exist in MX Retail.
• You have the order id from "Make your first order".

Scenario 1: Fulfill an order by shipping it

(Create a fulfillment with a delivery method of Courier)

Use this when you've shipped the goods and want to record it against the order.

POST /v3/order/{orderId}/fulfillment

{
  "deliveryMethod": "Courier",
  "status": "Shipped"
}

Created via POST /v3/order/{orderId}/fulfillment. deliveryMethod is Courier or Pickup; status is Shipped or Pickedup. Read fulfillments with GET /v3/order/{orderId}/fulfillment.

Scenario 2: Fulfill an order for in-store pickup

(Create a fulfillment with a delivery method of Pickup)

Use this for buy-online-pickup-in-store — mark the order picked up when the customer collects it.

POST /v3/order/{orderId}/fulfillment

{
  "deliveryMethod": "Pickup",
  "status": "Pickedup"
}

Same endpoint as Scenario 1 (POST /v3/order/{orderId}/fulfillment).

Scenario 3: Process a return

(Create an order return against a completed order)

Use this when a customer returns items from an order.

POST /v3/orderreturn

{
  "orderId": 123456,
  "lineItems": [
    { "name": "Test Product", "quantity": "1" }
  ]
}

Created via POST /v3/orderreturn. List an order's returns with GET /v3/order/{orderId}/return.

Track the order

Follow an order with these reads:

• GET /v3/order — list orders
• GET /v3/customer/order/{orderId} — get a single order
• GET /v3/order/{orderId}/history — the order's change history
• GET /v3/order/{orderId}/invoice — invoices generated from the order

Send the customer a receipt with POST /v3/orderreceipt.

Statuses

An order carries an order status and, once you fulfill it, a fulfillment status.

The order also carries a paymentStatus and fulfillmentStatus.

Operations reference

The full MX Orders surface lives in the MX Orders API Reference. Common operations:

Best practices

General API practices are in Getting Started. Specific to MX Orders:

Next steps

See also

• MX Retail: the catalog behind your orders
• Invoicing: invoices generated from orders
• Reports & Reconciliation: reconcile orders against payments