NAV
shell

Introduction

Zinc lets you buy things from popular online retailers, including Amazon.com, with a single POST request. Zinc also lets you get prices and descriptive information about products from supported retailers.

Quick start

  1. Make an account at dash.zinc.io.
  2. Follow the instructions in the create an order section from the documentation below to place your first order.

Supported retailers

The table below shows the endpoints available for each retailer. We can add additional retailers upon request – fill out the form at the bottom of our home page for a quote for a particular retailer.

Name Retailer Code Orders Product Details Product Prices
AliExpress aliexpress Y Y Y
Amazon† amazon Y Y Y
Amazon United Kingdom† amazon_uk Y Y Y
Amazon Canada† amazon_ca Y Y Y
Amazon Mexico† amazon_mx Y Y Y
Costco costco Y Y Y
Walmart walmart Y* Y Y

*Walmart AutoOrdering is currently in unsupported beta. Prime Pantry Items, Kindles, Alexa Products, and Digital items(eBooks and Digital movies) are not supported

Authentication

Example authentication request

curl https://api.zinc.io/v1/orders \
  -u <client_token>:

You can authenticate your account by including your client token in your request. Authentication is performed through HTTP Basic Auth, where the client token is the basic auth username value. You do not need to provide a password.

Make sure that you don’t share your client token and that you keep it away from publicly accessible areas such as Github, client-side code, etc. Client tokens are tied to your account, so you will be charged for any orders or requests made with your client token. If you believe your client token has been compromised, please contact [email protected] immediately.

Idempotency Keys

Example idempontency key request

curl "https://api.zinc.io/v1/orders" \
  -u <client_token>: \
  -d '{
  "idempotency_key": <idempotency_key>,
  "retailer": "amazon",
  "max_price": 2300,
  ...
  }'

The Zinc API does not provide out of the box deduplication of orders. Each time you send a new order request, the Zinc API will attempt to place a new order. However, the API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if an order request fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single order is created.

To perform an idempotent request, attach a unique key to request body of any POST request with the parameter "idempotency_key": <idempotency_key>. How you create unique keys is completely up to you. We suggest using random strings or UUIDs. We’ll always send back the same response for requests made with the same key. If you receive an error on a request, you can retry by sending another request with a different idempotency key. Once you receive an error or success response, the order will no longer change.

Idempotency keys are STRONGLY recommended. In the unlikely event that an API request returns a 5XX status code, duplicate requests could occur if you reattempt the request. We can’t be sure of the state of the request when we return a 5XX status code, so it’s best to attempt requests with an idempotency key. If you aren’t using an idempotency key and you retry orders with a 5XX error code, Zinc will not refund you for duplicate orders.

Orders

Create an order

Example create an order request

curl "https://api.zinc.io/v1/orders" \
  -u <client_token>: \
  -d '{
  "retailer": "amazon",
  "products": [
    {
      "product_id": "B0016NHH56",
      "quantity": 1
    }
  ],
  "max_price": 2300,
  "shipping_address": {
    "first_name": "Tim",
    "last_name": "Beaver",
    "address_line1": "77 Massachusetts Avenue",
    "address_line2": "",
    "zip_code": "02139",
    "city": "Cambridge",
    "state": "MA",
    "country": "US",
    "phone_number": "5551230101"
  },
  "is_gift": true,
  "gift_message": "Here is your package, Tim! Enjoy!",
  "shipping": {
    "order_by": "price",
    "max_days": 5,
    "max_price": 1000
  },
  "payment_method": {
    "name_on_card": "Ben Bitdiddle",
    "number": "5555555555554444",
    "security_code": "123",
    "expiration_month": 1,
    "expiration_year": 2020,
    "use_gift": false
  },
  "billing_address": {
    "first_name": "William",
    "last_name": "Rogers",
    "address_line1": "84 Massachusetts Ave",
    "address_line2": "",
    "zip_code": "02139",
    "city": "Cambridge",
    "state": "MA",
    "country": "US",
    "phone_number": "5551234567"
  },
  "retailer_credentials": {
    "email": "[email protected]",
    "password": "myRetailerPassword",
    "totp_2fa_key": "3DE4 3ERE 23WE WIKJ GRSQ VOBG CO3D METM 2NO2 OGUX Z7U4 DP2H UYMA"
  },
  "webhooks": {
    "order_placed": "http://mywebsite.com/zinc/order_placed",
    "order_failed": "http://mywebsite.com/zinc/order_failed",
    "tracking_obtained": "http://mywebsite.com/zinc/tracking_obtained"
  },
  "client_notes": {
    "our_internal_order_id": "abc123",
    "any_other_field": ["any value"]
  }
}'

Example create an order response

{
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc"
}

Zinc offers an API for apps that need real-time order placing capabilities. With a single POST request, you can order an item from one of our supported retailers. Making an order request will start an order. You’ll receive a request_id in the POST body’s response which you’ll then use for retrieving the status of the order.

Required attributes

Attribute Type Description
retailer String The retailer code of the supported retailer
products List A list of product objects that should be ordered
shipping_address Object An address object to which the order will be delivered
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), 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
payment_method Object A payment method object containing payment information for the order
retailer_credentials Object A retailer credentials object for logging into the retailer with a preexisting account

Optional attributes

Attribute Type Description
gift_message String A message to include on the packing slip for the recipient. Must be no more than 240 characters, or 9 lines.
is_gift Boolean 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.
max_price Number 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.
webhooks Object A webhooks object including URLs that will receive POST requests after particular events have finished
client_notes Object Any metadata to store on the request for future use. This object will be passed back in the response.
promo_codes Array A list of promotion codes to use at checkout.
ignore_invalid_promo_code Boolean Continue with checkout even if promotion codes are invalid. Default is false.
po_number Number (Amazon business accounts only). Adds a purchase order number to the order.
bundled Boolean (Amazon only). If enabled, orders will be grouped together into batches and placed together. See the order bundling section for more details.

