Sales orders

Create an order

Create an order and its fulfillment groups without booking labels. Each group can use a different active location and shipping method. Allocate the full quantity of every order line across the groups.

post/api/external/v1/orders

Request

  • Base URL: http://localhost
  • URL: http://localhost/api/external/v1/orders
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Request body

external_referencestring required

Must not be greater than 191 characters.

merchant_reference1string required

Required merchant order reference. Used as the order display name. Must not be greater than 255 characters.

currencystring required

Order currency, such as SEK. Three-letter uppercase ISO 4217 currency code. Must be 3 characters.

total_pricestring nullable

Optional total order amount as a decimal string. Omitted or null means unknown, not zero. Decimal string with up to eight digits before the decimal point and two after it. Negative values are allowed.

total_taxesstring nullable

Optional total tax amount as a decimal string. Omitted or null means unknown, not zero. Decimal string with up to eight digits before the decimal point and two after it. Negative values are allowed.

shipping_pricestring nullable

Optional shipping amount as a decimal string. Omitted or null means unknown, not zero. Decimal string with up to eight digits before the decimal point and two after it. Negative values are allowed.

weight_gramsinteger nullable

Must be at least 0. Must not be greater than 2147483647.

financial_status'AUTHORIZED' | 'PAID'

Reported payment status: AUTHORIZED or PAID. Defaults to AUTHORIZED. This does not authorize or capture a payment.

placed_atstring

Timestamp with whole seconds and an explicit timezone, such as 2026-09-13T10:00:00Z.

merchant_reference2string nullable

Must not be greater than 255 characters.

metadataobject nullable

Example request

{
  "external_reference": "b",
  "merchant_reference1": "ERP-ORDER-5001",
  "currency": "USD",
  "total_price": "249.00",
  "total_taxes": "49.80",
  "shipping_price": "49.00",
  "weight_grams": 22,
  "financial_status": "AUTHORIZED",
  "placed_at": "2026-10-13T09:06:16+00:00",
  "merchant_reference2": "g",
  "customer": {
    "first_name": "b",
    "last_name": "n",
    "company": "g",
    "address1": "z",
    "address2": "m",
    "postal_code": "i",
    "city": "y",
    "state": "v",
    "country": "dl",
    "phone": "j",
    "email": "lafayette.considine@example.com",
    "customer_type": "a"
  },
  "line_items": [
    []
  ],
  "fulfillment_orders": [
    []
  ]
}

Response

Example response

{
  "data": {
    "id": "ord_x7Kq9",
    "vendor_identifier": "external-api:1:order:example",
    "external_reference": "ERP-1001",
    "name": "#1001",
    "currency": "USD",
    "total_price": "249.00",
    "total_taxes": "49.80",
    "shipping_price": "49.00",
    "weight_grams": null,
    "financial_status": "AUTHORIZED",
    "fulfillment_status": "UNFULFILLED",
    "placed_at": "2026-09-07T10:00:00+00:00",
    "merchant_reference1": "#1001",
    "merchant_reference2": null,
    "customer": {
      "first_name": "Anna",
      "last_name": "Andersson",
      "company": null,
      "address1": "Drottninggatan 1",
      "address2": null,
      "postal_code": "11151",
      "city": "Stockholm",
      "state": null,
      "country": "SE",
      "phone": "+46701234567",
      "email": "anna@example.com",
      "customer_type": null
    },
    "line_items": [
      {
        "external_reference": "LINE-1",
        "name": "Blue shirt",
        "sku": "SHIRT-BLUE-M",
        "quantity": 2,
        "unit_price": "100.00",
        "type": "physical",
        "tax_rate_basis_points": 2500,
        "total_tax_amount": "40.00",
        "attributes": {}
      }
    ],
    "metadata": {},
    "created_at": "2026-09-07T10:00:00+00:00",
    "updated_at": "2026-09-07T10:00:00+00:00",
    "fulfillment_orders": [
      {
        "external_reference": "WAREHOUSE-A",
        "shipping_method_id": null,
        "service_point_id": null,
        "location_id": "loc_x7Kq9",
        "shipping": {
          "name": null,
          "type": null,
          "class": null,
          "carrier": null,
          "tax_rate_basis_points": null,
          "location": null
        },
        "status": "OPEN",
        "request_status": "UNSUBMITTED",
        "line_items": [
          {
            "order_line_reference": "LINE-1",
            "quantity": 1,
            "quantity_remaining": 1,
            "weight_grams": 250
          }
        ]
      },
      {
        "external_reference": "WAREHOUSE-B",
        "shipping_method_id": null,
        "service_point_id": null,
        "location_id": "loc_x7Kq9",
        "shipping": {
          "name": null,
          "type": null,
          "class": null,
          "carrier": null,
          "tax_rate_basis_points": null,
          "location": null
        },
        "status": "OPEN",
        "request_status": "UNSUBMITTED",
        "line_items": [
          {
            "order_line_reference": "LINE-1",
            "quantity": 1,
            "quantity_remaining": 1,
            "weight_grams": 250
          }
        ]
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.