Send orders

With orders:write, POST /orders creates an order in Nucleo. It goes through the same steps as the sales channel's orders: Nucleo's routing rules choose the location, the warehouse receives it, and order.created is sent to every key that receives webhooks — yours included.

curl https://api-commerce.nucleoplatform.com/api/commerce/v1/orders \
  -H "Authorization: Bearer $NUCLEO_COMMERCE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0c5e1a-2b3c-4d5e-8f9a-0b1c2d3e4f5a" \
  -d '{
    "channel_order_ref": "SO-2026-00871",
    "number": "B2B-871",
    "customer": { "name": "Anna Rossi", "email": "buyer@example.com" },
    "shipping_address": { "first_name": "Anna", "last_name": "Rossi", "address1": "Via Emilia 120",
      "city": "Modena", "postal_code": "41121", "country_code": "IT" },
    "shipping": { "method_code": "standard", "price": "5.00", "tax_rate": 22 },
    "lines": [ { "sku": "TEE-BLK-M", "quantity": 2, "unit_price": "29.90", "tax_rate": 22 } ]
  }'

• No duplicates. channel_order_ref is your own id of the order. Sending it again with the same key creates nothing: you get 200 with the order created the first time, unchanged (a new order answers 201). If a call times out, send it again: you never get two orders. An Idempotency-Key also replays the first answer exactly; it stores errors too, so after fixing a rejected request send it with a new key.
• Number. Nucleo shows the order as API- plus your number: B2B-871 becomes API-B2B-871 (GET /orders/API-B2B-871), so it never clashes with the sales channel's numbers. Use letters, digits, ., - and _, at most 40 characters. Without number, channel_order_ref is used and must follow the same rule. A number another order already has answers 409 number_taken.
• Items must be known to Nucleo, with a barcode, by sku or barcode; if you send both, they must be the same item. One unknown or mismatched item rejects the whole order with 400 unknown_item, with a message per line in details.
• Amounts are in EUR, tax included, with discounts already applied to unit_price. Every line needs its tax_rate, and the shipping its shipping.tax_rate when you send shipping.price. Nucleo computes subtotal, tax (lines and shipping) and total; shipping.price is added to the total.
• Payment. The order is treated as paid: send orders that are ready to ship.
• Routing. If no routing rule covers the order, or no location of its rule has all the items in stock, it stays on_hold and the merchant is alerted to add or fix the rule and route it again.
• Notes. notes reaches the merchant and the warehouse; the API does not return it.
• Webhook. order.created always carries status: received; the status the order reaches next comes with order.status_changed.

Orders created here cannot be changed or cancelled through the API yet: ask the merchant. Their status, shipments and tracking are read like any other order, and channel is nucleo_api.