Skip to main content
POST
/
v1
/
orders
Create Order
curl --request POST \
  --url https://api.zinc.io/v1/orders \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '{
  "retailer": "<string>",
  "products": [
    {
      "product_id": "<string>",
      "quantity": 123,
      "seller_selection_criteria": {
        "addon": true,
        "buy_box": true,
        "condition_in": [
          "<string>"
        ],
        "condition_not_in": [
          "<string>"
        ],
        "first_party_seller": true,
        "handling_days_max": 123,
        "international": true,
        "max_item_price": 123,
        "merchant_id_in": [
          "<string>"
        ],
        "merchant_id_not_in": [
          "<string>"
        ],
        "min_seller_num_ratings": 123,
        "min_seller_percent_positive_feedback": 123,
        "prime": true,
        "allow_oos": true
      }
    }
  ],
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "address_line1": "<string>",
    "address_line2": "<string>",
    "zip_code": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "phone_number": "<string>",
    "instructions": "<string>"
  },
  "shipping_method": "<string>",
  "shipping": {
    "order_by": "<string>",
    "max_days": 123,
    "max_price": 123
  },
  "billing_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "address_line1": "<string>",
    "address_line2": "<string>",
    "zip_code": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "phone_number": "<string>",
    "instructions": "<string>"
  },
  "payment_method": {
    "name_on_card": "<string>",
    "number": "<string>",
    "security_code": "<string>",
    "expiration_month": 123,
    "expiration_year": 123,
    "use_gift": true
  },
  "retailer_credentials": {
    "email": "<string>",
    "password": "<string>",
    "totp_2fa_key": "<string>"
  },
  "addax": true,
  "is_gift": true,
  "gift_message": "<string>",
  "require_gift": true,
  "webhooks": {
    "request_succeeded": "<string>",
    "request_failed": "<string>",
    "tracking_obtained": "<string>",
    "tracking_updated": "<string>",
    "status_updated": "<string>",
    "case_updated": "<string>"
  },
  "client_notes": {},
  "promo_codes": [
    {
      "code": "<string>",
      "optional": true,
      "merchant_id": "<string>",
      "discount_amount": 123,
      "discount_percentage": 123,
      "cost_override": 123
    }
  ],
  "strict_expired_product_id": true,
  "po_number": 123,
  "amazon_day": "<string>",
  "fail_if_taxed": true,
  "max_delivery_days": 123,
  "take_buybox_offers": true,
  "force_offers_postal_code": "<string>",
  "zma_discount": 123,
  "addax_queue_timeout": 123,
  "zma_prime_optout": true,
  "zma_priority_bid": 123,
  "max_price": 123
}'
{
  "request_id": "<string>"
}
Zinc offers two ways to place orders depending on your business needs. Choose the approach that works best for you:
  • Self-Managed Account
  • Zinc Managed Accounts (ZMA)
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
  • 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

​
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.
Order Status Flow

Order status flow for a typical Zinc 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.
Offer selection flow chart

Flow chart for making an order

​
Default seller selection criteria

If a seller selection criteria object is not explicitly provided, then the API will use the default:
{ 
"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.

Authorizations

​
Authorization
string
header
required

Use your client token as the username. Leave the password blank.

Body

application/json
​
retailer
string
required

The retailer code of the supported retailer.

​
products
object[]
required

A list of product objects that should be ordered.

​
shipping_address
object
required

An address object to which the order will be delivered.

​
is_gift
boolean
required

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.

​
shipping_method
string

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), or free (which will fail for items without some sort of free shipping). You must provide either this or the shipping attribute, but not both.

​
shipping
object

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
object

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
object

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
object

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
boolean

Set to true to enable Zinc Managed Accounts (ZMA). When true, do not include retailer_credentials, payment_method, or billing_address fields.

​
gift_message
string

A message to include on the packing slip for the recipient. Max 240 characters or 9 lines.

​
require_gift
boolean

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.

​
webhooks
object

A webhooks object including URLs that will receive POST requests after particular events have finished. See Webhooks for more details.

​
client_notes
object

Any metadata to store on the request for future use. This object will be passed back in the response.

​
promo_codes
object[]

A list of promotion codes to use at checkout.

​
strict_expired_product_id
boolean

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
number

(Amazon business accounts only) Adds a purchase order number to the order.

​
amazon_day
string

(Amazon only) Specify exact name of Amazon Day shipping selection when ship_method is set to amazon_day.

​
fail_if_taxed
boolean

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
number

(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
boolean

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
string

Uses this postal code for offer selection instead of the shipping_address.zip_code value.

​
zma_discount
number

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
number

Defaults to 14400. Number of seconds an order will stay in the ZMA queue before timing out with zma_temporarily_overloaded.

​
zma_prime_optout
boolean

Defaults to false. Set this value to true to force your ZMA order to use a non-prime fulfillment account.

​
zma_priority_bid
number

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
integer

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

Response

200 - application/json

Order created successfully

​
request_id
string
⌘I