> ## 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:
```json theme={null}
[
{
"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.
* **condition\_in** / **condition\_not\_in** - Condition allow/deny lists. Limit
which offers are eligible by item condition — useful for buying only new
items, or for accepting used items down to a floor. See
[Condition Filtering](/v2/api-reference/orders/multiple-products-quantities#condition-filtering).
## Shipping Address
All orders require a valid shipping address. Addresses are validated using Google's Address Validation API.
Required fields:
* `first_name` and `last_name`
* `address_line1` (use `address_line2` for apartment/suite, optional)
* `city`
* `postal_code`
* `phone_number`
Optional fields:
* `state` — omit for countries that don't use states/provinces
* `country` — ISO 3166-1 alpha-2 code (e.g. `US`, `CA`, `GB`, `DE`); defaults to `US`
International shipping is supported. Provide the destination `country` as an ISO 3166-1 alpha-2 code; `state` is optional where it doesn't apply.
## Payment
By default, orders draw from your prepaid [wallet](/v2/wallet) — no `payment` object needed. To charge your own end-customer's card instead and keep a margin, include a `payment` object with `mode: "connect"`. See the [Stripe Connect](/v2/connect) guide for the full flow.
| Field | Required | Description |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `mode` | | `"wallet"` (default) or `"connect"`. |
| `payment_method` | connect | Your end-customer's saved Stripe payment-method id (`pm_…`) on your connected account. |
| `customer` | connect | Your end-customer's Stripe Customer id (`cus_…`) on your connected account. |
| `margin` | connect | Your markup: `{ "type": "flat", "value": }` or `{ "type": "percent", "value": }`. |
In Connect mode the authorization hold is sized from `max_price`; your end-customer is charged the actual total when Zinc places the order with the retailer.
```json theme={null}
{
"payment": {
"mode": "connect",
"payment_method": "pm_1ExampleCard",
"customer": "cus_ExampleEndCustomer",
"margin": { "type": "flat", "value": 250 }
}
}
```
## 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 input to any fields during checkout that match.
* **po\_number** - Your internal purchase order number for tracking and reconciliation
* **is\_gift** - Mark the order as a gift (boolean, default `false`). Prices are
suppressed on the packing slip where the fulfillment method supports it.
* **handling\_days\_max** - Optional ceiling on a seller's handling days (integer,
minimum `1`). Offers from sellers whose handling time exceeds this are skipped.
Omit or send `null` for no limit.
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-06-26'
x-logo:
url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
contact:
name: Zinc API Support
email: support@zinc.com
url: https://zinc.com/docs
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. To find products
first, the /agent/* data endpoints (search, products/search,
products/offers, products/details) are MPP-paid at $0.01 per call;
/agent/search returns orderable URLs to feed straight into /agent/orders.
GET /retailers lists supported retailers for free (no payment or account).
Authenticated equivalents (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.
handling_days_max:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Handling Days Max
description: >-
Optional ceiling on a seller's shipping and handling days. Omit or
send null for no limit.
is_gift:
type: boolean
title: Is Gift
description: >-
Mark the order as a gift. Prices are suppressed on the packing slip
where the fulfillment method supports it.
default: false
payment:
anyOf:
- $ref: '#/components/schemas/OrderPayment'
- type: 'null'
description: Optional payment block. Omit for prepaid-wallet billing (default).
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
handling_days_max:
anyOf:
- type: integer
- type: 'null'
title: Handling Days Max
is_gift:
type: boolean
title: Is Gift
default: false
retailer_credentials_id:
anyOf:
- type: string
- type: 'null'
title: Retailer Credentials Id
retailer_credentials_uuid:
anyOf:
- type: string
- type: 'null'
title: Retailer Credentials Uuid
job_result:
anyOf:
- $ref: '#/components/schemas/OrderJobResult'
- type: 'null'
description: >-
Fulfillment result and price breakdown for a completed or failed
order; null while processing.
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: []
connect:
anyOf:
- $ref: '#/components/schemas/OrderConnectInfo'
- type: 'null'
description: >-
Stripe Connect charge details when this order was paid via Connect;
null for prepaid-wallet orders.
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)
condition_in:
anyOf:
- items:
$ref: '#/components/schemas/ProductCondition'
type: array
- type: 'null'
title: Condition In
description: >-
Condition allowlist. The agent only buys an offer whose condition is
in this list. Each value must be a canonical condition. Omit or send
null/[] for no constraint.
condition_not_in:
anyOf:
- items:
$ref: '#/components/schemas/ProductCondition'
type: array
- type: 'null'
title: Condition Not In
description: >-
Condition denylist. The agent will not buy an offer whose condition
is in this list. Each value must be a canonical condition. Omit or
send null/[] for no constraint.
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").
OrderPayment:
properties:
mode:
type: string
enum:
- wallet
- connect
title: Mode
default: wallet
payment_method:
anyOf:
- type: string
- type: 'null'
title: Payment Method
description: >-
Connect mode: the end-customer's vaulted Stripe payment-method id on
the customer's connected account.
customer:
anyOf:
- type: string
- type: 'null'
title: Customer
description: >-
Connect mode: the end-customer's Stripe Customer id (cus_…) on the
connected account. Required to charge a *reusable* saved card
off-session; omit only for a one-time, unattached payment method.
margin:
anyOf:
- $ref: '#/components/schemas/MarginSpec'
- type: 'null'
description: 'Connect mode: the customer''s margin on the order.'
type: object
title: OrderPayment
description: >-
Optional payment block. Absent or mode='wallet' ⇒ unchanged
prepaid-wallet
behavior. mode='connect' charges the end-customer's vaulted card in real
time
via Stripe Connect (see ConnectService).
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
condition_in:
anyOf:
- items:
$ref: '#/components/schemas/ProductCondition'
type: array
- type: 'null'
title: Condition In
condition_not_in:
anyOf:
- items:
$ref: '#/components/schemas/ProductCondition'
type: array
- type: 'null'
title: Condition Not In
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.
Field names mirror the OrderItem model, so callers build it with
``OrderItemResponse.model_validate(item)`` rather than enumerating
fields.
OrderJobResult:
properties:
success:
anyOf:
- type: boolean
- type: 'null'
title: Success
error:
anyOf:
- type: string
- type: 'null'
title: Error
error_type:
anyOf:
- type: string
- type: 'null'
title: Error Type
error_details:
anyOf:
- $ref: '#/components/schemas/ErrorDetails'
- type: 'null'
price_components:
anyOf:
- $ref: '#/components/schemas/OrderPriceComponents'
- type: 'null'
estimated_delivery:
anyOf:
- type: string
- type: 'null'
title: Estimated Delivery
merchant_order_ids:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Merchant Order Ids
additionalProperties: true
type: object
title: OrderJobResult
description: >-
Fulfillment result surfaced on a completed or failed order. Null while
the
order is still processing.
Lenient and open (``extra="allow"``) so it documents the common fields —
success, price breakdown, errors, merchant order ids, delivery estimate
—
without constraining the full processing payload, which carries
additional
internal detail.
TrackingNumberResponse:
properties:
id:
type: string
format: uuid
title: Id
carrier:
type: string
title: Carrier
tracking_number:
type: string
title: Tracking Number
status:
anyOf:
- $ref: '#/components/schemas/TrackingStatus'
- type: 'null'
description: Carrier-derived shipment state (pending, in_transit, delivered).
checkpoints:
items:
$ref: '#/components/schemas/TrackingCheckpointResponse'
type: array
title: Checkpoints
description: >-
Carrier scan events, most recent first. Empty unless the checkpoint
timeline was requested.
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.
``status`` is the authoritative carrier-derived shipment state and is
always
present. ``checkpoints`` is the per-scan timeline; it's embedded on the
single-order read (``GET /orders/{id}``) and, on the list endpoint, only
when ``include=tracking_events`` is requested.
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
OrderConnectInfo:
properties:
state:
type: string
title: State
description: secured | captured | released | refunded | …
secured_amount:
anyOf:
- type: integer
- type: 'null'
title: Secured Amount
order_cost:
anyOf:
- type: integer
- type: 'null'
title: Order Cost
description: Actual order cost (goods) captured when the order is placed.
customer_margin:
anyOf:
- type: integer
- type: 'null'
title: Customer Margin
zinc_fee:
anyOf:
- type: integer
- type: 'null'
title: Zinc Fee
stripe_fee:
anyOf:
- type: integer
- type: 'null'
title: Stripe Fee
final_charge:
anyOf:
- type: integer
- type: 'null'
title: Final Charge
transfer_amount:
anyOf:
- type: integer
- type: 'null'
title: Transfer Amount
payment_intent_id:
anyOf:
- type: string
- type: 'null'
title: Payment Intent Id
connected_account_id:
anyOf:
- type: string
- type: 'null'
title: Connected Account Id
simulated:
type: boolean
title: Simulated
default: false
type: object
required:
- state
title: OrderConnectInfo
description: >-
Stripe Connect charge + state for an order paid via Connect. Present
only
when the order has a Connect profile; ``null`` for prepaid-wallet
orders. All
amounts in cents.
``state`` moves ``secured`` → ``captured`` (or ``released``/``refunded``
on a
terminal outcome). The post-capture fields (``order_cost`` and below)
are
populated once Zinc places the order with the retailer and the actual
total
is captured.
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.).
ProductCondition:
type: string
enum:
- New
- Refurbished
- UsedLikeNew
- UsedVeryGood
- UsedGood
- UsedAcceptable
title: ProductCondition
description: >-
Canonical product-condition strings for condition filtering.
Matching against ``condition_in`` / ``condition_not_in`` is exact and
case-sensitive against these *values*. The vocabulary matches the Zinc
v1
API's ``seller_selection_criteria`` condition strings. The Sonic
worker's
CANONICAL_CONDITIONS (``src/agent/schemas.py``) must use the same
strings,
since they ride through the job payload unchanged.
The member *name* is the corresponding Amazon BizAPI offer condition
code
(see ``CONDITION_MAP`` in ``bizapi_service``), so the canonical→BizAPI
mapping is derived from the enum rather than maintained as a separate
table.
MarginSpec:
properties:
type:
type: string
enum:
- flat
- percent
title: Type
value:
type: number
minimum: 0
title: Value
description: >-
Cents when type='flat'; a percentage when type='percent' (e.g. 15 ==
15%).
type: object
required:
- type
- value
title: MarginSpec
description: Customer's markup on the order cost (computed before fees).
OrderItemStatus:
type: string
enum:
- pending
- processing
- ordered
- shipped
- delivered
- cancelled
- failed
title: OrderItemStatus
ErrorDetails:
properties:
code:
type: string
title: Code
message:
type: string
title: Message
address_validation_reasons:
items:
type: string
type: array
title: Address Validation Reasons
default: []
field_errors:
items:
$ref: '#/components/schemas/FieldError'
type: array
title: Field Errors
default: []
additionalProperties: true
type: object
required:
- code
- message
title: ErrorDetails
description: |-
Structured detail for a failed job.
Additive sibling to the flat `error`/`error_type` keys (kept for
back-compat). The structured home for enrichment beyond the category +
message — e.g. why a shipping address was rejected — so we don't keep
growing loose top-level keys on the job output.
OrderPriceComponents:
properties:
subtotal:
anyOf:
- type: integer
- type: 'null'
title: Subtotal
tax:
anyOf:
- type: integer
- type: 'null'
title: Tax
shipping:
anyOf:
- type: integer
- type: 'null'
title: Shipping
total:
anyOf:
- type: integer
- type: 'null'
title: Total
description: Order total in `currency` (subtotal + tax + shipping).
converted_payment_total:
anyOf:
- type: integer
- type: 'null'
title: Converted Payment Total
description: '`total` converted to the currency actually charged.'
currency:
anyOf:
- type: string
- type: 'null'
title: Currency
payment_currency:
anyOf:
- type: string
- type: 'null'
title: Payment Currency
line_items:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Line Items
description: Itemized rows, each `{description, amount, category}`.
additionalProperties: true
type: object
title: OrderPriceComponents
description: >-
Retailer price breakdown for an order, all amounts in cents.
Lenient by design — every field is optional and unknown keys are
preserved
(``extra="allow"``) — because it mirrors fulfillment output that may be
partial (e.g. a failed order) or carry extra detail. Documents the
common
fields without revalidating the raw payload.
TrackingStatus:
type: string
enum:
- pending
- in_transit
- delivered
title: TrackingStatus
description: Carrier-derived shipment state for a TrackingNumber.
TrackingCheckpointResponse:
properties:
checkpoint_time:
type: string
format: date-time
title: Checkpoint Time
description: When the carrier recorded this scan event.
status:
$ref: '#/components/schemas/TrackingStatus'
description: Carrier-derived shipment state at this checkpoint.
message:
type: string
title: Message
description: Carrier-provided description of the scan.
city:
anyOf:
- type: string
- type: 'null'
title: City
state:
anyOf:
- type: string
- type: 'null'
title: State
country:
anyOf:
- type: string
- type: 'null'
title: Country
zip:
anyOf:
- type: string
- type: 'null'
title: Zip
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: Free-form location string when city/state are absent.
type: object
required:
- checkpoint_time
- status
- message
title: TrackingCheckpointResponse
description: A single carrier-reported scan event for a tracking number.
ReturnRequestStatus:
type: string
enum:
- open
- approved
- denied
- credited
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.
FieldError:
properties:
field:
type: string
title: Field
code:
type: string
title: Code
message:
type: string
title: Message
default: ''
received:
title: Received
expected:
anyOf:
- type: string
- type: 'null'
title: Expected
additionalProperties: true
type: object
required:
- field
- code
title: FieldError
description: >-
A single field-level validation failure from a worker.
Mirrors Sonic's `FieldError` (src/agent/types.py): when a job fails
schema
validation the worker reports one of these per offending field, so
consumers
can show "state should be 'NY', got 'New York'" instead of a bare count.
securitySchemes:
BearerAuth:
type: apiKey
in: header
name: Authorization
description: Zinc API key (Bearer zn_...)
````