# POST 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.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-create-an-order/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-create-an-order.md
- Group: Orders
- Method: POST
- Path: /api/v3/orders
- Auth: Bearer token
- Required scopes: `orders:write`

## Body parameters

- integration_id (integer, optional): No description provided.
- store_order_id (string, optional): No description provided.
- store_order_number (string, optional): No description provided.
- total_amount (integer, optional): No description provided.
- currency (string, optional): No description provided.
- shipping_method (string, optional): No description provided.
- customer (object, optional): No description provided.
- billing_address (object, optional): No description provided.
- shipping_address (object, optional): No description provided.
- line_items (array, optional): No description provided.

## Request body example

```json
{
  "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
    }
  ]
}
```

## cURL example

```bash
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
    }
  ]
}'
```

## Response examples

### 201 POST 201 example 1

```json
{
  "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"
  }
}
```

### 400 Missing idempotency key

```json
{
  "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"
}
```

### 401 Missing or invalid API key

```json
{
  "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"
}
```

### 403 Insufficient scope

```json
{
  "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"
}
```

### 404 Unknown or foreign resource

```json
{
  "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"
}
```

### 409 External order already exists

```json
{
  "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"
}
```

### 413 Request body too large

```json
{
  "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"
}
```

### 422 Invalid request field

```json
{
  "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"
}
```

### 429 Rate limited

```json
{
  "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"
}
```