Orders

Create order

Create an order with its boxes and the products inside them.

POST/v1/orders

Bearer tokenIdempotency-KeyReturns JSONSuccess 201

The order starts as Pending and gets an Order ID. It is not priced yet: the price is set when you dispatch it. Send your own order number as merchantReference. The same checks as in the portal apply: the destination must be covered, the service must allow the payment mode, and a cross-border order needs its customs details.

Request

Headers

Field	Type	Description
`Authorization`required	`string`	The access token from Get token, as "Bearer <token>".
`Content-Type`required	`string`	Always application/json when a body is sent.
`Idempotency-Key`optional	`string`	Optional. Your own unique value for this action (up to 200 characters). Sending the same call again with the same value returns the first result and does nothing a second time.

Request body

Field	Type	Description
`customerId`required	`string`	The customer the order is for.
`customerAddressId`required	`string`	The delivery address: an address id of that customer.
`merchantReference`optional	`string`	Your own order number, up to 100 characters. It must be unique among your orders that are not cancelled.
`serviceId`optional	`string`	The delivery service, from List services.
`paymentMode`required	`prepaid \| cod`	prepaid: you pay the shipping charge. cod: cash is collected from the customer at delivery.
`codAmount`optional	`number`	The cash to collect. Required when paymentMode is cod.
`insuranceElected`optional	`boolean`	Insure this shipment. The premium is added at dispatch.
`declaredValue`optional	`number`	The value of the goods. Insurance and customs duty are worked out from it.
`deliveryContactName`optional	`string`	Who receives the shipment, if not the address contact.
`deliveryAltPhone`optional	`string`	A second phone number for delivery.
`deliveryInstructions`optional	`string`	Instructions for the driver.
`boxes`required	`array`	The boxes of the shipment. At least one. On an update, this replaces all boxes.
`boxes[].length`required	`number`	Length in cm.
`boxes[].width`required	`number`	Width in cm.
`boxes[].height`required	`number`	Height in cm.
`boxes[].standardBoxId`optional	`string`	A standard box id, from List standard boxes.
`boxes[].isFragile`optional	`boolean`	Handling flags: isFragile, isLiquid, isBattery, isPerishable, isOversize.
`boxes[].items`required	`array`	The products in the box. At least one.
`boxes[].items[].productName`required	`string`	Product name.
`boxes[].items[].sku`optional	`string`	Your product code.
`boxes[].items[].quantity`required	`number`	How many, 1 or more.
`boxes[].items[].unitPrice`required	`number`	Price of one unit.
`boxes[].items[].unitWeight`required	`number`	Weight of one unit in kg.
`boxes[].items[].hsCode`optional	`string`	Customs (HS) code. Needed for cross-border orders.
`boxes[].items[].originCountryId`optional	`string`	The country the product was made in.
`customs`optional	`object`	Customs details. Required for a cross-border order.
`customs.exportReason`required	`sale \| gift \| sample \| return_goods \| repair`	Why the goods are being sent.
`customs.incoterm`required	`ddp \| dap`	Who pays duties: ddp (you) or dap (the receiver).
`customs.declaredCustomsValue`required	`number`	The value declared to customs.
`customs.declaredCurrency`required	`string`	Currency of the declared value, as a 3-letter code.

Example request

curl -X POST "https://api.swiftazu.com/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c2f6f0a-3f55-4f0e-9a51-2a1e3b6c9d10" \
  -d '{
  "customerId": "8778df1e-9b74-420d-b826-d17cdad86d36",
  "customerAddressId": "0df7f36c-417a-4145-b956-743f66c4f9b7",
  "merchantReference": "WEB-10482",
  "serviceId": "5c8e7ef4-e345-433f-baa7-43921d5a9332",
  "paymentMode": "prepaid",
  "insuranceElected": true,
  "declaredValue": 350,
  "boxes": [
    {
      "length": 30,
      "width": 20,
      "height": 15,
      "items": [
        {
          "productName": "Linen shirt",
          "sku": "LS-001",
          "quantity": 2,
          "unitPrice": 120,
          "unitWeight": 0.4
        },
        {
          "productName": "Canvas tote",
          "sku": "CT-014",
          "quantity": 1,
          "unitPrice": 110,
          "unitWeight": 0.6
        }
      ]
    }
  ]
}'

Response

Example response · 201

{
  "id": "dffcd25d-6eb3-4b90-868c-6deca160ad74",
  "orderId": "SWZORDYFSADMR",
  "storeId": "100001",
  "status": "pending",
  "isDemo": true
}

Errors

HTTP	Code	Meaning
400	`invalid_request`	The request broke a business rule. message says which one.
403	`demo_allowance_exhausted`	The demo Application has used all of its demo orders. The answer carries demoAllowance and demoOrdersUsed.
409	`duplicate_merchant_reference`	Another order of yours (not cancelled) already uses this merchantReference. Send a new one.
400	`invalid_idempotency_key`	The Idempotency-Key header is empty or longer than 200 characters.
409	`idempotency_in_progress`	A call with this key is still running. Retry shortly.
409	`idempotency_key_reused`	This key was already used for a different call.

Every call can also return the shared errors listed on the Overview page. Overview