Retrieving an order

Example retrieve an order request

curl "https://api.zinc.io/v1/orders/3f1c939065cf58e7b9f0aea70640dffc" \
  -u <client_token>:

To see the status of an order, append the ‘request_id’ returned from your order query to the order URL and place GET request. Orders usually take a while to process. While your order is processing, the response will return an error with code type request_processing.

Example retrieve an order response (request processing)

{
  "_type": "error",
  "code": "request_processing",
  "message": "Request is currently processing and will complete soon.",
  "data": {}
}

Example retrieve an order response (order response)

{
  "_type" : "order_response",
  "price_components" : {
    "shipping" : 0,
    "subtotal" : 1999,
    "tax" : 0,
    "total" : 1999
  },
  "merchant_order_ids" : [
    {
      "merchant_order_id" : "112-1234567-7272727",
      "merchant" : "amazon",
      "account" : "[email protected]",
      "placed_at" : "2014-07-02T23:51:08.366Z"
    }
  ],
  "tracking" : [
    {
      "product_id" : "0923568964",
      "merchant_order_id" : "112-1234567-7272727",
      "carrier" : "Fedex",
      "tracking_number" : "9261290100129790891234",
      "obtained_at" : "2014-07-03T23:22:48.165Z"
    }
  ],
  "request" : {
    ...
  }
}

Once the request process completes, the retrieve an order response should either return a response of type order_response, with the details of the successfully placed order or error. An error response body will contain a code and a message. The code indicates the error that occurred, while the message provides a more detailed description of the error. Any extra details about the error will be provided in the data object. For a full list of errors, see the Errors section.

Order response attributes

Attribute Type Description
price_components Object A price components object which contains details about the price of the final order
merchant_order_ids Array A merchant order ids object which contains details about the retailer’s order identifiers
tracking Array An array of tracking objects that contain the order’s tracking information. In most cases, this field will not be populated immediately after the order is placed and will only be available later after tracking is updated by the retailer. Once tracking has been obtained, a POST request will be sent to the tracking_obtained field of the webhooks object from the request if set.
request Object The original request that was sent to the Zinc API
delivery_dates Array An array of ordered products and their given delivery dates
account_status Array (Amazon only) An account status object that gives details about the ordering account

Selecting shipping

Zinc provides a number of options to customize your shipping speed and cost formulas from the various options available from our supported retailers.

Since different items will have different shipping options, you can use a product’s seller selection criteria to specify handling_days_max. This will filter the list of potential offers down to those that will ship within a certain number of days, which is useful when customers expect to see a tracking number within a certain amount of time. The Zinc API will then select the cheapest offer that matched all of your seller selection criteria to make a purchase. For example, if you specified "handling_days_max": 6, 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. (Note: when no handling information is available, we use the longest projected arrival date of the product as the handling_days_max)

You may also use the shipping parameter on an order to select a shipping option once a product has been selected. Instead of filtering by the different offers, like the seller selection criteria, the shipping parameter will choose the shipping speed on the selected offer. This is useful for ensuring the product will arrive by a specific day. For example, if you set "max_days": 5 on the shipping parameter, the Zinc API would attempt to select the cheapest shipping method that took less than 5 days to arrive. Thus, if there was a shipping method that took 3 days and cost $10 and another shipping method that took 7 days but cost $2, the first shipping option would be selected.

Order bundling

The bundling feature groups orders together before placing them. This is often advantageous on retailers where larger orders are given free shipping. To use bundling, you only need to specify bundled: true when placing an order request. Bundling currently only works on the following retailers: amazon, amazon_uk.

The bundling feature allows you to take advantage of free shipping over $50 (on Amazon) without having to change your Zinc integration. Bundling will take the shipping addresses, products, and quantities from separate orders and will group them together into a single order, making sure that each product is routed correctly. The order requests and responses remain exactly the same. The only difference is when the order is placed. The order bundling feature will wait for enough orders in the queue before launching a bundled order. The exact dynamics are as follows:

  1. The order bundler will wait until $55 in products have been purchased. As soon as more than $55 of products have been queued with bundled: true, the bundler will launch a new order.
  2. If the order bundler has waited for longer than 6 hours and has not yet obtained $55 in products, it will launch an order with whatever products are currently in the queue.

Note that the order bundler will not group together two orders which have the same product ids.

Amazon Email Verification

Amazon occasionally requires additional verification of account ownership by emailing you a code to enter during login. If this happens during an order, you will receive an account_locked_verification_required error. In this case, please check the email associated with the account and obtain the verification code. Then resubmit your order and supply the code as verification_code under the retailer_credentials object. Another option is to enable Two Factor Authentication on your account and supply the 'totp_2fa_key’ with every order, which will skip Amazon email verification, for more detail review the info on 'retailer_credentials’

Aborting an order

Example order abort request

curl "https://api.zinc.io/v1/orders/<request_id>/abort" \
  -X POST \
  -u <client_token>:

Example successful order abort response

{
  "_type": "error",
  "code": "aborted_request",
  "message": "The request was aborted before it completed.",
  "data": {
    "msg": "Order aborted and dequeued"
  },
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc",
  "request": {
    ...
  }
}

Example request processing order abort response

{
  "_type": "error",
  "code": "request_processing",
  "message": "Request is currently processing and will complete soon.",
  "data": {}
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc",
}

The Zinc API allows you to abort uncompleted orders that are still in the request_processing stage. This functionality allows you to stop an order from going through if a mistake was made on the order, or if the order is taking too long to process.

