Skip to main content

CreateSalesOrderInput

customerIdstring<uuid>required

Id of the customer the order is for, from the customers list.

Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
idempotencyKeystring<uuid>

A UUID you generate for this order. Same effect as the Idempotency-Key header: a retry with the same key and body returns the original order.

orderDatestring

Order date, ISO 8601. Defaults to today. Any other day needs the user who created the key to hold the back-dating permission.

Example: 2026-01-15
customerEmailstring<email>

Contact email to record on the order.

Example: buyer@example.com
customerMobilestring

Contact phone number to record on the order.

Example: +1 555 0100
referencestring

Your own reference for the order, such as its id in your system.

Example: INT-0001
currencystring

ISO 4217 currency code of the order. Defaults to the workspace currency. A line is priced only from a price in this currency; a line with none is refused.

Example: USD
exchangeRatenumber

Rate from the order currency to the workspace currency. Greater than zero. Worked out by the server when you leave it off for a foreign currency.

Possible values: > 0

Example: 1
warehouseIdstring<uuid>

Warehouse the order is fulfilled from.

Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
promisedDatestring<date-time>

Date the order is promised to the customer, ISO 8601.

paymentTermsstringrequired

Payment terms code, from the payment terms list.

Example: NET_30
shippingMethodstring

Shipping method to record on the order.

notesstring

Free-text notes on the order.

internalNotesstring

Free-text notes for your own team.

deliveryInstructionsstring

Instructions for the delivery.

items object[]required

The order lines.

  • Array [
    • productIdstringrequired

    Id of the product the variant belongs to. An empty string lets the server take it from the variant; a product that does not match the variant is refused.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
    variantIdstringrequired

    Variant id, from the products list.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
    warehouseIdstring

    Warehouse this line ships from.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
    quantitynumberrequired

    Quantity ordered, in the unit given by uomId. Must be greater than zero.

    Example: 2
    unitPricenumber

    Unit price in the order currency. Leave it off to use the catalogue price. A price you send can be refused, depending on the workspace's pricing settings and the permissions of the user who created the key.

    Example: 12.5
    priceOverrideboolean

    Set to true when unitPrice deliberately differs from the catalogue price. The user who created the key may need the price-override permission.

    overrideReasonstring

    Why the price was overridden.

    Possible values: <= 500 characters

    taxRatenumber

    Tax rate percent for the line, used in place of the product's configured tax.

    Example: 10
    discountPercentnumber

    Line discount, from 0 to 100 percent.

    Possible values: >= 0 and <= 100

    Example: 0
    notesstring

    Notes on the line.

    uomIdstring<uuid>required

    Id of the unit of measure the quantity is in, from the units list.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
    taxGroupIdstring<uuid>

    Tax group to use for the line, in place of the product's configured tax.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
  • ]
    • shippingAmountnumber

    Shipping charge in the order currency. Defaults to 0.

    Example: 0
    discountAmountnumber

    Order-level discount amount in the order currency. Defaults to 0.

    Possible values: >= 0

    Example: 0
    discountSchemeIdstring<uuid>

    Id of a discount scheme to apply to the order.

    Example: 9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d
    taxCalculationMethodstring

    Whether line prices already include tax (INCLUSIVE) or tax is added on top (EXCLUSIVE).

    Possible values: [INCLUSIVE, EXCLUSIVE]

    billingAddress object

    Billing address for the order.

    street1stringrequired

    Street address, line 1.

    Example: 1 Example Street
    street2string

    Street address, line 2.

    citystringrequired

    City.

    Example: Exampleville
    statestringrequired

    State or province.

    Example: Example State
    postalCodestringrequired

    Postal code.

    Example: 12345
    countrystringrequired

    Country.

    Example: Exampleland
    idstring

    Id of the saved address this was copied from. Kept for reference only.

    labelstring

    Short label for the address, kept for reference only.

    typestring

    Kind of address, such as BILLING or SHIPPING. Kept for reference only.

    shippingAddress object

    Shipping address for the order.

    street1stringrequired

    Street address, line 1.

    Example: 1 Example Street
    street2string

    Street address, line 2.

    citystringrequired

    City.

    Example: Exampleville
    statestringrequired

    State or province.

    Example: Example State
    postalCodestringrequired

    Postal code.

    Example: 12345
    countrystringrequired

    Country.

    Example: Exampleland
    idstring

    Id of the saved address this was copied from. Kept for reference only.

    labelstring

    Short label for the address, kept for reference only.

    typestring

    Kind of address, such as BILLING or SHIPPING. Kept for reference only.

    statusstring

    Status the order starts in. DRAFT reserves no stock. AWAITING_PAYMENT also reserves none; use it for an order that waits for payment before it is confirmed. CONFIRMED confirms the order and reserves stock, and is refused if the customer's credit limit does not allow it or, when the workspace does not allow negative stock, stock does not cover it. Defaults to DRAFT.

    Possible values: [DRAFT, AWAITING_PAYMENT, CONFIRMED]

    customerPoNumberstring

    The customer's own purchase order number.

    Possible values: <= 100 characters

    Example: PO-12345
    CreateSalesOrderInput
    {
      "customerId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
      "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orderDate": "2026-01-15",
      "customerEmail": "buyer@example.com",
      "customerMobile": "+1 555 0100",
      "reference": "INT-0001",
      "currency": "USD",
      "exchangeRate": 1,
      "warehouseId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
      "promisedDate": "2024-07-29T15:51:28.071Z",
      "paymentTerms": "NET_30",
      "shippingMethod": "string",
      "notes": "string",
      "internalNotes": "string",
      "deliveryInstructions": "string",
      "items": [
        {
          "productId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
          "variantId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
          "warehouseId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
          "quantity": 2,
          "unitPrice": 12.5,
          "priceOverride": true,
          "overrideReason": "string",
          "taxRate": 10,
          "discountPercent": 0,
          "notes": "string",
          "uomId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
          "taxGroupId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d"
        }
      ],
      "shippingAmount": 0,
      "discountAmount": 0,
      "discountSchemeId": "9d2f6b1c-8e47-4a30-b5c2-0e1f3a4b5c6d",
      "taxCalculationMethod": "INCLUSIVE",
      "billingAddress": {
        "street1": "1 Example Street",
        "street2": "string",
        "city": "Exampleville",
        "state": "Example State",
        "postalCode": "12345",
        "country": "Exampleland",
        "id": "string",
        "label": "string",
        "type": "string"
      },
      "shippingAddress": {
        "street1": "1 Example Street",
        "street2": "string",
        "city": "Exampleville",
        "state": "Example State",
        "postalCode": "12345",
        "country": "Exampleland",
        "id": "string",
        "label": "string",
        "type": "string"
      },
      "status": "DRAFT",
      "customerPoNumber": "PO-12345"
    }