> ## 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 via the Zinc API
Zinc offers two ways to place orders depending on your business needs. Choose the approach that works best for you:
Use your own Amazon, Walmart, or other retailer account credentials. You have full control over orders and can use your preferred payment methods.
**Required fields:**
* `retailer` - The retailer code of the [supported retailer](/v1/supported-retailers)
* `products` - A list of product objects that should be ordered
* `retailer_credentials` - Your account login details
* `payment_method` - Credit card or gift card balance
* `billing_address` - Address associated with payment method
* `shipping_method` or `shipping` - The desired shipping method
* `shipping_address` - Where the order will be delivered
* `is_gift` - Boolean indicating if this is a gift order
Fund a balance with Zinc and we'll place orders using our managed retailer accounts. No need to create or maintain your own accounts.
**Required fields:**
* `addax: true` - Enables ZMA ordering
* `retailer` - The retailer code of the [supported retailer](/v1/supported-retailers)
* `products` - A list of product objects that should be ordered
* `shipping_address` - Where the order will be delivered
* `is_gift` - Boolean indicating if this is a gift order
* `max_price` - Maximum price in cents for the order
**Excluded fields:**
* `retailer_credentials`
* `payment_method`
* `billing_address`
**ZMA Queue System:** Orders are queued until a suitable fulfillment account is available. Default timeout is 4 hours. You can customize this with `"addax_queue_timeout": 14400` (seconds).
**ZMA Availability:** Currently available for Amazon.com only. [Contact sales](mailto:sales@zinc.io) to set up funding options.
## Order Flow
Making an order request will start an order. You'll receive a `request_id` in the response which you'll then use for retrieving the status of the order. The following illustration shows the flow for a typical order.
When placing an order, each product will have multiple offers from different sellers each with their own shipping options. To address this, use a product's seller selection criteria to filter offers and an order's shipping parameter to specify shipping preferences. Below is a flowchart of the process used to filter offers and select a shipping option.
### Default seller selection criteria
If a seller selection criteria object is not explicitly provided, then the API will use the default:
```json theme={null}
{
"prime": true,
"handling_days_max": 6,
"condition_in": ["New"]
}
```
### Some examples
**Tracking within 5 days:**
If you wanted to send your customer a tracking number within 5 days, you would set `handling_days_max` to `5` in your seller selection criteria. The Zinc API would then filter out all offers which would not ship and upload a tracking number within 5 days.
**Handling days filtering:**
If you specified `"handling_days_max": 6` in your seller selection criteria, then any offer that won't ship in 6 days or less from now would be excluded from your buying selection. Thus, if two sellers are offering the same product, but one has a guaranteed shipping date 10 days away and the other seller has a guaranteed shipping date 5 days away, the second seller's offer would be selected.
When no handling information is available, we use the longest projected arrival date of the product as the `handling_days_max`.
**Shipping method selection:**
If you set `"max_days": 5` on the shipping parameter, the Zinc API would attempt to select the cheapest shipping method that took fewer than 5 days to arrive. Thus, if there was a shipping method that took 3 days and cost ten dollars and another shipping method that took 7 days but cost two dollars, the first shipping option would be selected.
## OpenAPI
````yaml POST /v1/orders
openapi: 3.0.0
info:
title: Zinc API
version: 1.0.0
description: API for placing orders and retrieving product data from top retailers.
servers:
- url: https://api.zinc.io
description: Production server
security:
- basicAuth: []
paths:
/v1/orders:
post:
summary: Create Order
description: Place a new order with Zinc.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'200':
description: Order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderResponse'
components:
schemas:
CreateOrderRequest:
type: object
required:
- retailer
- products
- shipping_address
- is_gift
properties:
retailer:
type: string
description: The retailer code of the [supported retailer](/supported-retailers).
products:
type: array
description: A list of product objects that should be ordered.
items:
type: object
properties:
product_id:
type: string
description: The unique identifier for the product at the retailer.
quantity:
type: integer
description: The number of units to order.
seller_selection_criteria:
$ref: '#/components/schemas/SellerSelectionCriteria'
description: >-
A seller selection criteria object containing information
about which offers to choose when there are multiple offers
available.
required:
- product_id
- quantity
shipping_address:
$ref: '#/components/schemas/Address'
description: An address object to which the order will be delivered.
shipping_method:
type: string
description: >-
The desired shipping method for the object. Available methods are
`cheapest` (always select the cheapest method available), `fastest`
(always select the fastest method available), `amazon_day` (choose
default from Amazon or use `amazon_day` attribute from order),
`free` (which will fail for items without some sort of free
shipping), or `no_rush` (Amazon only - selects the slowest/cheapest
No-Rush shipping option). You must provide either this or the
`shipping` attribute, but not both.
shipping:
$ref: '#/components/schemas/Shipping'
description: >-
A shipping object with information as to which shipping method to
use. You must provide either this or the `shipping_method`
attribute, but not both.
billing_address:
$ref: '#/components/schemas/Address'
description: >-
An address object for the person associated with the credit card.
Required for self-managed accounts. Do not include when using ZMA
(`addax: true`).
payment_method:
$ref: '#/components/schemas/PaymentMethod'
description: >-
A payment method object containing payment information for the
order. Required for self-managed accounts. Do not include when using
ZMA (`addax: true`).
retailer_credentials:
$ref: '#/components/schemas/RetailerCredentials'
description: >-
A retailer credentials object for logging into the retailer with a
preexisting account. Required for self-managed accounts. Do not
include when using ZMA (`addax: true`).
addax:
type: boolean
description: >-
Set to true to enable Zinc Managed Accounts (ZMA). When true, do not
include `retailer_credentials`, `payment_method`, or
`billing_address` fields.
is_gift:
type: boolean
description: >-
Whether or not this order should be placed as a gift. Typically,
retailers will exclude the price of the items on the receipt if this
is set.
gift_message:
type: string
description: >-
A message to include on the packing slip for the recipient. Max 240
characters or 9 lines.
require_gift:
type: boolean
description: >-
If `is_gift` is true, setting `require_gift` to true will cause the
order to fail if any items in the order do not include a gift
option.
use_gift_wrap:
type: boolean
description: >-
(Amazon only) If true, enables gift wrapping for the order. Requires
`is_gift` to also be true.
webhooks:
$ref: '#/components/schemas/WebhooksObject'
client_notes:
type: object
description: >-
Any metadata to store on the request for future use. This object
will be passed back in the response.
promo_codes:
type: array
items:
$ref: '#/components/schemas/PromoCode'
description: A list of promotion codes to use at checkout.
strict_expired_product_id:
type: boolean
description: >-
Defaults to false. If `true`, fail orders where the `product_id` is
`expired` or `deprecated`. If unset or `false`, Amazon redirects to
a valid `product_id` and buys that one.
po_number:
type: number
description: >-
(Amazon business accounts only) Adds a purchase order number to the
order.
amazon_day:
type: string
description: >-
(Amazon only) Specify exact name of Amazon Day shipping selection
when ship_method is set to amazon_day.
fail_if_taxed:
type: boolean
description: >-
Defaults to `false`. If `true`, fail orders where taxes are included
in the total. Useful for ZMA orders which should not be placed if no
tax exempt account is available.
max_delivery_days:
type: number
description: >-
(Amazon only) Defaults to unlimited. If set, fail orders with error
`max_delivery_days_exceeded` if the retailer estimates delivery more
than this many days in the future.
take_buybox_offers:
type: boolean
description: >-
Bypass the process of looking at all offers - takes whatever the
default offer is on the item details page buy box.
force_offers_postal_code:
type: string
description: >-
Uses this postal code for offer selection instead of the
`shipping_address.zip_code` value.
zma_discount:
type: number
description: >-
The percent below (or above, if negative) face value that you will
be charged for this order. Can range from `-50` to `0`. Lower
discount orders will be processed before higher discount orders. If
discount is too high and we are unable to secure ordering at that
discount, the order will time out with
`zma_temporarily_overloaded`. Defaults to `0`.
addax_queue_timeout:
type: number
description: >-
Defaults to `14400`. Number of seconds an order will stay in the ZMA
queue before timing out with `zma_temporarily_overloaded`.
zma_prime_optout:
type: boolean
description: >-
Defaults to `false`. Set this value to `true` to force your ZMA
order to use a non-prime fulfillment account.
zma_priority_bid:
type: number
description: >-
A fixed-value bid used to prioritize ZMA orders. Successful orders
will include the bid value in their ZMA cost. A value of `100`
equals a bid of $1.00. Orders with higher bids get a higher
priority.
max_price:
type: integer
description: >-
The maximum price in cents for the order. If the final price exceeds
this number, the order will not go through and will return a
`max_price_exceeded` error. Required for ZMA orders (`addax: true`).
customs_id_number:
type: string
description: >-
ID number required for customs clearance on international shipments.
Required when shipping to certain countries. If needed but not
provided, the order will fail with a `customs_id_number_required`
error.
tax_exemption_opt_out:
type: boolean
description: >-
If true, opts out of tax exemption and requests that tax be charged
on the order. Useful for accounts that have tax exemption enabled
but need to be charged tax for a specific order.
disable_weekend_shipping:
type: boolean
description: >-
(Amazon only) If true, disables Saturday and Sunday delivery
options. The order will only be scheduled for weekday delivery.
CreateOrderResponse:
type: object
properties:
request_id:
type: string
SellerSelectionCriteria:
type: object
properties:
addon:
type: boolean
description: >-
(Amazon only) Specifies whether the selected offer should be an
addon item
buy_box:
type: boolean
description: >-
(Amazon only) Specifies whether the selected offer should be
Amazon's default buy box offer
condition_in:
type: array
items:
type: string
description: An array of item conditions that the Zinc API must order from
condition_not_in:
type: array
items:
type: string
description: An array of item conditions that the Zinc API must not order from
first_party_seller:
type: boolean
description: Is the seller first-party? e.g. sold by Walmart.com on walmart
handling_days_max:
type: integer
description: The maximum number of allowable days for shipping and handling
international:
type: boolean
description: >-
Specifies whether the item should come from an international
supplier
max_item_price:
type: integer
description: The maximum allowable price in cents for an item
merchant_id_in:
type: array
items:
type: string
description: >-
(Amazon only) An array of merchant ids that the Zinc API must order
from
merchant_id_not_in:
type: array
items:
type: string
description: >-
(Amazon only) An array of merchant ids that the Zinc API must not
order from
min_seller_num_ratings:
type: integer
description: >-
(Amazon only) The minimum number of ratings required for an Amazon
seller's offer to be selected
min_seller_percent_positive_feedback:
type: integer
description: >-
(Amazon only) The minimum percentage of positive ratings of an
Amazon seller for their offer to be selected
prime:
type: boolean
description: >-
(Amazon only) Specifies whether the selected offer should be an
Amazon Prime offer
allow_oos:
type: boolean
description: >-
(Amazon only) Specifies whether we should still attempt to complete
ordering with the cheapest offer if all offers appear unavailable
Address:
type: object
required:
- first_name
- last_name
- address_line1
- city
- state
- zip_code
- country
- phone_number
properties:
first_name:
type: string
last_name:
type: string
address_line1:
type: string
address_line2:
type: string
zip_code:
type: string
city:
type: string
state:
type: string
description: The USPS abbreviation for the state of the address (e.g. AK)
country:
type: string
description: >-
The ISO abbreviation for the country of the address (e.g. US). A
list of all available two-letter country codes can be found
[here](https://www.theodora.com/country_digraphs.html).
phone_number:
type: string
instructions:
type: string
description: Optional instructions to include with the shipping addresses
Shipping:
type: object
required:
- order_by
- max_days
- max_price
properties:
order_by:
type: string
description: >-
The ordering of available shipping methods that meet the desired
criteria. Available values are `price` or `speed`. If ordering by
price, then the Zinc API will choose the cheapest shipping method
that meets the desired criteria, while speed will choose the fastest
shipping method meeting the criteria.
max_days:
type: integer
description: The maximum number of days allowed for shipping on the order.
max_price:
type: integer
description: >-
The maximum price in cents allowed for the shipping cost of the
order.
PaymentMethod:
type: object
properties:
name_on_card:
type: string
number:
type: string
security_code:
type: string
expiration_month:
type: integer
expiration_year:
type: integer
use_gift:
type: boolean
RetailerCredentials:
type: object
properties:
email:
type: string
password:
type: string
totp_2fa_key:
type: string
WebhooksObject:
type: object
description: >-
A webhooks object including URLs that will receive `POST` requests after
particular events have finished. See
[Webhooks](/api-reference/introduction/webhooks) for more details.
properties:
request_succeeded:
type: string
description: The webhook URL to send data to when a request succeeds
request_failed:
type: string
description: The webhook URL to send data to when a request fails
tracking_obtained:
type: string
description: >-
The webhook URL to send data to when ALL tracking for an order is
retrieved (placing orders call only)
tracking_updated:
type: string
description: >-
The webhook URL to send data to when ANY tracking for an order is
retrieved (placing orders call only)
status_updated:
type: string
description: >-
The webhook URL to send data to when the status of a request is
updated
case_updated:
type: string
description: >-
The webhook URL to send data to when a ZMA case associated with the
order receives an update
PromoCode:
type: object
required:
- code
properties:
code:
type: string
description: The promo code to apply (required)
optional:
type: boolean
description: >-
Should we continue placing the order if this code fails to apply?
Defaults to false.
merchant_id:
type: string
description: >-
If supplied, only try this code if we selected an offer from the
given merchant.
discount_amount:
type: number
description: >-
Fixed amount in cents by which we should discount the matching
merchant's offers during offer selection. Only makes sense if
merchant_id is also supplied. Defaults to 0.
discount_percentage:
type: number
description: >-
Percentage amount (between 0 and 100) by which we should discount
the matching merchant's offers during offer selection. Only makes
sense if merchant_id is also supplied. Defaults to 0.
cost_override:
type: number
description: >-
If supplied, we will assume all offers by this merchant cost exactly
this many cents. Only makes sense if merchant_id is also supplied.
Overrides other discount methods.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Use your client token as the username. Leave the password blank.
````