The response to this request will be a standard GET response for an order, which is either a request_processing response, an error response, or a successful order response. If we are able to successfully abort the order, an aborted_request error code will be returned for the order in question. If you receive back a request_processing response, you will need to continue to wait before the API is able to abort a request on an already running process.

If you are using the request_succeeded and request_failed webhooks, you won’t need to do anything with the order abort response. The API will hit the request_failed webhook if an order is aborted correctly, and will have normal behavior if the order abort fails.

Note that abortion is best effort, so we cannot guaranteed that you will be able to abort a request.

Adding and Amazon Affiliate Tag

Example Affiliate Tag Snippet

curl "https://api.zinc.io/v1/orders" \
  -u <client_token>: \
  -d '{
  "retailer": "amazon",
  "affiliate_info": {"tag": "yourtag-20"},
  ...
  }

The API allows you to add an Amazon Affiliate tag if you so desire. However, Zinc doesn’t recommend using the affiliate tag due to the high risk of your affiliate account being closed when a large number of orders are coming from a particular purchasing account.

Cancellations

Initiate a cancellation

Example cancellation

curl "https://api.zinc.io/v1/orders/<request_id>/cancel" \
  -X POST \
  -u <client_token>: \

Example advanced cancellation

curl "https://api.zinc.io/v1/orders/<request_id>/cancel" \
  -X POST \
  -u <client_token>: \
  -H 'Content-type: application/json' \
  -d '{
    "merchant_order_id": "112-1234567-7272727",
    "webhooks": {
      "request_succeeded": "https://www.example.com/webhooks/success",
      "request_failed": "https://www.example.com/webhooks/failed"
     }
   }'

Example cancellation response

{
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc"
}

The Zinc API supports pre-shipment order cancellation on Amazon.com and Amazon.co.uk. Simply POST to the cancellation endpoint. Note that cancelling an order occurs after an order has been successfully placed on the API. This is distinct from an order abort, which occurs while the order is still in progress. Cancellations will send a cancellation request to the retailer and attempt to stop the order from shipping and can only be initiated for order requests that were successful.

There aren’t any required parameters for a cancellation, so you can send an authenticated post to the cancellation URL "https://api.zinc.io/v1/orders/<request_id>/cancel" without any extra parameters. However, cancellations can only be performed for a single merchant order id. If your order response has multiple merchant order ids, then you need to pass the merchant_order_id parameter to the request.

Optional cancellation attributes

Attribute Type Description
merchant_order_id String The merchant order id of the order that you would like to cancel. If multiple merchant order ids exist for a particular order, this parameter is required, otherwise the cancellation request will fail
webhooks Object A webhooks object including URLs that will receive POST requests after particular events have finished

The request_succeeded and request_failed webhooks are optional. If supplied, they will be called when the corresponding event occurs on the cancellation request.

Retrieve a cancellation

Example cancellation retrieval request

curl "https://api.zinc.io/v1/cancellations/<request_id>" \
  -u <client_token>:

Example cancellation retrieval response

{
  "_type": "cancellation_response",
  "merchant_order_id": "112-1234567-7272727",
  "request": {
    ...
  }
}

To retrieve a cancellation response given a cancellation request id, simply make a GET request to the cancellation URL "https://api.zinc.io/v1/cancellations/<request_id>". You will receive either a request_processing response, an error response, or a successful cancellation response of type “cancellation_response”.

Cancellation response attributes

Attribute Type Description
merchant_order_id String The merchant order id of the order that was cancelled
request Object The original request that was sent to the Zinc API

Attempting to cancel

Example attempting_to_cancel cancellation response

{
  "_type": "error",
  "code": "attempting_to_cancel",
  "message": "The retailer is attempting to cancel the order.",
  "data": {
    "msg": "Attempting to cancel order",
  },
  "request": {
    ...
  }
}

In about 50% of cases, Amazon is unable to immediately cancel an order. Instead, they tell Zinc that they’re “Attempting to Cancel” the order. This currently results in the failure code attempting_to_cancel in the API. This status will be updated when the order is either cancelled successfully or if the cancellation fails. The Zinc API will continue to poll the retailer and attempt to figure out the status of the order, but no guarantees can be made for how long this will take. Once Zinc determines the actual status of the cancellation, the attempting_to_cancel error code will be removed and the updated response will take its place.

The request_failed webhook will be hit if the cancellation goes into the attempting_to_cancel state. If it moves out of this state and into an error state, the request_failed webhook will be hit again with the updated cancellation response. If the cancellation moves into a successful state, the request_succeeded webhook will be hit with the updated cancellation response. Thus if you are using the request_succeeded and request_failed webhooks, you won’t need to poll the cancellation request id to learn about changes from the attempting_to_cancel state.

Returns

Create a Return

Example return label request

curl "https://api.zinc.io/v1/orders/<request_id>/return" \
  -X POST \
  -u <client_token>: \
  -H 'Content-type: application/json' \
  -d '{
    "webhooks": {
      "request_succeeded": "https://www.exaple.com/webhooks/return/success",
      "request_failed": "https://www.exaple.com/webhooks/return/failed",
    },
    "products": [{"product_id": "B0000001234", "quantity": 1}],
    "reason_code": "inaccurate website description",
    "method_code": "UPS Dropoff",
    "explanation": "Additional details for Amazon seller",
    "cancel_pending": false
  }'

Example return label response

{
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc"
}

The Zinc API also supports generating return labels. Returns are only available on the following retailers: amazon, amazon_uk. You can create a return for an order by hitting the https://api.zinc.io/v1/orders/<request_id>/return route where request_id is the request id of the original order.

Required attributes

