The Products Array

The Zinc API allows you to order multiple products in a single request and specify quantities for each item.

Products Array

The products array in your order request accepts multiple OrderProduct objects. Each product is processed as part of the same order.

All products in an order must be from the same retailer. You cannot mix products from different retailers in a single order request.

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826"
    },
    {
      "url": "https://www.amazon.com/dp/B09V3KXJPB"
    }
  ],
  "shipping_address": { ... },
  "max_price": 5000
}

Setting Quantities

Each product can include a quantity field to specify how many units to order. What will be accepted by the retailer depends on the product and availability. We will return an error code, product_quantity_unavailable if we are unable to purchase the amount specified.

Range: 1 to 100
Default: 1 (if omitted)

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "quantity": 3
    }
  ],
  "shipping_address": { ... },
  "max_price": 3000
}

Combining with Variants

When ordering products with variants (size, color, etc.), you can combine the variant array with quantity:

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "quantity": 2,
      "variant": [
        {
          "label": "Color",
          "value": "Black"
        },
        {
          "label": "Size",
          "value": "Large"
        }
      ]
    }
  ],
  "shipping_address": { ... },
  "max_price": 4000
}

Condition Filtering

Each product can constrain which offers are eligible by item condition using condition_in (an allowlist) and condition_not_in (a denylist). The agent only buys an offer whose condition passes both lists. Both fields take an array of canonical condition values:

Value	Meaning
`New`	Brand new
`Refurbished`	Manufacturer or seller refurbished
`UsedLikeNew`	Used — like new
`UsedVeryGood`	Used — very good
`UsedGood`	Used — good
`UsedAcceptable`	Used — acceptable

Matching is exact and case-sensitive against these values. Omit a field, or send null / [], for no constraint.

Buy only new items:

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "condition_in": ["New"]
    }
  ],
  "shipping_address": { ... },
  "max_price": 3000
}

Accept used items, but nothing below “good”:

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "condition_in": ["New", "Refurbished", "UsedLikeNew", "UsedVeryGood", "UsedGood"]
    }
  ],
  "shipping_address": { ... },
  "max_price": 3000
}

Allow anything except acceptable-grade used items:

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "condition_not_in": ["UsedAcceptable"]
    }
  ],
  "shipping_address": { ... },
  "max_price": 3000
}

Complete Example

Here’s an example ordering multiple products with different quantities and variants:

{
  "products": [
    {
      "url": "https://www.amazon.com/dp/B07JGBW826",
      "quantity": 2,
      "variant": [
        {
          "label": "Color",
          "value": "Navy"
        }
      ]
    },
    {
      "url": "https://www.amazon.com/dp/B09V3KXJPB",
      "quantity": 1
    },
    {
      "url": "https://www.amazon.com/dp/B08N5WRWNW",
      "quantity": 3,
      "variant": [
        {
          "label": "Size",
          "value": "Medium"
        }
      ]
    }
  ],
  "shipping_address": {
    "first_name": "John",
    "last_name": "Smith",
    "address_line1": "123 Main Street",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US",
    "phone_number": "206-555-0100"
  },
  "max_price": 15000
}

Max Price Considerations

The max_price field applies to the total order amount across all products and quantities combined.

If the total order cost (including all products, quantities, taxes, and shipping) exceeds max_price, the order will fail with an error. Set your max_price high enough to account for the full order total.

When calculating max_price, consider:

Unit price × quantity for each product
Applicable taxes
Shipping costs
Any additional fees

Getting Started

Search (Beta)

Orders

Bulk Orders

Managed Accounts

Returns

Product Data

Retailers

Agent

Usage

The Products Array

Products Array

Setting Quantities

Combining with Variants

Condition Filtering

Complete Example

Max Price Considerations

​Products Array

​Setting Quantities

​Combining with Variants

​Condition Filtering

​Complete Example

​Max Price Considerations

Products Array

Setting Quantities

Combining with Variants

Condition Filtering

Complete Example

Max Price Considerations