> ## 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
> Place a purchase order on Amazon, Walmart, and other retailers via the Zinc API.
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. Zinc resolves the retailer from the URL itself, and will attempt checkout at most online stores — not only the ones in the [retailer catalog](/docs/v2/api-reference/retailers/list-retailers). That catalog is the set Zinc verifies with daily test orders, not the limit of what it can buy from: a store missing from it is not unsupported.
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.
Holding a URL you are unsure about? [`GET /retailers/check`](/docs/v2/api-reference/retailers/check-retailer) answers whether Zinc will order from that store and ship it to a given country, before you submit. It applies the same gates as this endpoint, so the two cannot disagree.
An order can contain at most **10 products**. More than that is rejected with
`422` / `validation_error` — `Order cannot contain more than 10 items`. The limit
is on entries in the `products` array, not units: one entry with `quantity: 50`
still counts as one. See
[The Products Array](/docs/v2/api-reference/orders/multiple-products-quantities#products-array).
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](/docs/v2/api-reference/orders/multiple-products-quantities#condition-filtering).
## Products Zinc cannot buy
Some items can't be purchased through Zinc no matter which account places the order.
They fail with `product_unavailable` at checkout rather than being rejected when you
submit, so filter them out of your catalog up front:
* **Digital goods** — e-books, downloads, digital video
* **Gift cards**, including e-gift cards
* **Customized or personalized items** — anything configured on the product page
* **Retailer-assembled bundles**
* **Groceries** — Amazon Fresh and Whole Foods
* **Pharmacy items**
* **Services** — installation, at-home service, and similar add-ons
* **Magazine subscriptions**
* **Restricted items** — anything the retailer prohibits from automated purchase
An offer can also be unbuyable for the account placing the order: business-only offers
can't be bought on a consumer account, and some consumer-only items can't be bought on
a business account. Both surface as `product_unavailable`. See
[Retailer Accounts](/docs/v2/retailer-accounts) if you're placing orders on your own account.
## 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` — for a US address this must be a ZIP: five digits, optionally `+4` (`98632` or `27517-8761`)
* `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.
## Which account places the order
By default Zinc places the order on its own accounts and you pay for the item out of
your wallet. To have it placed on your own retailer account instead, pass that account's
`short_id` as `retailer_credentials_id` — orders on your own account are charged the API
fee only. Zinc never selects one of your saved accounts for you, so send the field on
every order that needs it. See [Retailer Accounts](/docs/v2/retailer-accounts).
## Payment
By default, orders draw from your prepaid [wallet](/docs/v2/wallet) — no `payment` object needed. To charge your end-customer's card instead and keep a margin, send a `payment` object with `mode: "connect"`. See the [Stripe Connect](/docs/v2/connect) guide for the full flow.
| Field | Required | Description |
| - | - | - |
| `mode` | | `"wallet"` (default) or `"connect"`. |
| `payment_method` | connect | Your end-customer's saved payment-method id 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`, and the card is charged the actual total when Zinc places the order with the retailer.
### Connect mode
```json theme={null}
{
"payment": {
"mode": "connect",
"payment_method": "pm_1ExampleCard",
"customer": "cus_ExampleEndCustomer",
"margin": { "type": "flat", "value": 250 }
}
}
```
## Fulfillment preferences
An order is **strict by default**: if any rule can't be met — an item can't be
bought, the retailer caps the quantity, the gift option isn't offered — the whole
order fails and nothing ships.
The optional `fulfillment` object relaxes that one concern at a time. Each key
takes the mode to hold that rule at, and the only mode today is `"best_effort"`.
Anything you leave out stays strict, so an omitted `fulfillment` block and an
empty one mean exactly the same strict order.
| Concern | With `"best_effort"` | Strict failure it replaces |
| - | - | - |
| `items` | An item that can't be bought is skipped and the rest ship. That item's status becomes `skipped`. | `product_not_found`, `product_out_of_stock`, `product_variant_unavailable`, `add_to_cart_failed` |
| `quantity` | If the retailer caps an item below the quantity you asked for, buy the cap. | `quantity_limit_exceeded` |
| `gift` | If the retailer offers no free gift option, place a normal order instead. Requires `is_gift: true`. | `gift_option_unavailable` |
```json theme={null}
{
"fulfillment": {
"items": "best_effort",
"quantity": "best_effort"
}
}
```
`max_price` is never relaxed. No fulfillment setting will let an order exceed the
ceiling you set.
Two things hold no matter what you relax:
* **An empty cart still fails.** If every item ends up skipped, the order fails
with `cart_empty` rather than placing an order for nothing.
* **Unknown keys and unknown modes are rejected, not ignored.** A typo like
`"itmes"` or `"best-effort"` returns a `422`, so a mistake can never quietly
leave a rule strict when you meant to relax it.
Whatever was actually relaxed is reported back in `fulfillment.concessions` on
the order, so a placed order always tells you what it did — see
[Fulfillment](/docs/v2/api-reference/orders/get-order#fulfillment).
`fulfillment` is also accepted on [`POST /agent/orders`](/docs/v2/api-reference/agent/create-order), which shares the same order-creation schema.
### Excluding merchants
`fulfillment.excluded_merchants` goes the other way: it makes an order stricter. List up to 20 merchants the order must never be bought from. Each entry is either a seller's display name as shown on the retailer's storefront, or an Amazon Business merchant id (`amzn1.…`). Names are matched ignoring case and spacing.
```json theme={null}
{
"fulfillment": {
"excluded_merchants": ["Acme Resellers", "amzn1.pa.o.EXAMPLE"]
}
}
```
The list is added to any blocklist already on your account. It can bar more merchants but can never allow one your account already bars. The order echoes it back as `fulfillment.excluded_merchants`.
`excluded_merchants` currently applies to Amazon Business orders only and is ignored for other retailers.
## 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`), suppressing
prices on the packing slip. See [Gift orders](#gift-orders) for the failure
behavior when a retailer offers no gift option.
* **gift\_message** - Optional note for the recipient, entered into the retailer's
gift-message field at checkout (string, max 240 characters). Requires `is_gift`
to be `true`.
* **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.
## Gift orders
Setting `is_gift: true` suppresses prices on the packing slip. Because a gift that
arrives with prices visible to the recipient is worse than no order at all, this is
treated as a hard requirement rather than a preference:
If the retailer's checkout offers no free gift option, the order **fails** with
`gift_option_unavailable` instead of being placed as a normal order. Handle this
error type if you offer gifting as an optional add-on — see
[Order Processing Errors](/docs/v2/api-reference/introduction/error-handling#gift-errors).
If gifting is a nice-to-have rather than the point of the order, you can opt out
of that failure instead of catching it: send `fulfillment: { "gift": "best_effort" }`
and a retailer with no gift option gets a normal order rather than none. See
[Fulfillment preferences](#fulfillment-preferences).
`gift_message` is best-effort by contrast: it's delivered where the retailer's
checkout offers a gift-message field, and the order is still placed without it
where one isn't available.
```json theme={null}
{
"is_gift": true,
"gift_message": "Happy birthday! Hope you enjoy it."
}
```
`is_gift` and `gift_message` are also accepted on [`POST /agent/orders`](/docs/v2/api-reference/agent/create-order), which shares the same order-creation schema.
## 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.
Supported retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon CA,
Amazon DE, Amazon FR, Amazon MX, Amazon UK, Barnes & Noble, Best Buy, Chewy,
Gap, and 18 more. Ships to the US and 6 other countries (CA, DE, FR, GB, IT,
MX). The listed retailers are the ones Zinc verifies with daily test orders,
not the limit of what Zinc can buy from: checkout is attempted at most
online stores, including Shopify-hosted ones. To ask about a specific store
before ordering, call GET /retailers/check?url=... — it answers whether Zinc
will attempt that URL.
version: '2026-10-09'
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 from a supported
retailer, a 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_); those orders are paid from a prefunded
wallet — GET /wallet/me returns the spendable balance and per-order fee, so
check it before POST /orders to avoid a 402. Orders are strict by default:
if the gift option can't be applied or any item can't be bought, the whole
order fails. When the user wants whatever can be shipped, send fulfillment:
{"gift": "best_effort", "items": "best_effort"} and read
fulfillment.concessions on the order to see what was relaxed. max_price is
never relaxed. Docs: https://zinc.com/docs Supported retailers include
1-800-Flowers, Ace Hardware, Amazon, Amazon CA, Amazon DE, Amazon FR, Amazon
MX, Amazon UK, Barnes & Noble, Best Buy, Chewy, Gap, and 18 more, shipping
to the US and 6 other countries (CA, DE, FR, GB, IT, MX). The listed
retailers are the ones Zinc verifies with daily test orders, not the limit
of what Zinc can buy from: checkout is attempted at most online stores,
including Shopify-hosted ones. To ask about a specific store before
ordering, call GET /retailers/check?url=... — it answers whether Zinc will
attempt that URL.
x-supported-retailers:
- 1-800-Flowers
- Ace Hardware
- Amazon
- Amazon CA
- Amazon DE
- Amazon FR
- Amazon MX
- Amazon UK
- Barnes & Noble
- Best Buy
- Chewy
- Gap
- Grainger
- IBS
- Lowe's
- Macys
- McMaster-Carr
- Partstown
- Pokémon Center
- Sephora
- Target
- The Home Depot
- TikTok
- Uniqlo
- Walmart
- Wayfair
- Zinc
- eBay
- libraccio
- zazzle
x-supported-countries:
- US
- CA
- DE
- FR
- GB
- IT
- MX
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/CheckoutOrderCreate'
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:
CheckoutOrderCreate:
properties:
products:
items:
$ref: '#/components/schemas/OrderProduct'
type: array
minItems: 1
title: Products
shipping_address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
description: Where to ship. Required for wallet and Connect orders.
max_price:
type: integer
minimum: 0
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 one of your own saved
retailer accounts to place this order on. The item is then paid for
by the payment method saved on that account, and your wallet is
charged the API fee only — so the balance needed to place the order
is the fee, not max_price + fee. Omit it and the order is placed on
a Zinc account and funded from your wallet; Zinc never substitutes
one of your saved accounts, so send this field on every order that
has to run on yours.
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, suppressing prices on the packing slip. If
the retailer's checkout offers no free gift option, the order FAILS
with `gift_option_unavailable` rather than being placed as a normal
order — a gift that arrives with prices visible to the recipient is
treated as worse than no order.
default: false
gift_message:
anyOf:
- type: string
maxLength: 240
- type: 'null'
title: Gift Message
description: >-
Optional note for the recipient, entered into the retailer's
gift-message field at checkout. Requires `is_gift` to be true. Max
240 characters. Delivered where the retailer's checkout offers a
gift message; the order is still placed without it where one isn't
available.
payment:
anyOf:
- $ref: '#/components/schemas/OrderPayment'
- type: 'null'
description: Optional payment block. Omit for prepaid-wallet billing (default).
customer_notifications:
anyOf:
- $ref: '#/components/schemas/CustomerNotifications'
- type: 'null'
description: >-
Opt in to emailing the end customer order updates (and unlock the
public tracking page for this order). Adds a per-order surcharge.
Omit for no customer notifications (default).
fulfillment:
anyOf:
- $ref: '#/components/schemas/FulfillmentPreferences'
- type: 'null'
description: >-
Loosen the order's strict-by-default rules. Omit for today's
behaviour: any rule that can't be met fails the order. Set a rule
(`gift`, `items`, `quantity`) to `best_effort` to have the order
placed anyway; anything left unset stays strict. Whatever was
relaxed is reported back in `fulfillment.concessions` on the order.
`max_price` is never relaxed. `excluded_merchants` tightens instead:
merchants this order must not be bought from.
type: object
required:
- products
- max_price
title: CheckoutOrderCreate
description: Request body for ``POST /orders``.
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
gift_message:
anyOf:
- type: string
- type: 'null'
title: Gift Message
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.
merchant_order_ids:
items:
type: string
type: array
title: Merchant Order Ids
description: >-
The retailer's own order number(s) for this order (e.g. an Amazon
`113-…` ID), as recorded when it was placed. Empty while processing,
or if the order never reached the retailer.
default: []
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.
payment:
anyOf:
- $ref: '#/components/schemas/OrderPaymentInfo'
- type: 'null'
description: >-
Card hold details when this order was paid by card outside the
wallet and Connect; null for wallet and Connect orders.
customer_notifications:
anyOf:
- $ref: '#/components/schemas/CustomerNotificationStatus'
- type: 'null'
description: >-
End-customer email-notification status when the order opted into the
notifications add-on; null when it didn't.
fulfillment:
$ref: '#/components/schemas/OrderFulfillment'
description: >-
`gift`/`items`/`quantity`: the mode this order asked for on each
rule (all null = strict). `concessions`: every rule that actually
was relaxed, with the worker's code and the item it concerned. Empty
concessions means the order was fulfilled exactly as requested.
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
maxLength: 60
title: Address Line1
description: >-
Street address. At most 60 characters — retailers reject a longer
line outright rather than truncating it.
address_line2:
anyOf:
- type: string
maxLength: 60
- type: 'null'
title: Address Line2
description: >-
Apartment, suite, unit, etc. At most 60 characters — retailers
reject a longer line outright rather than truncating it.
city:
type: string
title: City
state:
anyOf:
- type: string
- type: 'null'
title: State
postal_code:
type: string
title: Postal Code
description: >-
Postal code. For a US address this must be a ZIP: 5 digits,
optionally +4 (e.g. '98632' or '27517-8761').
phone_number:
type: string
title: Phone Number
country:
type: string
title: Country
description: >-
Country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'CA', 'GB', 'DE').
Case-insensitive. Longer spellings such as 'USA' or 'United States'
are rejected — the error names the code to use.
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"), which are required rather
than
inferred — a longer spelling like "USA" is rejected with the code to
use, so
everything downstream can rely on seeing alpha-2.
OrderPayment:
properties:
mode:
type: string
enum:
- wallet
- card
- connect
title: Mode
default: wallet
payment_method:
anyOf:
- type: string
- type: 'null'
title: Payment Method
description: >-
Connect mode: the end-customer's vaulted payment-method id on the
connected account. Required for connect mode.
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' draws the order from the
prepaid wallet. mode='connect' charges the end-customer's saved card
through
Stripe Connect and keeps your margin (see ConnectService).
CustomerNotifications:
properties:
email:
type: string
format: email
title: Email
description: End-customer email address to send order updates to.
type: object
required:
- email
title: CustomerNotifications
description: |-
Opt-in to email the END customer as this order progresses.
Providing this block opts the order into the notifications add-on: a
per-order surcharge is applied and the public tracking page becomes
reachable for the order. The feature is gated server-side by
``customer_emails_enabled``; while that's off the block has no effect.
FulfillmentPreferences:
properties:
gift:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if the retailer offers no free gift option, place a
normal order instead of failing with `gift_option_unavailable`.
Requires `is_gift: true`. Omit to keep the gift requirement strict.
items:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if an item can't be bought (not found, out of stock,
variant or condition unavailable, add-to-cart failed), skip it and
ship the rest — its status becomes `skipped`. An empty cart still
fails. Omit for all-or-nothing.
quantity:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if the retailer caps an item below the requested
quantity, buy the cap instead of failing with
`quantity_limit_exceeded`. Omit to require the full quantity.
excluded_merchants:
anyOf:
- items:
type: string
type: array
maxItems: 20
- type: 'null'
title: Excluded Merchants
description: >-
Merchants this order must never be bought from: a display name as
shown on the retailer's storefront (matched ignoring case and
spacing) or an Amazon Business `amzn1.` merchant id. At most 20
entries. Added to any blocklist already on your account; it can only
bar more merchants, never allow a barred one. Currently applied to
Amazon Business orders only and ignored elsewhere.
additionalProperties: false
type: object
title: FulfillmentPreferences
description: >-
Which strict order rules may be relaxed. The order contract is strict by
default; this object only ever loosens it.
One key per concern — ``gift``, ``items``, ``quantity`` — whose value is
the
mode to hold that rule at. Absent (or null) is today's behaviour, so an
omitted block and ``{}`` mean the same strict order. There is
deliberately
no ``"strict"`` mode to write — the existing fields already mean that
(``is_gift: true`` is a required gift; a products list is
all-or-nothing),
and a second spelling of the same intent is a second thing to get wrong.
Unknown keys and unknown modes are rejected rather than ignored, so a
typo
can never silently mean "strict".
Extension point: a softer mode for a concern is a new
``FulfillmentMode``
member (``prefer``, ``nearest``); a per-concern knob is that concern's
value
widening from a bare mode into an object (``items: {mode: "best_effort",
min_items: 2}``) — never a new top-level order field.
The one exception to "only loosens" is ``excluded_merchants``: a
per-order
seller blocklist, here rather than top-level because it is rare and only
some placement paths can honour it (BizAPI today; ignored elsewhere). It
is
not a ``FulfillmentConcern`` and never produces a concession.
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
error_type:
anyOf:
- type: string
- type: 'null'
title: Error Type
tracking_number_ids:
anyOf:
- items:
type: string
format: uuid
type: array
- type: 'null'
title: Tracking Number Ids
description: >-
Ids of the `tracking_numbers[]` known to carry this item, best
effort. Null when unknown (never an empty list). The reverse of
`tracking_numbers[].order_item_ids`.
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
zinc_tracking_number:
anyOf:
- type: string
- type: 'null'
title: Zinc Tracking Number
description: >-
Zinc-issued tracking number under pseudo-carrier ZNLOGIC (format
ZPY…YQ). Carrier-independent alias for this shipment; assigned once
and never changes, even if the carrier tracking is corrected.
zinc_tracking_url:
anyOf:
- type: string
- type: 'null'
title: Zinc Tracking Url
description: Public tracking URL for the Zinc tracking number (17track.net).
status:
anyOf:
- $ref: '#/components/schemas/TrackingStatus'
- type: 'null'
description: Carrier-derived shipment state (pending, in_transit, delivered).
estimated_delivery_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Estimated Delivery Date
description: >-
Carrier-reported delivery estimate for this shipment, as a
destination-local calendar date. Refreshed on every carrier poll;
null when the carrier hasn't reported one.
delivery_proof_url:
anyOf:
- type: string
- type: 'null'
title: Delivery Proof Url
description: >-
URL of the carrier's proof-of-delivery photo, when one was captured.
Typically appears once the shipment is delivered; null when none is
available.
checkpoints:
items:
$ref: '#/components/schemas/TrackingCheckpointResponse'
type: array
title: Checkpoints
description: >-
Carrier scan events, most recent first. Empty unless the checkpoint
timeline was requested.
order_item_ids:
anyOf:
- items:
type: string
format: uuid
type: array
- type: 'null'
title: Order Item Ids
description: >-
Ids of the `items[]` this package carries, best effort. Null when
unknown (never an empty list). Populated when the order has one
item, or once a single-package order is delivered; see
`item_mapping` for how much to trust it.
item_mapping:
anyOf:
- type: string
enum:
- exact
- inferred
- type: 'null'
title: Item Mapping
description: >-
Confidence of `order_item_ids`: `exact` means the package cannot
carry anything else; `inferred` means at least one entry is a
best-effort guess. Null when `order_item_ids` is null.
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: []
credited_amount:
type: integer
title: Credited Amount
description: >-
Total wallet credit issued for this return, in cents. 0 until a
credit is issued (and on returns resolved without one). Credits are
append-only, so this is the running total across every credit and
reversal on the return, not the last one.
default: 0
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.
OrderPaymentInfo:
properties:
mode:
type: string
const: card
title: Mode
default: card
state:
type: string
title: State
description: authorized | captured | released | refunded | …
authorized_cents:
type: integer
title: Authorized Cents
fee_cents:
type: integer
title: Fee Cents
stripe_fee_cents:
anyOf:
- type: integer
- type: 'null'
title: Stripe Fee Cents
description: >-
Card-processing fee grossed into the amount above, the same way a
wallet top-up and a Connect charge gross it in.
captured_cents:
anyOf:
- type: integer
- type: 'null'
title: Captured Cents
payment_method:
anyOf:
- type: string
- type: 'null'
title: Payment Method
payment_intent_id:
anyOf:
- type: string
- type: 'null'
title: Payment Intent Id
simulated:
type: boolean
title: Simulated
default: false
type: object
required:
- state
- authorized_cents
- fee_cents
title: OrderPaymentInfo
description: >-
Card hold details for an order paid by card outside the wallet and
Connect, and where that hold stands. ``null`` for wallet and Connect
orders
(Connect has its own ``connect`` block). All amounts in cents.
``state`` moves ``authorized`` → ``captured`` when the retailer order is
placed (``captured_cents`` = actual total + fee), or → ``released`` when
the
order fails or is cancelled first. The card is only ever charged
``captured_cents``; the difference to ``authorized_cents`` is released.
CustomerNotificationStatus:
properties:
email:
type: string
title: Email
delivered:
anyOf:
- type: boolean
- type: 'null'
title: Delivered
type: object
required:
- email
title: CustomerNotificationStatus
description: >-
End-customer email-notification status for an order.
Present only when the order opted into the notifications add-on.
``delivered``
is the deliverability signal: True once a notification reached the
shopper
(an unsubscribe click also counts — it proves receipt), False if one was
attempted but bounced/failed/suppressed, and null while nothing has been
sent yet (e.g. not shipped) or a send is still in flight.
OrderFulfillment:
properties:
gift:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if the retailer offers no free gift option, place a
normal order instead of failing with `gift_option_unavailable`.
Requires `is_gift: true`. Omit to keep the gift requirement strict.
items:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if an item can't be bought (not found, out of stock,
variant or condition unavailable, add-to-cart failed), skip it and
ship the rest — its status becomes `skipped`. An empty cart still
fails. Omit for all-or-nothing.
quantity:
anyOf:
- $ref: '#/components/schemas/FulfillmentMode'
- type: 'null'
description: >-
`best_effort`: if the retailer caps an item below the requested
quantity, buy the cap instead of failing with
`quantity_limit_exceeded`. Omit to require the full quantity.
excluded_merchants:
anyOf:
- items:
type: string
type: array
maxItems: 20
- type: 'null'
title: Excluded Merchants
description: >-
Merchants this order must never be bought from: a display name as
shown on the retailer's storefront (matched ignoring case and
spacing) or an Amazon Business `amzn1.` merchant id. At most 20
entries. Added to any blocklist already on your account; it can only
bar more merchants, never allow a barred one. Currently applied to
Amazon Business orders only and ignored elsewhere.
concessions:
items:
$ref: '#/components/schemas/FulfillmentConcession'
type: array
title: Concessions
default: []
type: object
title: OrderFulfillment
description: |-
What was asked (the per-concern modes, all null on a strict order) plus
what was actually relaxed (``concessions``, empty when the order was
fulfilled exactly as requested — which is every strict order).
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.
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).
FulfillmentMode:
type: string
enum:
- best_effort
title: FulfillmentMode
description: >-
How hard to hold one order rule — the value of a ``fulfillment`` key
(``fulfillment.items: "best_effort"``).
Every mode loosens; strict is the *absence* of a mode, never a spelling
of
one. A future softer mode for a concern (``prefer``, ``nearest``) is a
new
member here; a future per-concern knob is that concern's value growing
from
a bare mode into an object — neither is a new top-level order field.
OrderItemStatus:
type: string
enum:
- pending
- processing
- ordered
- shipped
- available_for_pickup
- delivered
- cancelled
- failed
- skipped
title: OrderItemStatus
ErrorDetails:
properties:
code:
type: string
title: Code
message:
type: string
title: Message
url:
anyOf:
- type: string
- type: 'null'
title: Url
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: []
line_rejections:
items:
$ref: '#/components/schemas/LineRejection'
type: array
title: Line Rejections
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
discount:
anyOf:
- type: integer
- type: 'null'
title: Discount
description: >-
Promotion/free-shipping discount applied by the retailer, as a
positive magnitude subtracted from the total. A nonzero `shipping`
paired with an equal `discount` means shipping was itemized but
waived — the total correctly excludes it.
fees:
anyOf:
- type: integer
- type: 'null'
title: Fees
description: >-
Retailer fees not folded into subtotal/shipping/tax (gift wrap,
import/regulatory charges), as a positive magnitude added to the
total. Surfaced so a total exceeding the shown parts reads as an
itemized fee rather than an unexplained charge.
total:
anyOf:
- type: integer
- type: 'null'
title: Total
description: >-
Order total in `currency` (subtotal + tax + shipping + fees −
discount).
converted_payment_total:
anyOf:
- type: integer
- type: 'null'
title: Converted Payment Total
description: >-
`total` converted to `payment_currency`, the currency actually
charged. On an order billed in USD from a non-USD `currency`, this
is the USD amount charged, including the FX markup; `total` stays in
the retailer's currency. Equal to `total` when no conversion was
charged.
currency:
anyOf:
- type: string
- type: 'null'
title: Currency
payment_currency:
anyOf:
- type: string
- type: 'null'
title: Payment Currency
cart_items:
anyOf:
- items:
$ref: '#/components/schemas/OrderCartItem'
type: array
- type: 'null'
title: Cart Items
description: >-
Per-product rows making up `subtotal`. Distinct from `line_items`,
which carries order-level adjustments (discounts, fees) and shares
no fields with these — a discount is never a cart row. Null when the
retailer's checkout page did not expose readable line items, so
handle both `null` and `[]`. Individual fields may also be null on a
row we could only partly read. Best-effort: `sum(line_total)`
normally equals `subtotal`, but that is not guaranteed and must not
be used as a billing input — the charge is always driven by `total`.
line_items:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Line Items
description: >-
Order-level adjustments, each `{description, amount, category}`.
Null — not `[]` — when the producer didn't supply them, which is
every BizAPI-placed order today, so null-check before iterating.
breakdown_recorded:
anyOf:
- type: boolean
- type: 'null'
title: Breakdown Recorded
description: >-
False when `subtotal`/`tax`/`shipping` are placeholders rather than
observed figures — an order an operator recorded by hand without
itemizing the whole of what they paid. Those fields read `0` in that
case, which must NOT be shown as '$0.00 tax': nothing was recorded.
`total` is authoritative either way. Null on results written before
this flag existed; treat null as true.
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
- available_for_pickup
- delivered
- undeliverable
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.
FulfillmentConcession:
properties:
concern:
type: string
enum:
- gift
- items
- quantity
title: Concern
code:
type: string
title: Code
description: Worker error code that would have failed a strict order.
message:
anyOf:
- type: string
- type: 'null'
title: Message
item_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Item Id
description: Order item this concession is about, if any.
url:
anyOf:
- type: string
- type: 'null'
title: Url
requested_quantity:
anyOf:
- type: integer
- type: 'null'
title: Requested Quantity
fulfilled_quantity:
anyOf:
- type: integer
- type: 'null'
title: Fulfilled Quantity
additionalProperties: true
type: object
required:
- concern
- code
title: FulfillmentConcession
description: One rule that was actually relaxed while placing the order.
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.
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.
LineRejection:
properties:
url:
anyOf:
- type: string
- type: 'null'
title: Url
product_id:
anyOf:
- type: string
- type: 'null'
title: Product Id
requested_quantity:
anyOf:
- type: integer
- type: 'null'
title: Requested Quantity
available_quantity:
anyOf:
- type: integer
- type: 'null'
title: Available Quantity
codes:
items:
type: string
type: array
title: Codes
default: []
messages:
items:
type: string
type: array
title: Messages
default: []
type: object
title: LineRejection
description: One order line the retailer rejected, as it reported it (BizAPI).
OrderCartItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
product_id:
anyOf:
- type: string
- type: 'null'
title: Product Id
description: >-
Retailer product identifier (Amazon ASIN, Walmart item number, SKU)
when one is visible on the page. Often absent — do not rely on it to
join rows back to the requested products.
quantity:
anyOf:
- type: integer
- type: 'null'
title: Quantity
unit_price:
anyOf:
- type: integer
- type: 'null'
title: Unit Price
description: Price per unit.
line_total:
anyOf:
- type: integer
- type: 'null'
title: Line Total
description: >-
Total for this row, normally `quantity * unit_price`. May differ
when the retailer applies a per-line promotion.
additionalProperties: true
type: object
title: OrderCartItem
description: |-
A single product row from the retailer's cart or order summary.
Lenient and open (``extra="allow"``) like its siblings — it mirrors
fulfillment output that may be partial. All amounts are in cents.
securitySchemes:
BearerAuth:
type: apiKey
in: header
name: Authorization
description: Zinc API key (Bearer zn_...)
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.