Attribute Type Description
products List A list of product objects that should be returned
reason_code String The reason for the return. This is passed directly to Amazon. Reason codes will vary depending on Amazon country. Many users have had success using “inaccurate website description” for Amazon.com and “description on website was not accurate” for Amazon.co.uk. Note that the reason_code must be an exact match with the reason code dropdown available on Amazon.
method_code String The method of returning the specified products. This is passed directly to Amazon. The available options may vary based on Amazon country and customer address. Note that UPS Dropoff is the only method supported for automatic refunds on Zinc Managed Account orders. If you’d like to use a different method, you’ll need to manually request a refund.
explanation String Any extra information that will be passed to Amazon or the Amazon seller. It is required for some return reasons.

Optional attributes

Attribute Type Description
webhooks Object A webhooks object including URLs that will receive POST requests after particular events have finished.
cancel_pending Boolean Whether or not this request should cancel any pending returns while creating a new return. If false, the request will return a return_in_progress error code if a pending return already exists. Defaults to false.
return_address Object An address object from which the return is sent. If not provided, the default return address from Amazon will be used.

Retrieving a return

Example return retrieval request

curl "https://api.zinc.io/v1/returns/<request_id>" \
  -u <client_token>:

Example return retrieval response

{
  "_type": "return_response",
  "merchant_return_id": "12345678-abcd-efgh-1234-abcde1234567",
  "return_by": "2018-02-01T00:00:00",
  "label_urls": [
    "https://zincapi.s3.amazonaws.com/3f1c939065cf58e7b9f0aea70640dffc_return_label.pdf"
  ],
  "request": {
    ...
  }
}

Example return_in_progress return retrieval response

{
  "_type": "error",
  "code": "return_in_progress",
  "message": "A return is currently in progress for the items you specified.",
  "data": {
    "status": {
      "status": "Refund issued",
      "description": "$6.30 refund issued on Nov 22, 2017."
    },
    "error": "Tried to cancel but could not find cancel button",
  },
  "request": {
    ...
  }
}

To retrieve a return response given a return request id, simply make a GET request to the return URL “https://api.zinc.io/v1/returns/”. You will receive either a request_processing response, an error response, or a successful cancellation response of type “return_response”.

Return response attributes

Attribute Type Description
merchant_return_id String A unique identifier for the return
return_by String The date before which the products must be returned by
label_urls Array A list of URLs for the generated return labels
request Object The original request that was sent to the Zinc API

You can use the return_in_progress error to check the status of your return. Just supply an invalid method_code like “Dummy Method Code”. If the return is in progress, you’ll get the status back with the error. If the return is not yet started, we’ll be unable to start a return because the method code does not exist.

Product details

Example product details request

curl https://api.zinc.io/v1/products/0923568964?retailer=amazon \
  -u <client_token>:

Get up to date information on the title, description, manufacturer details, item specifics, and more for any product on our supported retailers.

To retrieve product details, make a GET request to the following URL, replacing <product_id> with the retailer’s unique identifier for a particular product and specifying the request attributes as query parameters in the URL.

https://api.zinc.io/v1/products/<product_id>?retailer=<retailer_name>

Required request attributes

Attribute Type Description
retailer String The retailer for the product

Optional request attributes

Attribute Type Description
max_age Number A number in seconds setting the maximum age of the response. The data returned in the response will be at most this many seconds old. Cannot specify with newer_than.
newer_than Number A timestamp setting the minimum time the response should be retrieved from. The data returned in the response will be newer this timestamp. Cannot specify with max_age.
async Boolean Determines whether the resulting response will be asynchronous. If set to true, then the API will not block waiting for a result. Instead, it will immediately return status: "processing" and you will be responsible for resending the request until the response is no longer status: "processing". Defaults to false.

Example product details response

{
    "status": "completed",
    "original_retail_price": 899,
    "timestamp": 1515775557,
    "all_variants": [
        {
            "variant_specifics": [
                {
                    "dimension": "Size",
                    "value": "2"
                }
            ],
            "product_id": "B00Q3H18EQ"
        },
        {
            "variant_specifics": [
                {
                    "dimension": "Size",
                    "value": "1"
                }
            ],
            "product_id": "B00KFP6NHO"
        }
    ],
    "retailer": "amazon",
    "feature_bullets": [
        "Includes four freeze-and-feed popsicle molds with handles shaped perfectly for little hands",
        "Perfect for fresh homemade puree popsicles - turn fresh fruit/veggie puree or juice into 1 fl. oz popsicles",
        "Wide popsicle-holder base catches drips as the popsicle melts to reduce the risk of messes",
        "Great for teething babies to help soothe sore gums",
        "6 Months + / BPA Free"
    ],
    "variant_specifics": [
        {
            "dimension": "Size",
            "value": "1"
        }
    ],
    "main_image": "https://images-na.ssl-images-amazon.com/images/I/61K0YbuLi-L.jpg",
    "images": [
        "https://images-na.ssl-images-amazon.com/images/I/61K0YbuLi-L.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/81KtOn8ddTL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/71%2BruDKMSoL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/91AE6dpp5EL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/61FQEQJR2HL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/511agWyBf3L.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/31cC6K6y%2ByL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/31ocdUye0ML.jpg"
    ],
    "package_dimensions": {
        "weight": {
            "amount": 8.5,
            "unit": "ounces"
        },
        "size": {
            "width": {
                "amount": 4,
                "unit": "inches"
            },
            "depth": {
                "amount": 5.8,
                "unit": "inches"
            },
            "length": {
                "amount": 5.8,
                "unit": "inches"
            }
        }
    },
    "epids": [
        {
            "type": "MPN",
            "value": "5438"
        },
        {
            "type": "UPC",
            "value": "048526054381"
        },
        {
            "type": "EAN",
            "value": "0048526054381"
        }
    ],
    "product_id": "B00KFP6NHO",
    "asin": "B00KFP6NHO",
    "ship_price": 0,
    "categories": [
        "Home & Kitchen",
        "Kitchen & Dining",
        "Kitchen Utensils & Gadgets",
        "Specialty Tools & Gadgets",
        "Ice Pop Molds"
    ],
    "review_count": 829,
    "epids_map": {
        "MPN": "5438",
        "UPC": "048526054381",
        "EAN": "0048526054381"
    },
    "title": "Nuby Garden Fresh Fruitsicle Frozen Pop Tray",
    "brand": "Nuby",
    "product_description": "Size:1  Nuby's Garden Fresh Fruitsicle Frozen Popsicle Tray\nis specially designed for making fresh puree popsicles at home. Nuby’s\nFruitsicles are the perfect size for baby’s small hands and are designed to\ncatch drips as the pop melts. Fruitsicles are perfect for teething babies with\nsore gums. This set includes four fruitsicle handles and a tray to mold the\npops while keeping them in place while in your freezer. To use: fill\ncompartments with fresh puree, breast milk, or juice. Snap handles into mold\nand freeze until solid. BPA Free. By Nuby",
    "product_details": [
        "Product Dimensions: 5.8 x 5.8 x 4 inches ; 7.8 ounces",
        "Shipping Weight: 8.5 ounces",
        "Domestic Shipping: Item can be shipped within U.S.",
        "UPC: 048526054381 013513034066",
        "Item model number: 5438"
    ],
    "question_count": 26,
    "stars": 4.5,
    "price": 799
}

