POST `/v1/orders`

Create order intake request

Sends an order into the store's POS. A live key's order is answered 202 once it is accepted into the queue (dispatchState pending_pos_adapter); it then reads dispatched when it landed in the POS, or parked when it could not. A test key's order (a key that starts with cc_test_ or cd_test_) is validated exactly like a live key's and answered with the same 202 and body, but it is simulated and never reaches the store: its orderId starts with test_, its dispatchState is simulated (final: it never changes), the billing block says mode test, and no webhook is sent for it. The checks only the store itself makes (each productCode looked up in its POS, the price it charges, the store agent's support for shipTo and for lines without a unitPrice) are not run for a test order. Sending the same Idempotency-Key or externalOrderId again returns the same simulated order. A test key reads only its integration's simulated orders and a live key only its live ones: an order of the other mode is 404 order_not_found.

Key	Required. See Authentication.
Capability	`order-intake`
Scope	`orders.write`
Price	16 credits, per call. How pricing works.

Example

curl -s -X POST "https://api.compudime.com/v1/orders" \
  -H "Authorization: Bearer $PUBLIC_API_KEY" \
  -H "Idempotency-Key: <idempotency-key>" \
  -H "Content-Type: application/json" \
  -d @body.json

With this body.json:

{
  "externalOrderId": "web-1001",
  "customer": "Pickup customer",
  "notes": "Paid online",
  "orderMethod": "pickup",
  "lines": [
    {
      "productCode": "SKU-100",
      "quantity": 2,
      "unitPrice": "3.99"
    }
  ]
}

Parameters

Name	In	Type	Description
`Idempotency-Key` required	header	string	Safe caller-generated identifier used to prevent duplicate order intake and duplicate billing on retries.

Request body

JSON: OrderCreateRequest (required).

Name	Type	Description
`externalOrderId` required	string
`lines` required	array of `OrderCreateLine`	At least 1 item.
`customer`	string	A 10-digit North American phone number (formatting and a leading 1 are ignored) matches or creates the POS customer; any other value is written as the invoice's ship-to name, of which the POS keeps the first 35 characters, unless shipTo names the recipient.
`notes`	string	Free text for the store; it lands in the POS invoice's Remark, which keeps the first 50 characters. Longer notes are accepted (not refused), but only those 50 reach the invoice.
`orderMethod`	string	How the customer gets the order. Optional: omit it (or send an empty string) and the store's own default delivery method applies, exactly as before this field existed; with a shipTo and no orderMethod the order is a delivery (the 202 and the reads then say delivery). pickup together with a shipTo is a free 400 (a pickup has no delivery address). Any other value is a free 400 before billing. On a replay of the same Idempotency-Key or externalOrderId the stored order keeps the method it was created with. One of: pickup, delivery.
`shipTo`	`OrderShipTo`	Optional delivery address. With it the order is a delivery; without it (or null) the order is exactly what it was before this field existed.

Responses

Status	Description	Body
`202`	Order intake request accepted into the durable queue; a test key's order is validated and simulated instead (dispatchState simulated) and never reaches the store.	`OrderStatus`
`400`	The order request body is invalid, or its externalOrderId or Idempotency-Key already names an order your integration sent with a key of the other mode (live or test).	`Problem`
`401`	Public API key is missing, invalid, or revoked.	`Problem`
`402`	The request was blocked by billing policy: no_api_plan (no plan funds this meter), billing_card_missing, billing_card_failed, usage_exhausted, overage_cap_reached, subscription_paused, sandbox_exhausted, or billing_blocked. A key the store pays for under its approval gets grant_cap_exceeded (the store's monthly limit for your calls) or payer_billing_blocked (the store cannot be charged right now; ask the store owner) instead: what is wrong with the store's billing is not shown to it.	`Problem`
`403`	The API key is not enabled for this endpoint.	`Problem`
`405`	The requested method is not allowed for this endpoint.	`Problem`
`429`	Too many requests from this API key (code rate_limited). Each key has its own request budget at the API edge, refilled continuously; it covers every authenticated endpoint, including the free ones, and is checked before anything is billed or sent to the store. Billed endpoints are also subject to the store plan's per-minute ceiling, which answers the same problem code. Wait at least Retry-After seconds before the next request with this key, then resume; if 429 answers again, back off exponentially (double the wait each time, up to a minute or so) and add random jitter so parallel workers do not retry in step. A 429 is never charged and reserves nothing. Header `Retry-After`: Whole seconds to wait before retrying with this key: the time until the key's next request token at the edge (never less than 1), or 60 when the store plan's per-minute ceiling refused the call.	`Problem`
`500`	The API edge encountered an internal error.	`Problem`
`503`	A required Public API dependency is temporarily unavailable. Also answered, with code endpoint_disabled, while CompuDime has temporarily switched the endpoint off: the whole API, the endpoint's family (x-compudime-family) or this endpoint alone; the detail says which and why. It is checked before anything is validated, reserved or sent to the store, so it is never charged; it is retryable and carries Retry-After. Header `Retry-After`: Sent with code endpoint_disabled: whole seconds to wait before asking again. A switch has no scheduled end, so this is a polling interval (60), not a promise.	`Problem`

Error bodies are problem JSON; every code is listed there.

Access level

What your integration's access level changes here.