---
search:
  tags:
    - Orders
    - POST
seo:
  description: >-
    Creates an order. There is no Idempotency-Key-header-style replay mechanism
    — a retried request… Reference for the POST /orders endpoint in the Bolder
    API v2.
sidebar:
  label: Create an order
  badge: POST
title: Create an order
type: openapi-operation
---
Creates an order. **There is no `Idempotency-Key`-header-style replay
mechanism** — a retried request always executes again server-side, it
never returns a cached copy of the original response. If a create
request times out or the response is otherwise lost, pass an
`external_id` and check `GET /v2/orders?external_id={value}` before
retrying: the first successful create claims that `external_id`, and a
second create attempt with the same value is rejected with a 422
instead of producing a duplicate order. (The `id`/`code` field does
*not* give you this protection via `POST` — see below.)

Alternatively, `PUT /v2/orders/{id}` with `_upsert: true` and an
`external_id` in the body finds-or-creates by `external_id` directly
— it creates the order (with a system-generated `code`, not the URL
`:id`) if no order with that `external_id` exists yet, or updates it
in place if one does, so a retried request converges instead of
duplicating. See that operation's description for details.

`POST /orders`

**cURL**

```bash
curl -s -X POST \
  -H "Authorization: Bearer $BOLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shop_id":1,"contact":{"name":"Jane Doe","email":"customer@example.com"},"line_items":[{"variant_id":101,"units":2}]}' \
  "https://api.onbolder.com/v2/orders"
```

**Request body** (`application/json`, required)

- `shop_id` (integer, required) — Required — ID of the shop this order belongs to
- `id` (string) — Optional client-supplied order code (returned/queryable as \`code\`). \*\*Not a reliable idempotency key\*\*: if the code collides with an existing order, the collision is resolved silently by generating a new random code instead of rejecting the request — a retried create with the same \`id\` does not return the original order, it creates a new one with a different code. Use \`external\_id\` instead if you need safe dedup.
- `external_id` (string) — Optional client-supplied reference, unique per seller. A colliding value is rejected with a 422 (unlike \`id\`), so this is the field to use for retry-safe order creation: check \`GET /v2/orders?external\_id={value}\` before retrying a create that may have already succeeded.
- `source` (string)
- `contact` (object)
- `address` (Address)
- `line_items` (object[])
- `tags` (string[])
- `courier_name` (string)
- `tracking_code` (string)
- `fulfillment_method` (string)
- `_policies` (object) — Flags controlling order processing behavior

Request body example:

```json
{
  "shop_id": 1,
  "contact": {
    "name": "Jane Doe",
    "email": "customer@example.com"
  },
  "line_items": [
    {
      "variant_id": "101",
      "units": 2
    },
    {
      "variant_id": "205",
      "units": 1
    }
  ]
}
```

**Responses**

- `201` — Order created
- `403` — Access denied to the given shop
- `422` — Validation error

Response example, 422:

```json
{
  "id": 5002,
  "shop_id": 1,
  "code": "ORD-5002",
  "status": "checkout",
  "currency_code": "USD",
  "total": 17997,
  "created_on": "2024-06-20T14:30:00Z",
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/orders/ORD-5002"
    },
    "orders:update": {
      "href": "https://api.onbolder.com/v2/orders/ORD-5002",
      "method": "put"
    }
  }
}
```