Response attributes

Attribute Type Description
status String Possible values are processing, failed, or completed. You will only see processing if async: true was set on the request
retailer String The retailer for the product
product_id String The retailer’s unique identifier for the product
timestamp String The timestamp that the resource was accessed
title String Title of the product
product_details Array An array of strings providing details about the product
feature_bullets String An array of strings providing highlights of the product
brand String The brand of the product (if available)
main_image String The URL of the primary image associated with the product
images Array An array of image URLs associated with the product
variant_specifics Array Array of objects containing information about the types and values of a particular product variant. A variant specifics object contains a dimension field describing the type of the variant (e.g. “Color”) and a value field describing the specific value available. At the top level, this contains information on the selected variant
all_variants Array An array of variant_specifics objects detailing all variants of the product as well as their product IDs
categories Array Array of different categories that the product belongs in
authors Array Array of author names (only available for products that are books)
product_description String The description of the product
epids Array Array of objects containing external product identifier (epid) objects. An epid object contains a type field describing the name of the external product identifier and a value field for the identifier’s value
epids_map Array An array of the epids with the epid type as the the field and the epid value as the value
package_dimensions Array An array detailing the packaging details if available. Each dimension contains a ‘amount’ and 'unit’
item_location String (AliExpress only) The originating location of the product
original_retail_price Number (Amazon only) The “List Price” in cents of the product (present if the retailer is presenting a crossed out list price)
price Number (Amazon only) The price in cents of the buy box price of the item
review_count Number (Amazon only) The number of reviews of the product
stars Double (Amazon only) The review score of the product
question_count Number (Amazon only) The number of questions on the Amazon question section
asin String (Amazon only) The ASIN of the product
item_number String (Costco only) The Costco item number of the product (may not contain variant details)

Product prices

Example product offers request

curl https://api.zinc.io/v1/products/0923568964/offers?retailer=amazon \
  -u <client_token>:

Get information about all the offers for a particular product, including seller name, item price, shipping price, condition, seller reputation, and more.

To retrieve product offers and prices, make a GET request to the following URL, replacing :product_id with the retailer’s unique identifier for a particular product and specifying the request attributes as query parameters in the URL.

https://api.zinc.io/v1/products/:product_id/offers

Required request attributes

Attribute Type Description
retailer String The retailer for the product

Optional request attributes

Attribute Type Description
max_age Number A number in seconds setting the maximum age of the response. The data returned in the response will be at most this many seconds old. Cannot specify with newer_than.
newer_than Number A timestamp setting the minimum time the response should be retrieved from. The data returned in the response will be newer this timestamp. Cannot specify with max_age.
async Boolean Determines whether the resulting response will be asynchronous. If set to true, then the API will not block waiting for a result. Instead, it will immediately return status: "processing" and you will be responsible for resending the request until the response is no longer status: "processing". Defaults to false.

Example product offers response

{
  "retailer": "amazon",
  "status": "completed",
  "offers":[
    {
      "addon": false,
      "condition": "New",
      "handling_days_max": 0,
      "handling_days_min": 0,
      "international": false,
      "merchant_id": "ATVPDKIKX0DER",
      "offerlisting_id": "lUai8vEbhC%2F2vYZDwaePlc4baWiHzAy9XJncUR%2FpQ9l4VOrs%2FfpYt4ZtreQaB%2BPL1xJwz5OpIc%2BJjyymHg3iv4YkZvWy5z7flil7n7lUDWNPY76YUhMNdw%3D%3D",
      "price": 9.79,
      "ship_price": 0
      "prime": true,
      "prime_only": false,
      "seller_name": "Amazon.com",
      "seller_num_ratings": 1000000,
      "seller_percent_positive": 100
    }
  ]
}

Response attributes

Attribute Type Description
status String Possible values are processing, failed, or completed. You will only see processing if async: true was set on the request.
retailer String The retailer for the product offers
offers Array An array of product offer objects for a particular product on a retailer

Zinc Managed Accounts

Overview

Zinc Managed Accounts allow customers to place orders without worrying about creating and managing their own Amazon accounts. Instead, users of a Managed Account can fund a balance with Zinc using PayPal or wire transfer, which Zinc will then debit to place orders on your behalf.

Managed accounts are currently available for Amazon and Amazon UK.

Zinc Managed Accounts are currently available by invite only. Please contact [email protected] and mention Managed Accounts. You can also contact this address if you need more information to determine if Managed Accounts are right for you.

