> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Order
> Create a new order
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
## 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.
## OpenAPI
````yaml /versions/latest.json POST /orders
openapi: 3.1.0
info:
title: Zinc
summary: >-
Zinc lets you search, buy, and return items from top online retailers with a
single API.
description: >-
Search, buy, and return items from top online retailers with a single API.
Supports AI agent ordering via MPP (HTTP 402) — no account required.
version: '2026-04-27'
x-logo:
url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
x-guidance: >-
Zinc lets AI agents buy products from online retailers via a single API. Use
POST /agent/orders to place an order — no Zinc account needed, payment is
handled via MPP (HTTP 402 flow). Provide a product URL (e.g. Amazon),
shipping address, and max_price in cents. The API charges max_price + $1 API
fee upfront and refunds the difference on completion. Authenticated
endpoints (orders, products, managed-accounts) require a Bearer token (API
key prefixed zn_). Docs: https://zinc.com/docs
servers:
- url: https://api.zinc.com
description: Production
security:
- BearerAuth: []
paths:
/orders:
post:
tags:
- orders
summary: Create Order
description: Posts an order to a queue for processing
operationId: create_order_orders_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
OrderCreate:
properties:
products:
items:
$ref: '#/components/schemas/OrderProduct'
type: array
title: Products
shipping_address:
$ref: '#/components/schemas/Address'
max_price:
type: integer
title: Max Price
description: >-
Maximum price (in cents) allowed for an order before it is
finalized.
idempotency_key:
anyOf:
- type: string
maxLength: 36
- type: 'null'
title: Idempotency Key
description: >-
Optional idempotency key to prevent duplicate orders. If not
provided, one will be generated.
retailer_credentials_id:
anyOf:
- type: string
- type: 'null'
title: Retailer Credentials Id
description: >-
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:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
description: >-
Optional metadata to attach to the order. Can contain arbitrary
key-value pairs.
po_number:
anyOf:
- type: string
- type: 'null'
title: Po Number
description: Optional purchase order number for the order.
type: object
required:
- products
- shipping_address
- max_price
title: OrderCreate
description: Request model for creating a new order.
OrderResponse:
properties:
id:
type: string
format: uuid
title: Id
status:
$ref: '#/components/schemas/OrderStatus'
max_price:
type: integer
title: Max Price
attempts:
type: integer
title: Attempts
items:
items:
$ref: '#/components/schemas/OrderItemResponse'
type: array
title: Items
shipping_address:
additionalProperties: true
type: object
title: Shipping Address
metadata:
additionalProperties: true
type: object
title: Metadata
default: {}
po_number:
anyOf:
- type: string
- type: 'null'
title: Po Number
retailer_credentials_id:
anyOf:
- type: string
- type: 'null'
title: Retailer Credentials Id
tracking_numbers:
items:
$ref: '#/components/schemas/TrackingNumberResponse'
type: array
title: Tracking Numbers
default: []
created_by:
anyOf:
- type: string
- type: 'null'
title: Created By
user_id:
anyOf:
- type: integer
- type: 'null'
title: User Id
returns:
items:
$ref: '#/components/schemas/ReturnRequestSummary'
type: array
title: Returns
default: []
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- status
- max_price
- attempts
- items
- shipping_address
- retailer_credentials_id
- created_at
- updated_at
title: OrderResponse
description: Response model for order data.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
OrderProduct:
properties:
url:
type: string
title: Url
examples:
- https://www.amazon.com/dp/B07JGBW826
quantity:
type: integer
maximum: 100
minimum: 1
title: Quantity
default: 1
variant:
anyOf:
- items:
$ref: '#/components/schemas/ProductVariant'
type: array
- type: 'null'
title: Variant
description: Product variants to select (e.g., color, size)
type: object
required:
- url
title: OrderProduct
description: |-
Product item for an order.
For example:
````{
url: "https://www.amazon.com/dp/B07JGBW826",
quantity: 1
}```
Address:
properties:
first_name:
type: string
title: First Name
last_name:
type: string
title: Last Name
address_line1:
type: string
title: Address Line1
address_line2:
anyOf:
- type: string
- type: 'null'
title: Address Line2
city:
type: string
title: City
state:
anyOf:
- type: string
- type: 'null'
title: State
postal_code:
type: string
title: Postal Code
phone_number:
type: string
title: Phone Number
country:
type: string
title: Country
default: US
type: object
required:
- first_name
- last_name
- address_line1
- city
- postal_code
- phone_number
title: Address
description: >-
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").
OrderStatus:
type: string
enum:
- pending
- in_progress
- order_placed
- order_failed
- cancelled
- cancelled_by_retailer
title: OrderStatus
OrderItemResponse:
properties:
id:
type: string
format: uuid
title: Id
url:
type: string
title: Url
quantity:
type: integer
title: Quantity
variant:
anyOf:
- items:
$ref: '#/components/schemas/ProductVariant'
type: array
- type: 'null'
title: Variant
status:
$ref: '#/components/schemas/OrderItemStatus'
cancellation_reason:
anyOf:
- type: string
- type: 'null'
title: Cancellation Reason
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- url
- quantity
- status
- created_at
- updated_at
title: OrderItemResponse
description: Response model for order item data.
TrackingNumberResponse:
properties:
id:
type: string
format: uuid
title: Id
carrier:
type: string
title: Carrier
tracking_number:
type: string
title: Tracking Number
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- carrier
- tracking_number
- created_at
title: TrackingNumberResponse
description: Response model for tracking number data.
ReturnRequestSummary:
properties:
id:
type: string
format: uuid
title: Id
status:
$ref: '#/components/schemas/ReturnRequestStatus'
reason:
$ref: '#/components/schemas/ReturnRequestReason'
notes:
anyOf:
- type: string
- type: 'null'
title: Notes
resolution_notes:
anyOf:
- type: string
- type: 'null'
title: Resolution Notes
items:
items:
$ref: '#/components/schemas/ReturnRequestItem'
type: array
title: Items
default: []
label_urls:
items:
type: string
type: array
title: Label Urls
default: []
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- status
- reason
- created_at
- updated_at
title: ReturnRequestSummary
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ProductVariant:
properties:
label:
type: string
minLength: 1
title: Label
description: Variant label (e.g., 'Color', 'Size')
value:
type: string
minLength: 1
title: Value
description: Variant value (e.g., 'Black', 'Large')
type: object
required:
- label
- value
title: ProductVariant
description: >-
Product variant schema for selecting product options (color, size,
etc.).
OrderItemStatus:
type: string
enum:
- pending
- processing
- ordered
- shipped
- delivered
- cancelled
- failed
title: OrderItemStatus
ReturnRequestStatus:
type: string
enum:
- open
- approved
- denied
title: ReturnRequestStatus
ReturnRequestReason:
type: string
enum:
- damaged
- not_delivered
- empty_box
- wrong_item
- defective
- not_as_described
- wrong_size
- no_longer_needed
- forced_cancellation
- other
title: ReturnRequestReason
description: Universal return reason codes (Shopify + Amazon prepaid alignment).
ReturnRequestItem:
properties:
order_item_id:
type: string
format: uuid
title: Order Item Id
quantity:
type: integer
maximum: 100
minimum: 1
title: Quantity
type: object
required:
- order_item_id
- quantity
title: ReturnRequestItem
description: A single product line on a return — which order item, how many.
securitySchemes:
BearerAuth:
type: apiKey
in: header
name: Authorization
description: Zinc API key (Bearer zn_...)
````