Place an order

View as Markdown

Places an order at cost (production price, shipping and VAT) paid from your wallet, with any shortfall charged to your saved card, for example for a sale on your own website. Send an Idempotency-Key and reuse it on every retry: an order is created at most once. Follow the order with the order.* webhooks.

What you need

itemsarray of objectRequired
What to order: { "variant": "var_...", "quantity": 1 } per line. Each variant must be yours, active and approved.
customerobjectRequired
The recipient: name, email and optionally phone.
shipping_addressobjectRequired
Where to ship: line1, city, country_code (ISO alpha-2) and optionally line2, state, postal_code.
referencestring
Your own reference for the order, for example your order number.
idempotency_keystringRequired
A unique string for this attempt, for example a UUID. Send the same value when you retry, so the write happens once.

Step 1: Create an order

POST/v2/orders

Create and pay the order. It comes back paid and goes to production. payment_failed (402) means no order was created: add or update the saved card in the dashboard, then retry with the same Idempotency-Key. variant_not_orderable (422) names a variant that is unknown, inactive or not approved.

Parameters

{
  "header Idempotency-Key": "$inputs.idempotency_key"
}

Request body

{
  "items": "$inputs.items",
  "customer": "$inputs.customer",
  "shipping_address": "$inputs.shipping_address",
  "reference": "$inputs.reference"
}

Succeeds when:

$statusCode == 201

Otherwise:

retry_server_error: retry after 5 seconds, at most 3 times, when $statusCode >= 500.
payment_failed: stop the workflow when $statusCode == 402.
variant_not_orderable: stop the workflow when $statusCode == 422.

Keeps for the next steps:

order_id: $response.body#/id
number: $response.body#/number
status: $response.body#/status
total: $response.body#/charges/total

As a workflow file

The workflow returns:

order_id: $steps.create_order.outputs.order_id
number: $steps.create_order.outputs.number
total: $steps.create_order.outputs.total

Values starting with $ are filled in as you go: $inputs.x is something you provide, $steps.s.outputs.o is a value an earlier step returned, and $response.body#/path a field of this response.

This recipe is the workflow place_order of arazzo.json, an Arazzo 1.0 document that tools and AI agents can follow step by step.