Funding your account

Check account balance and view past transactions

curl "https://api.zinc.io/v1/addax/balance" -u <client_token>:
curl "https://api.zinc.io/v1/addax/transactions?count=100&offset=0" -u <client_token>:

Please contact [email protected] They’ll help set up funding options taylored for your needs. Generally, funding is performed either through PayPal’s Mass Pay option or via wire transfer directly to our bank.

You’ll need to fund your account before you’ll be able to place orders.

You can check your account balance and transactions at any time.

Note: these funds are used to pay for the cost of your order on Amazon, but you’ll still be billed the normal ordering fee at the end of the month. Your Zinc sales contact can provide more information about billing.

Create an order

Follow the standard documentation for creating orders with two changes:

  1. Add "addax": true to your request body.
  2. Do not supply the retailer_credentials, payment_method, or billing_address keys.

All other ordering features and options work as specified in the standard documentation.

Successful orders will result in a transaction decreasing your account balance for the currency of the market. Failed orders will not cost you anything.

Refunds

In some cases, a Managed Account order might initially succeed (and thus charge your account) but later need to be reversed. For example, your buyer might want to return the product, or the order may be cancelled by the Amazon seller.

To address these cases, we’ve created a refund process. All refunds will be sent to Zinc, which we will approve or decline. Any declined refunds may be appealed to [email protected]

When there’s a successful cancellation (see above) or a return created through the Zinc API is delivered back to Amazon, we’ll automatically start the refund process for your account. In other cases, you’ll need to request a refund manually.

Checking refund status

Make a GET request to the refund endpoint.

Check refund status

curl "https://api.zinc.io/v1/orders/<order_id>/refund" \
  -u <client_token>:

refund_state will be one of the following values:

Value Description
(null) No refund has been requested.
requested A refund has been requested. Zinc has 30 days to respond.
refunded A refund has been issued to your account.
declined Zinc has declined the refund request. Please contact [email protected] if you need more information.

Requesting a refund manually

Make a POST request to the refund endpoint.

Create refund

curl "https://api.zinc.io/v1/orders/<order_id>/refund" \
  -X POST \
  -u <client_token>: \
  -H 'Content-type: application/json' \
  -d '{"reason": "refund_reason_code", "note": "Please include as much detail as possible in the note."}'

Valid reason codes include:

Code Description
attempting_to_cancel You attempted to cancel the order, but are unsure if it completed. Zinc will refund if possible and decline if the order actually went through.
return_completed The item was returned, but not using a label that was generated by Zinc.
other Please contact [email protected] and explain why you need to use this code.

If none of these reason codes cover your use case, please contact [email protected] and use the code: other.

Object reference

Product object

Example product object

{
  "product_id": "B06XGHJ5H3",
  "quantity": 1,
  "seller_selection_criteria": {
    "prime": true,
    "handling_days_max": 6,
    "condition_in": ["New"],
  }
}
Attribute Type Description
product_id String The retailer’s unique identifier for the product. Note that Zinc does not support digital purchases or Amazon prime pantry items.
quantity Number The number of products to purchase.
seller_selection_criteria Object A seller selection criteria object containing information about which offers to choose when there are multiple offers available. If the seller selection criteria object is not included for a product, the seller selection criteria will default to "prime": true, "handling_days_max": 6, and "condition_in": ["New"].

Seller selection criteria object

Example seller selection criteria object

{
  "addon": false,
  "condition_in": ["New"],
  "handling_days_max": 6,
  "max_item_price": 5350
  "min_seller_num_ratings": 100,
  "prime": true,
}

Seller selection criteria allow you to filter multiple offers for a product from a retailer. They give you fine grained control when a retailer has multiple offers for a single product. This happens frequently when third party or affiliated merchants are selling on a platform, such as o Amazon.

The seller selection criteria serve as a series of optional filters to narrow down the potential set of offers to something reasonable. After all the filters have been applied, Zinc will select the cheapest offer that is still available. For example, if "handling_days_max": 6 is applied, then the Zinc API will order the cheapest offer where the shipping will arrive in 6 days or less.

Attribute Type Description
addon Boolean (Amazon only) Specifies whether the selected offer should be an addon item
buy_box Boolean (Amazon only) Specifies whether the selected offer should be Amazon’s default buy box offer
condition_in Array An array of item conditions that the Zinc API must order from
condition_not_in Array An array of item conditions that the Zinc API must not order from
first_party_seller Boolean Is the seller first-party? e.g. sold by Walmart.com on walmart
handling_days_max Number The maximum number of allowable days for shipping and handling
international Boolean Specifies whether the item should come from an international supplier
max_item_price Number The maximum allowable price in cents for an item
merchant_id_in Array (Amazon only) An array of merchant ids that the Zinc API must order from
merchant_id_not_in Array (Amazon only) An array of merchant ids that the Zinc API must not order from
min_seller_num_ratings Number (Amazon only) The minimum number of ratings required for an Amazon seller’s offer to be selected
min_seller_percent_positive_feedback Number (Amazon only) The minimum percentage of positive ratings of an Amazon seller for their offer to be selected
prime Boolean (Amazon only) Specifies whether the selected offer should be an Amazon Prime offer

Shipping object

Example shipping object

{
  "order_by": "price",
  "max_days": 5,
  "max_price": 1000
}

The shipping object gives you fine grained control over shipping speeds on your orders. Typically, there is a tradeoff between how fast your order arrives and the cost of shipping. The shipping object gives you a way to make sure that you don’t go over budget and that your order still arrives on time.

Attribute Type Description
order_by String 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 Number The maximum number of days allowed for shipping on the order.
max_price Number The maximum price in cents allowed for the shipping cost of the order.

Address object

Example address object

