Create an order (v2) — Acme Commerce API

POST /api/v2/orders Requires authentication 10 requests per minute v2

Send a bearer token in the Authorization header.

Creates an order in pending state. Send the Idempotency-Key header so a retried request cannot double-charge.

Full URL: https://api.acme.example/api/v2/orders

Changed since v1

requires a new header parameter Idempotency-Key

Header parameters

Name	Type	Required	Description
Idempotency-Key	string<uuid>	yes	A unique key per logical order. Replays return the original order.

Body parameters

Name	Type	Required	Description
customer_id	integer	yes	Who the order is for.
currency	string, one of USD, EUR, GBP	yes
items	array	yes	At least one line item.
items[].product_id	integer	no
items[].quantity	integer	no

Responses

201 The created order.

422 Validation failed.

429 Too many orders created. Back off and retry after the interval in the Retry-After header.

Example request

cURL

curl -X POST 'https://api.acme.example/api/v2/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c' \
  -d '{
    "customer_id": 1,
    "currency": "USD",
    "items": [
        {
            "product_id": 1,
            "quantity": 2
        }
    ]
}'

JavaScript

const response = await fetch('https://api.acme.example/api/v2/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c'
  },
  body: JSON.stringify({
      "customer_id": 1,
      "currency": "USD",
      "items": [
          {
              "product_id": 1,
              "quantity": 2
          }
      ]
  })
});

const data = await response.json();

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_TOKEN',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c',
])->post('https://api.acme.example/api/v2/orders', [
    'customer_id' => 1,
    'currency' => 'USD',
    'items' => [
        [
            'product_id' => 1,
            'quantity' => 2,
        ],
    ],
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://api.acme.example/api/v2/orders', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
        'Idempotency-Key' => '9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c',
    ],
    'json' => [
        'customer_id' => 1,
        'currency' => 'USD',
        'items' => [
            [
                'product_id' => 1,
                'quantity' => 2,
            ],
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true);

Example response

201

{
    "id": 8802,
    "status": "pending",
    "total": 3998,
    "currency": "USD",
    "items": [
        {
            "product_id": 12,
            "quantity": 2,
            "unit_price": 1999
        }
    ]
}