Skip to main content
POST
/
orders
Create Order
curl --request POST \
  --url https://api.zinc.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>",
    "postal_code": "<string>",
    "phone_number": "<string>",
    "address_line2": "<string>",
    "state": "<string>",
    "country": "US"
  },
  "max_price": 123,
  "idempotency_key": "<string>",
  "retailer_credentials_id": "<string>",
  "metadata": {},
  "po_number": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "max_price": 123,
  "attempts": 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",
  "metadata": {},
  "po_number": "<string>",
  "tracking_numbers": []
}
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

​
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.

​
Optional Order Data

You can include additional data with your order for tracking and reference purposes. This data will be used by our system as as input to any fields during checkout that match.
  • po_number - Your internal purchase order number for tracking and reconciliation
If you only need data for internal reference, use the metadata field instead.

​
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.

Supports international addresses. The state field is optional for countries that don't use states/provinces. The country field uses ISO 3166-1 alpha-2 country codes (e.g., "US", "CA", "GB", "DE").

​
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.

​
metadata
Metadata · object

Optional metadata to attach to the order. Can contain arbitrary key-value pairs.

​
po_number
string | null

Optional purchase order number for the order.

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
​
attempts
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
​
metadata
Metadata · object
​
po_number
string | null
​
tracking_numbers
TrackingNumberResponse · object[]