{
  "first_name": "Tim",
  "last_name": "Beaver",
  "address_line1": "77 Massachusetts Avenue",
  "address_line2": "",
  "zip_code": "02139",
  "city": "Cambridge",
  "state": "MA",
  "country": "US",
  "phone_number": "5551230101"
}
Attribute Type Description
first_name String The first name of the addressee
last_name String The last name of the addressee
address_line1 String The house number and street name
address_line2 String The suite, post office box, or apartment number (optional)
zip_code String The zip code of the address
city String The city of the address
state String The USPS abbreviation for the state of the address (e.g. AK)
country String 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.
phone_number String The phone number associated with the address

Payment method object

Example payment object

{
  "name_on_card": "Ben Bitdiddle",
  "number": "5555555555554444",
  "security_code": "123",
  "expiration_month": 1,
  "expiration_year": 2015,
  "use_gift": false
}

The recommended way to pay for purchases on a retailer is by using gift card balance already applied to an account. Gift cards are supported on amazon, amazon_uk, amazon_ca, and walmart. To use the existing gift balance on the account, simply pass {"use_gift": true} as the payment method object.

To use a credit card, you must include the name_on_card, number, security_code, expiration_month, and expiration_year fields. For Amazon, you should only have a single credit card associated with an account which should be the same as the card passed in the payment method object. This allows the system to correctly answer any payment-related security questions.

Attribute Type Description
name_on_card String The full name on the credit/debit card
number String The credit/debit card number
security_code String The card verification value on the back of the credit/debit card
expiration_month Number The month of the expiration of the card (e.g. January is 1, February is 2)
expiration_year Number The year of the expiration of the card (e.g. 2016)
use_gift Boolean Whether or not to use the gift balance on the retailer account. If true, then the gift balance will be used for payment. Only works for retailers which support gift balance (Amazon and Walmart).

Webhooks object

Webhooks let you register a URL that the Zinc API notifies whenever an event happens pertaining to your account. When an event occurs, we will send a POST request to the URL specified in the webhooks object. If no URL was specified, then a webhook will not be sent. The body of the POST request is the standard raw JSON response for that object.

As an example, let’s say you have just created an order via the Zinc API. Every time the order status changes, a POST request will be sent to the URL that you passed in the status_updated parameter of the webhooks object. The body will mimic the response received from the standard GET https://api.zinc.io/v1/orders/<request_id> request. A webhook will also be sent if order fails, gets placed, or if tracking gets updated.

Example webhooks object

{
  "request_succeeded": "http://mywebsite.com/zinc/request_placed",
  "request_failed": "http://mywebsite.com/zinc/request_failed",
  "tracking_obtained": "http://mywebsite.com/zinc/tracking_obtained",
  "status_updated": "http://mywebsite.com/zinc/status_updated"
}
Attribute Type Description
request_succeeded String The webhook URL to send data to when a request succeeds
request_failed String The webhook URL to send data to when a request fails
tracking_obtained String The webhook URL to send data to when tracking for an order is retrieved
status_updated String The webhook URL to send data to when the status of a request is updated

Retailer credentials object

Example retailer credentials object

{
  "email": "[email protected]",
  "password": "myRetailerPassword"
}
Attribute Type Description
email String The email for the retailer account
password String The password for the retailer account
verification_code String (Optional) The verification code required by the retailer for logging in. Only required in cases where the retailer prevents a login with an account_locked_verification_required error code.
totp_2fa_key String (Optional) The secret key used for two factor authentication. If you have two factor authentication enabled, you must provide this key. You can find the 64 digit Amazon key by enabling two factor authentication and clicking on the “Can’t scan the barcode?” link. Note this is not the 6 digit time based code.

Price components object

Example price components object

{
  "shipping" : 0,
  "subtotal" : 1999,
  "tax" : 0,
  "total" : 1999
}
Attribute Type Description
shipping Number The price for shipping
product_subtotals Array A list of the price for each product_id in the order
subtotal Number The total price of the order before tax and other price adjustments
tax Number The tax collected on the order
total Number The total price paid for the order
gift_certificate Number (Optional) The amount of value used on a gift certificate placed on the account

Merchant order ids object

Example merchant order ids object

{
  "merchant_order_id" : "112-1234567-7272727",
  "merchant" : "amazon",
  "account" : "[email protected]",
  "placed_at" : "2018-01-02T23:51:08.366Z",
  "tracking_url": "https://www.amazon.com/progress-tracker/package/ref=oh_aui_hz_st_btn?_encoding=UTF8&itemId=jnlnooqppopuun&orderId=112-1234567-7272727",
  "delivery_date": "Jan. 7, 2018"
}
Attribute Type Description
merchant_order_id String The identifier provided by the retailer for the order that was placed
merchant String The retailer on which the order was placed
account String The account on which the order was placed
placed_at Date The date and time at which the order was placed
tracking Array A list of the tracking numbers associated with the order
product_ids Array A list of product_ids in the order
tracking_url String The tracking url provided by the merchant (if available)
delivery_date String The projected delivery date given by the retailer

Account status object

Example account status object

{
  "prime": true,
  "fresh": false,
  "business": false,
  "charity": null
}
Attribute Type Description
prime boolean Indicates if the account has Prime enabled
fresh boolean Indicates if the account has Fresh enabled
business boolean Indicates if the account has Business enabled
charity string Indicates if the account has a Charity associated

Product offer object

Example product offer object

