Skip to main content
POST
/
orders
Create Order
curl --request POST \
  --url https://api.example.com/orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "products": [
    {
      "url": "<string>",
      "quantity": 1,
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "address_line1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "phone_number": "<string>",
    "address_line2": "<string>",
    "country": "US"
  },
  "max_price": 123,
  "idempotency_key": "<string>",
  "retailer_credentials_id": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "max_price": 123,
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "quantity": 123,
      "status": "pending",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "shipping_address": {},
  "retailer_credentials_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
Create a new order for processing. Orders are queued and processed asynchronously.

​
Request Flow

  1. Submit Order - Send order details including products and shipping address
  2. Validation - We validate product URLs and shipping address
  3. Queued - Order is queued for processing
  4. Processing - Our system places the order with the retailer
  5. Completed - You receive confirmation with tracking details
Order flow diagram

Order processing flow

​
Product URLs

Provide direct product URLs from supported retailers. Each product must include:
  • url - Direct link to the product page
Make sure product URLs are accessible and lead directly to the product page, not search results or category pages.
Optionally, the product can include:
  • quantity - Number of items to order (integer, default 1)
  • variant - A list of label, value pairs indicating a variant of a product. For example, if you’re ordering a shirt. The shirt may come in different colors and different sizes. To indicate a red medium shirt, you would do: 
    [
  {
    "label": "Color",
    "value": "Red"
  },
  {
    "label": "Size",
    "value": "Medium"
  }
]
    Make sure the strings used for both the label and value match up to what is present on the retailer website. For example, if a medium is indicated by the value M, use M for the value.

​
Shipping Address

All orders require a valid US shipping address. Addresses are validated using Google’s Address Validation API. Required fields:
  • Name
  • Street address
  • City
  • State (2-letter code)
  • Postal code
  • Phone number
  • Country (must be “US”)
We currently only support shipping to addresses in the United States.

​
Response

A successful order creation returns:
  • id - Unique order identifier (UUID)
  • status - Current order status (initially “pending”)
  • items - Array of order items with their details
  • shipping_address - Confirmed shipping address
  • created_at - Timestamp of order creation
Use the order id to retrieve order status and updates.

Headers

​
authorization
string | null

Body

application/json

Request model for creating a new order.

​
products
OrderProduct · object[]
required
​
shipping_address
Address · object
required

Shipping address model.

​
max_price
integer
required

Maximum price (in cents) allowed for an order before it is finalized.

​
idempotency_key
string | null

Optional idempotency key to prevent duplicate orders. If not provided, one will be generated.

Maximum string length: 36
​
retailer_credentials_id
string | null

Optional short ID (e.g., 'zn_acct_XXXXXXXX') of specific retailer credentials to use for this order. If not provided, credentials will be selected automatically.

Response

Successful Response

Response model for order data.

​
id
string<uuid>
required
​
status
enum<string>
required
Available options:
pending,
in_progress,
order_placed,
order_failed,
cancelled
​
max_price
integer
required
​
items
OrderItemResponse · object[]
required
​
shipping_address
Shipping Address · object
required
​
retailer_credentials_id
string | null
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required