Skip to main content
POST
/
orders
{
  "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"
    }
  ],
  "shipping_address": {},
  "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
  • quantity - Number of items to order (integer, minimum 1)
Make sure product URLs are accessible and lead directly to the product page, not search results or category pages.

​
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

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
​
max_price
integer
required
​
items
OrderItemResponse · object[]
required
​
shipping_address
Shipping Address · object
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required