{
  "addon": false,
  "condition": "New",
  "handling_days_max": 0,
  "handling_days_min": 0,
  "international": false,
  "merchant_id": "ATVPDKIKX0DER",
  "offerlisting_id": "lUai8vEbhC%2F2vYZDwaePlc4baWiHzAy9XJncUR%2FpQ9l4VOrs%2FfpYt4ZtreQaB%2BPL1xJwz5OpIc%2BJjyymHg3iv4YkZvWy5z7flil7n7lUDWNPY76YUhMNdw%3D%3D",
  "price": 9.79,
  "ship_price": 0
  "prime": true,
  "prime_only": false,
  "seller_name": "Amazon.com",
  "seller_num_ratings": 1000000,
  "seller_percent_positive": 100
}
Attribute Type Description
addon Boolean Whether or not the product is an addon item that can only be purchased in a bundle
condition String The condition of the product. Possible values are New, Refurbished, Used - Like New, Used - Very Good, Used - Good, Used - Acceptable, Unacceptable.
greytext String (Amazon only) The shipping text provided by the seller
handling_days_max Number The maximum number of days required for shipping and handling
handling_days_min Number The minimum number of days required for shipping and handling
international Boolean Whether or not the product ships from outside of the United States
member_only Boolean (Costco only) Whether or not the purchase must be from a Costco Member
merchant_id String The merchant’s unique identifier for the product
offerlisting_id String (Amazon only). The unique identifier that identifies an item sold by any merchant on Amazon
price Number The price of the item, not including shipping
ship_price Number The price of the shipping for the item
prime Boolean (Amazon only). Whether or not the product ships using Amazon Prime
prime_only Boolean (Amazon only). Whether or not the product only ships using Amazon Prime
seller_name String The name of the seller of the current offer
seller_num_ratings Number The number of ratings that the seller has accumulated
seller_percent_positive Number Number between 0 and 100 denoting the percentage of positive ratings the seller has received

Tracking object

Example tracking object

{
  "merchant_order_id": "112-1234567-7272727",
  "carrier": "UPS",
  "tracking_number": "1Z9999999999999999",
  "tracking_url": "https://some-url.com/tracking-number/1Z9999999999999999",
  "product_id": "0923568964"
}
Attribute Type Description
merchant_order_id String The corresponding order identifier for which tracking was obtained.
carrier String (Optional) The logistics carrier that was used to ship the package.
tracking_number String (Optional) The tracking number from the logistics carrier.
tracking_url String (Optional) The tracking url that can be used to find the carrier and tracking number for a package.
product_id String (Optional) The corresponding product for which tracking was obtained.

Errors

Example error response

{
  "_type": "error",
  "code": "product_unavailable",
  "message": "One of the products you selected is unavailable.",
  "data": {'product_id': '018293801'}
}

If there is an error processing a request, the result endpoint will return an error object containing three fields: code, message, and data.

The code field provides a short, unique error code describing the error situation. The message field provides a human readable message describing the error and is intended for the developer and not the end user. The data field contains specific information related to the error (for example, the maximum quantity allowed and the desired quantity would be shown for a max_quantity_exceeded error).

The Zinc API uses the following errors:

Error Code Meaning
account_locked The retailer asked for additional information to verify your account.
account_locked_verification_required The retailer emailed you a code which you must supply to continue ordering.
account_login_failed We were unable to log in to the retailer with the username and password you provided.
add_on_item Add-on items cannot be ordered individually.
additional_information_required The retailer asked for additional account verification questions. If using the API, please add a field ‘phone_number’ in the billing address that matches your billing telephone number.
billing_address_refused The billing address you provided was refused by the retailer.
brand_not_accepted Your credit card brand is not accepted with this merchant.
credit_card_declined The credit card you entered was declined.
duplicate_order This order is a duplicate.
expired_product_id The product_id you used is no longer supported by the retailer.
incomplete_account_setup You attempted to place an order with an account that has not been fully set up.
insufficient_addax_balance Insufficient funds in your Managed Account Balance to complete the order. Add more funds through your payment channel.
insufficient_variants You did not select all required variants for a product.
internal_error Zinc or the retailer you requested is experiencing outages. Please try again or contact [email protected] if this error persists.
invalid_card_number The credit card number you entered is not valid.
invalid_client_token Your client token is invalid.
invalid_expiration_date The expiration date on your credit card is not valid.
invalid_gift_options The gift options you provided were rejected by the retailer.
invalid_json The JSON in your request could not be parsed.
invalid_login_credentials The email and password you entered were incorrect.
invalid_payment_method The payment method provided is not available on the retailer.
invalid_promo_code One of the promotion codes you entered was not valid.
invalid_quantity The quantity for one of the products does not match the one available on the retailer.
invalid_request Validation failed on the request.
invalid_request_id The provided request_id is invalid.
invalid_security_code The security code you entered was declined.
invalid_shipping_method The shipping method you selected was not valid.
invalid_variant One of the product variants you provided was not valid.
manual_review_required This order is under manual review by Zinc – please check back later for the status of this order.
max_price_exceeded The retailers final price exceeds the maximum price.
max_quantity_exceeded You have exceeded the maximum quantity available for a specific product.
no_free_shipping Free shipping is not available for the item(s) you selected.
no_gift_shipping No gift shipping was available on this order.
no_two_day_shipping Two day shipping (or faster) is not available for the item(s) you selected.
order_probably_placed This order was probably placed, but we were not able to retrieve the merchant order ids.
payment_info_problem There was a problem with your payment information (likely not enough gift balance).
prime_pantry_not_supported Purchasing Prime Pantry items is not supported by the Zinc API.
product_unavailable One of the products you selected is not available on the retailer. Either the seller selection criteria did not match any available offers or the product is out of stock and not available for purchase.
request_processing Request is currently processing and will complete soon.
shipping_address_refused The shipping address you provided was refused by the retailer.
shipping_address_unavailable The item(s) cannot be shipped to the selected shipping address.
shipping_method_unavailable The selected shipping_method is not available for the selected shipping_address.
unauthorized_access You are not authorized to make this API call. Please contact [email protected] (Usually, attempting to use Addax before it has been enabled)