Orders

Create an order

Copy page

Store one order received from an enabled custom integration for the authenticated Store. Every product_id must be a modern product created through the same integration and Store.

POST/api/v3/orders

Create an order

Store one order received from an enabled custom integration for the authenticated Store. Every `product_id` must be a modern product created through the same integration and Store. The 201 response means Sign Customiser committed the order; it does not claim payment, manufacturing, fulfilment, shipping, refund, or cancellation state. Requires `orders:write`. `total_amount` is the integration's external grand total in integer minor units. Sign Customiser separately derives its app total from the stored unit prices and quantities, so callers cannot override the platform fee basis. `currency` must equal the Store and every referenced product currency. Customer and address values are optional snapshots; request payloads are never retained as raw JSON. Sign Customiser durably schedules the established manufacturer order emails, order analytics, order-created webhook, and onboarding synchronisation with the order. Manufacturer recipients and analytics events have independent retry units. A queue publishing failure rolls the order back. Delivery by external providers is asynchronous. Repeating the exact method, path, body, credential, and `Idempotency-Key` replays the original 201 response and does not schedule those effects again. Retry a 409 `idempotency_key_in_flight` with the same key after `retry_after`; use the original body or a new key for an idempotency conflict. This v3 operation rejects a `store_order_id` already present for the integration and serialises concurrent v3 creations. During migration, do not send the same logical order through legacy and v3 writes in parallel.

Authorisation

Authorizationstring<bearer>required

The Authorization header expects a Bearer token. Generate one on the API keys page in your dashboard.

Bodyapplication/json

Create an order

Overview

The 201 response means Sign Customiser committed the order; it does not claim payment, manufacturing, fulfilment, shipping, refund, or cancellation state. Requires orders:write. total_amount is the integration's external grand total in integer minor units. Sign Customiser separately derives its app total from the stored unit prices and quantities, so callers cannot override the platform fee basis. currency must equal the Store and every referenced product currency. Customer and address values are optional snapshots; request payloads are never retained as raw JSON. Sign Customiser durably schedules the established manufacturer order emails, order analytics, order-created webhook, and onboarding synchronisation with the order. Manufacturer recipients and analytics events have independent retry units. A queue publishing failure rolls the order back. Delivery by external providers is asynchronous. Repeating the exact method, path, body, credential, and Idempotency-Key replays the original 201 response and does not schedule those effects again. Retry a 409 idempotency_key_in_flight with the same key after retry_after; use the original body or a new key for an idempotency conflict. This v3 operation rejects a store_order_id already present for the integration and serialises concurrent v3 creations. During migration, do not send the same logical order through legacy and v3 writes in parallel.

Authorisation

Bearer token required. Include it in theAuthorization header.

Required scope: orders:write

Request body

integration_idintegerbody

store_order_idstringbody

store_order_numberstringbody

total_amountintegerbody

currencystringbody

shipping_methodstringbody

customerobjectbody

billing_addressobjectbody

shipping_addressobjectbody

line_itemsarraybody

Request body example

{
  "integration_id": 17,
  "store_order_id": "ext-order-1001",
  "store_order_number": "#1001",
  "total_amount": 25800,
  "currency": "AUD",
  "shipping_method": "Express",
  "customer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "billing_address": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "address_1": "1 Example Street",
    "city": "Adelaide",
    "province": "SA",
    "postcode": "5000",
    "country": "AU",
    "company": "Analytical Engines Ltd",
    "address_2": "Suite 2",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "shipping_address": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "address_1": "1 Example Street",
    "city": "Adelaide",
    "province": "SA",
    "postcode": "5000",
    "country": "AU",
    "company": "Analytical Engines Ltd",
    "address_2": "Suite 2",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "line_items": [
    {
      "product_id": 731,
      "quantity": 2
    }
  ]
}

Create an order

curl https://web.signcustomiser.com/api/v3/orders \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "integration_id": 17,
  "store_order_id": "ext-order-1001",
  "store_order_number": "#1001",
  "total_amount": 25800,
  "currency": "AUD",
  "shipping_method": "Express",
  "customer": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "billing_address": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "address_1": "1 Example Street",
    "city": "Adelaide",
    "province": "SA",
    "postcode": "5000",
    "country": "AU",
    "company": "Analytical Engines Ltd",
    "address_2": "Suite 2",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "shipping_address": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "address_1": "1 Example Street",
    "city": "Adelaide",
    "province": "SA",
    "postcode": "5000",
    "country": "AU",
    "company": "Analytical Engines Ltd",
    "address_2": "Suite 2",
    "email": "ada@example.com",
    "phone": "+61 400 000 001"
  },
  "line_items": [
    {
      "product_id": 731,
      "quantity": 2
    }
  ]
}'

{
  "data": {
    "object": "order",
    "id": 123,
    "store_order_id": "ext-order-1001",
    "store_order_number": "#1001",
    "status": "received",
    "status_display_name": "Received",
    "total_amount": 25800,
    "currency": "AUD",
    "shipping_method": "Express",
    "customer": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com",
      "phone": "+61 400 000 001"
    },
    "billing_address": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": null,
      "address_1": "1 Example Street",
      "address_2": null,
      "city": "Adelaide",
      "province": "SA",
      "postcode": "5000",
      "country": "AU",
      "email": null,
      "phone": null
    },
    "shipping_address": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": null,
      "address_1": "1 Example Street",
      "address_2": null,
      "city": "Adelaide",
      "province": "SA",
      "postcode": "5000",
      "country": "AU",
      "email": null,
      "phone": null
    },
    "line_items": [
      {
        "object": "order_line_item",
        "id": 731,
        "store_product_id": "ext-product-1001",
        "customiser_id": 42,
        "title": "Custom neon sign",
        "quantity": 2,
        "unit_price_amount": 12900,
        "currency": "AUD",
        "preview_image_url": null,
        "width_cm": 80.5,
        "height_cm": 31.5,
        "length_cm": 2.5
      }
    ],
    "created_at": "2026-07-19T09:20:00Z",
    "updated_at": "2026-07-19T09:20:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/orders/123",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write operation.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the orders:write scope.",
  "required_scopes": [
    "orders:write"
  ],
  "granted_scopes": [
    "orders:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/store_order_id_conflict",
  "title": "Store order ID conflict",
  "status": 409,
  "code": "store_order_id_conflict",
  "detail": "This integration has already created an order with the supplied store_order_id. Retry the original request with its original Idempotency-Key, or use a new store_order_id.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/request_too_large",
  "title": "Request too large",
  "status": 413,
  "code": "request_too_large",
  "detail": "The request body must not exceed 2 MiB.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "One or more request fields are invalid.",
  "errors": [
    {
      "parameter": "line_items.0.product_id",
      "pointer": "/line_items/0/product_id",
      "code": "currency_mismatch",
      "detail": "The product currency must match the order and Store currency."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}