Introduction

The Zinc API 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.

The Zinc API is organized around REST. Our API has predictable, resource-oriented URLs.

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.

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.

Supported retailers

The table below shows the endpoints available for each retailer.

Note that this is a partial list. We support hundreds more retailers in beta. For details, please email [email protected].

*Currently in beta. †Prime Pantry Items, Kindles, Alexa Products, and Digital items(eBooks and Digital movies) are not supported

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": {
    "request_succeeded": "http://example.com/zinc/request_succeeded",
    "request_failed": "http://example.com/zinc/requrest_failed",
    "tracking_obtained": "http://example.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. The following illustration shows the flow for a typical order.

Required attributes

Optional attributes for all orders

Optional attributes for ZMA orders

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" : {
    "converted_payment_total": 1999,
    "currency": "USD",
    "payment_currency": "USD",
    "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

Retrieving a list of orders

Example query for all Amazon orders (up to 5000) for June 1, 2019 14:00 - July 1, 2019 14:00

curl "https://api.zinc.io/v1/orders?limit=5000&starting_after=1559397600000&ending_before=1561989600000&retailer=amazon" \
  -u <client_token>:

To get a list of all orders within a specific timestamp range, use the order query and include these additional query parameters.

Order query parameters

The timestamps are unix timestamps in milliseconds, which you can read about here unix timestamps. To easily convert a human-readable date / time to a unix timestamp, you can use this converter.

Sample code that includes an example of a bulk order query can be found in this github repo.

Selecting an offer & shipping

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 an 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: { "prime": true, "handling_days_max": 6, "condition_in": ["New"] }

Some examples

• 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.
• 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. (Note: when no handling information is available, we use the longest projected arrival date of the product as the handling_days_max)
• 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.

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 abort response that is still pending

{
  "_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 orders that are still in the request_processing stage. This functionality is intended to abort an order if was made by mistake or if it is taking too long to process.

The response will be the same as if you were to GET the order. If we were able to immediately abort the order, the order will have an error code of aborted_request. It can take time for an order to abort and success is not guaranteed. You can either periodically poll the order to check if it was aborted or use webhooks.

Amazon email verification

Occasionally, Amazon requires verification of account ownership and will email you a code during login. If this happens during an order, you will receive an account_locked_verification_required error. There are a few options for resolving this issue.

• 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.
• Enable Two Factor Authentication on your account and supply the totp_2fa_key with every order under the retailer_credentials object.
• Use Zinc Managed Accounts where we manage keeping accounts open and unlocked.
• Forward all emails from your Amazon account's email to [email protected]. AutoOrdering will automatically parse the incoming email and fill in the code. For instructions on how to forward from a Gmail account, see this article.

Retrying an order

Sometimes an order will fail for reasons that are temporary. In these situations, orders can be retried after the temporary conditions are resolved. A successful order retry response contains the request_id of the new order.

Example order retry request

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

Example successful order retry response

{
  "request_id": "3f1c939065cf58e7b9f0aea70640dffc"
}

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, https://api.zinc.io/v1/orders/<request_id>/cancel. Note that cancelling an order occurs after an order has been successfully placed on the API. This is distinct from aborting an order, 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.

Required attributes

Optional cancellation attributes

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

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 POSTING to the https://api.zinc.io/v1/orders/<request_id>/return route where request_id is the request id of the original order.

Required attributes

Optional attributes

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

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 Data

Zinc can get product details, product offers and search supported retailers. In general, these calls are tuned for throughput rather than latency. If you need responses quickly, we have realtime versions of each call. Also, proper use of the optional max_age or newer_than query parameters will improve response times.

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

Optional request attributes

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": 44,
    "stars": 4.4,
    "fresh": false,
    "pantry": false,
    "handmade": false,
    "digital": false,
    "buyapi_hint": true,
    "price": 799
}

Response attributes

Product Offers

Example product offers request

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

Example product offers response

{
  "status": "completed",
  "asin": "B007JR5304",
  "offers": [
    {
      "seller": {
        "num_ratings": null,
        "percent_positive": null,
        "first_party": false,
        "name": "Amazon Warehouse",
        "id": "A2L77EE7U53NWQ"
      },
      "marketplace_fulfilled": true,
      "international": false,
      "offer_id": "eMLzuculxk",
      "available": true,
      "handling_days": {
        "max": 0,
        "min": 0
      },
      "price": 928,
      "prime_only": false,
      "condition": "Used - Very Good",
      "addon": false,
      "shipping_options": [
        {
          "price": 0,
          "delivery_days": {
            "max": 4,
            "min": 4
          },
          "name": "one-day"
        }
      ],
      "minimum_quantity": null,
    }
  ],
  "timestamp": 1543523165,
  "retailer": "amazon"
}

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

Optional request attributes

Response attributes

Product Search

Example product search request

curl 'https://api.zinc.io/v1/search?query=fish%20oil&page=1&retailer=amazon' \
  -u <client_token>:

Get search results from a retailer based on a query term. Results include product id, title, image url, number of reviews, star rating, and price.

To retrieve search results, make a GET request to the following URL, replacing :query with a url-encoded query string and specifying the request attributes as query parameters in the URL.

https://api.zinc.io/v1/search?query=:query&page=1&retailer=:retailer

Required request attributes

Example product offers response

{
  "status": "completed",
  "timestamp": 1522268852,
  "retailer": "amazon",
  "results": [
    {
      "product_id": "B000NPYY04",
      "title": "Nature's Bounty Fish Oil, 1200 mg Omega-3, 200 Rapid Release Softgels, Dietary Supplement for Supporting Cardiovascular Health(1)",
      "image": "https://images-na.ssl-images-amazon.com/images/I/51KGjV22PWL._AC_US218_.jpg",
      "num_reviews": 395,
      "stars": "4.5 out of 5 stars",
      "fresh": false,
      "price": 1248
    },
    {
      "product_id": "B004U3Y9FU",
      "title": "Nature Made Burpless Fish Oil 1000 mg w. Omega-3 300 mg Softgels 150 Ct",
      "image": "https://images-na.ssl-images-amazon.com/images/I/516F1UWawAL._AC_US218_.jpg",
      "num_reviews": 0,
      "stars": "4.4 out of 5 stars",
      "fresh": false,
      "price": 1299
    },
    {
      "product_id": "B002VLZHLS",
      "title": "Kirkland Signature Fish Oil Concentrate with Omega-3 Fatty Acids, 400 Softgels, 1000mg",
      "image": "https://images-na.ssl-images-amazon.com/images/I/41bpqnspd1L._AC_US218_.jpg",
      "num_reviews": 0,
      "stars": "4.6 out of 5 stars",
      "fresh": false,
      "price": 1642
    }
  ]
}

Response attributes

Realtime Product Data

The calls documented above are tuned for throughput rather than latency, and for most use cases they work well. There are some use cases (for example, catalog expansion) that have strict latency requirements. To satisfy those use cases we have developed a realtime version of our data APIs. To ensure we meet our latency guarantees, we limit access to the realtime api. To get access to our realtime API, contact [email protected].

Realtime Search

Example realtime search request

curl'https://api.zinc.io/v1/realtime/search?query=vitamin&retailer=amazon' \
-u <client_token>:

Example realtime search response

{
  "status": "completed",
  "timestamp": 1537653337,
  "nextPage": "https://api.zinc.io/v1/realtime/search?nextToken=eyJzZWVuIjpbMjY4NDM1NDU2LDAsMTA0ODU3NiwwLDAsNDIxMDY4OCwwLDAsMTYzODQsMCwwLDAsMTMxMDcyLDAsMjU2LDAsMzI3NjgsMjU2LDAsNDA5NiwxMDQ4NTc2LDAsMCwyMzA0LDQsMjA2MDgsMjY4NDM1NDU2LDAsMCwwLC0yMTQ3NDgzNjQ4LDAsMCwwLDY3MTE3MDU2LDAsMTMxMDcyLDUzNjg3MDkxMiwwLDAsMCwyNTYsMCw1MTIwLDAsNTI0MjkyLDAsMzI3NjgsNjU1MzYsMCwxNiwwLDIwODAsMCwwLDAsMCw2NTUzNiwwLDEwNTYsMCwxMDI0LDAsMCwxNjc3NzIxNiwwLDAsMCwwLDI2ODQzNTQ1Niw1NzYsODE5Miw2NCwxMDczNzQxODI0LDEwNDg1NzYsMCwwLDQsMCwxMDQ4NTc2LDI3MiwwLDI4NTIxMjY3MiwwLDAsMCwwLDAsMCwwLDAsMTY3NzcyMTYsMCwwLC0yMTQ3NDgyNjI0LDI2NDE5MiwwLDAsMCw0MDk2LDAsMCw1MTIsMCwwLDAsMCwwLDIzMDQsMjYyMTQ0LDAsMCwyNjg0MzU0NTYsMCwxLDAsMCw2NTUzNywwLDUyOCwwLDAsMCwtMjE0NzQ2NzI2NCwwLDE2Mzg0LDAsMF0sInBhZ2UiOjIsImNvdW50cnkiOiJ1cyIsInF1ZXJ5Ijoidml0YW1pbiJ9",
  "nextToken": "eyJzZWVuIjpbMjY4NDM1NDU2LDAsMTA0ODU3NiwwLDAsNDIxMDY4OCwwLDAsMTYzODQsMCwwLDAsMTMxMDcyLDAsMjU2LDAsMzI3NjgsMjU2LDAsNDA5NiwxMDQ4NTc2LDAsMCwyMzA0LDQsMjA2MDgsMjY4NDM1NDU2LDAsMCwwLC0yMTQ3NDgzNjQ4LDAsMCwwLDY3MTE3MDU2LDAsMTMxMDcyLDUzNjg3MDkxMiwwLDAsMCwyNTYsMCw1MTIwLDAsNTI0MjkyLDAsMzI3NjgsNjU1MzYsMCwxNiwwLDIwODAsMCwwLDAsMCw2NTUzNiwwLDEwNTYsMCwxMDI0LDAsMCwxNjc3NzIxNiwwLDAsMCwwLDI2ODQzNTQ1Niw1NzYsODE5Miw2NCwxMDczNzQxODI0LDEwNDg1NzYsMCwwLDQsMCwxMDQ4NTc2LDI3MiwwLDI4NTIxMjY3MiwwLDAsMCwwLDAsMCwwLDAsMTY3NzcyMTYsMCwwLC0yMTQ3NDgyNjI0LDI2NDE5MiwwLDAsMCw0MDk2LDAsMCw1MTIsMCwwLDAsMCwwLDIzMDQsMjYyMTQ0LDAsMCwyNjg0MzU0NTYsMCwxLDAsMCw2NTUzNywwLDUyOCwwLDAsMCwtMjE0NzQ2NzI2NCwwLDE2Mzg0LDAsMF0sInBhZ2UiOjIsImNvdW50cnkiOiJ1cyIsInF1ZXJ5Ijoidml0YW1pbiJ9",
  "retailer": "amazon",
  "results": [
    {
      "product_id": "B00K2RJAR0",
      "title": "OPTIMUM NUTRITION Opti-Men, Mens Daily Multivitamin Supplement with Vitamins C, D, E, B12, 150 Count",
      "price": 2278,
      "image": "https://images-na.ssl-images-amazon.com/images/I/41raAjeCEwL._AC_US218_.jpg",
      "brand": "Optimum Nutrition",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B007L0DPE0",
      "title": "Vitafusion Women's Gummy Vitamins, 150 Count (Packaging May Vary)",
      "price": 979,
      "image": "https://images-na.ssl-images-amazon.com/images/I/51eGHGb0zqL._AC_US218_.jpg",
      "brand": "Vitafusion",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B002H0KZ9M",
      "title": "Vitafusion Multi-vite, Gummy Vitamins For Adults, 150 Count (Packaging May Vary)",
      "price": 979,
      "image": "https://images-na.ssl-images-amazon.com/images/I/515YezxBrlL._AC_US218_.jpg",
      "brand": "Vitafusion",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B003G4BP5G",
      "title": "Centrum Adult (200 Count) Multivitamin / Multimineral Supplement Tablet, Vitamin D3",
      "price": 949,
      "image": "https://images-na.ssl-images-amazon.com/images/I/41IpifEYOpL._AC_US218_.jpg",
      "brand": "Centrum",
      "prime": false,
      "product_details": []
    },
    {
      "product_id": "B00GB85JR4",
      "title": "NatureWise Vitamin D3 5,000 IU for Healthy Muscle Function, Bone Health and Immune Support, Non-GMO in Cold-Pressed Organic Olive Oil,Gluten-Free, 1-year supply, 360 count",
      "price": 1105,
      "image": "https://images-na.ssl-images-amazon.com/images/I/61X2dIACG9L._AC_US218_.jpg",
      "brand": "NatureWise",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B00WR6JGD2",
      "title": "Dr. Tobias Multivitamin for Women and for Men - Enhanced Bioavailability - With Whole Food & Herbal Ingredients, Minerals and Enzymes - Rich in Vitamin B & C - Womens And Mens Daily Vitamins - Non-GMO",
      "price": 2277,
      "image": "https://images-na.ssl-images-amazon.com/images/I/61GaW6R4iuL._AC_US218_.jpg",
      "brand": "Dr. Tobias",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B007L0DONW",
      "title": "Vitafusion Men's Gummy Vitamins, 150 Count (Packaging May Vary)",
      "price": 1174,
      "image": "https://images-na.ssl-images-amazon.com/images/I/519q4FPn5eL._AC_US218_.jpg",
      "brand": "Vitafusion",
      "prime": false,
      "product_details": []
    },
    {
      "product_id": "B071ZH84QG",
      "title": "Centrum Men (250 Count) Multivitamin / Multimineral Supplement Tablet, Vitamin D3",
      "price": 1977,
      "image": "https://images-na.ssl-images-amazon.com/images/I/51MR+UHdh8L._AC_US218_.jpg",
      "brand": "Centrum",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B0771X1HTZ",
      "title": "One A Day Men's Health Formula Multivitamin, 250 Count",
      "price": 1424,
      "image": "https://images-na.ssl-images-amazon.com/images/I/41-X+7wZ1DL._AC_US218_.jpg",
      "brand": "ONE A DAY",
      "prime": true,
      "product_details": []
    },
    {
      "product_id": "B01KE592JU",
      "title": "Men's Daily Multimineral/Multivitamin Supplement - Vitamins A C E D B1 B2 B3 B5 B6 B12. Magnesium, Biotin, Spirulina, Zinc. Antioxidant For Heart & Immune Health. 60 Daily Gluten Free Multivitamins.",
      "price": 1897,
      "image": "https://images-na.ssl-images-amazon.com/images/I/51T72DkubeL._AC_US218_.jpg",
      "brand": "Vimerson Health",
      "prime": true,
      "product_details": []
    }
  ]
}

Expand your product catalog with realtime results from Amazon based on a query term. Results include product id, title, image url, and price.

To retrieve search results, make a GET request to the following URL, replacing <query> with a url-encoded query string and specifying the request attributes as query parameters in the URL.

https://api.zinc.io/v1/realtime/search?query=<query>&retailer=<retailer_name>&nextToken=<token>

The first page should always return within 4 seconds and will contain 10 results. If you want to show more than 10 results, you should use AJAX to load additional pages for the best user experience. A demo of this can be found at http://amazonsearchdemo.surge.sh/ (source code). Note that you must contact [email protected] first so we can enable this feature for you.

Required request attributes

Optional request attributes

Response attributes

Realtime Details

Example realtime details request

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

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.

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

Using the realtime details call is identical to our normal details call with the exception that max_age is ignored.

If a realtime details call hits our cache, the call does not count against your real-time rate limit.

Realtime Offers

Example realtime offers request

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

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.

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

Usage and returned data is identical to our normal offers call.

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.com only.

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.

ZMA orders go into a queue until a fulfillment account that meets the requirements of the order is available. If an order is queued for too long without an account becoming available, the order will fail with a zma_temporarily_overloaded error. The default queue timeout value is 4 hours (14400 seconds). To change this value, add "addax_queue_timeout": 14400 to your order, replacing the 14400 with your preferred timeout. Note: decreasing the timeout will not improve your chances of getting your order placed. If you timeout after one hour and then resubmit the order, it will go to the end of the queue.

Cases

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.

Cases are automatically opened by Zinc when an order is cancelled, a return is requested, and for other scenarios. You can also open a Case to ask for assistance with a failed return, cancellation, and other issues. Cases are regularly updated by Zinc with information about the status of the case.

Checking the status of a Case

Make a GET request to the case endpoint

Check Case status

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

state will be one of the following values:

messages contains the entire history of a case, and can have any of these values for type:

The most up to date case status is represented by the latest object in the messages list.

Opening a Case

Make a POST request to the case endpoint

Create a new Case

curl "https://api.zinc.io/v1/orders/<order_id>/case" \
  -X POST \
  -u <client_token>: \
  -H 'Content-type: application/json' \
  -d '{"reason": "return.request_label", "message": "I need a return label"}'

To open a case you must use one of the following values for reason:

Updating a Case

You can append a freetext message to a Case by POSTing a message without a reason:

Update a Case

curl "https://api.zinc.io/v1/orders/<order_id>/case" \
  -X POST \
  -u <client_token>: \
  -H 'Content-type: application/json' \
  -d '{"message": "I have an update on this case"}'

Proxies

The Zinc API interfaces with the retailers via proxies. This enables each retailer interaction session to use unique and consistent IP addressing. Due to many factors, sometimes the bulk proxies available to us become blocked by retailers. The best path to keeping your own account from being blocked is to provide your own proxy service, by either hosting your own proxy or purchasing a proxy from a provider. We call this "bring-your-own-proxy" (BYOP).

Where do I get a proxy?

We cannot recommend any specific proxy provider. Many commerical providers are unsuitable because their IPs are low quality and shared among many users. It is best to use a real residential IP address dedicated to your ordering flow.

One option is to deploy the Zinc proxy container, on Github at zinc/zn-proxy.

Configure ZincAPI for your own proxy (BYOP)

To configure a BYOP, you must provide the retailer, email account, and full proxy connection URL.

The proxy_url components are as follows:

Example BYOP configuration

curl "https://api.zinc.io/v1/proxies/byop" \
  -X PUT \
  -u <client_token>: \
  -d '{"retailer":"amazon","email":"[email protected]","proxy_url":"http://proxy_user:[email protected]:1234"}'

Query ZincAPI for current BYOP details

You can also query the Zinc API for the current BYOP configuration of a specific retailer account. If the account is configured for BYOP, the full proxy information will be returned in the JSON response. If the account is configured for one of our internal proxies, the response will be successful (200) with an empty JSON body.

Example query of existing BYOP configuration

curl "https://api.zinc.io/v1/proxies/byop" \
  -X GET \
  -u <client_token>: \
  -d '{"retailer":"amazon","email":"[email protected]"}'

Disable BYOP

Use the DELETE method instead of PUT.

Object reference

Product object

Example product object

{
  "product_id": "B06XGHJ5H3",
  "quantity": 1,
  "seller_selection_criteria": {
    "prime": true,
    "handling_days_max": 6,
    "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.

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.

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",
  "instructions": "Place packages inside blue garage door."
}

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.

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.

Note that the case_updated webhook is specifically for ZMA order cases.

Example webhooks object

{
  "request_succeeded": "https://example.com/zinc/request_placed",
  "request_failed": "https://example.com/zinc/request_failed",
  "tracking_obtained": "https://example.com/zinc/tracking_obtained",
  "tracking_updated": "https://example.com/zinc/tracking_updated",
  "status_updated": "https://example.com/zinc/status_updated",
  "case_updated": "https://example.com/zinc/case_updated"
}

You can optionally pass an Array of webhooks instead of a String, and Zinc will hit all of the webhooks.

Note that webhooks have "at least once" delivery semantics and may be called more than one time each. If you need to do something only once on an event (for example, sending an "order completed" email in response to request_succeeded, you should deduplicate in your own application.

Webhooks are not signed, but it is possible to increase webhook security by including a secret query parameter or HTTP basic auth credentials in the webhook, like the following:

https://zincapi:[email protected]/zinc/tracking_obtained

Additionally, for maximum security, you can discard the body of the webhook and instead use it as a trigger to re-fetch the body from the normal /v1/orders/:order_id API endpoint.

Retailer credentials object

Example retailer credentials object

{
  "email": "[email protected]",
  "password": "myRetailerPassword"
}

Promo code object

Example promo code object

{
  "code": "FIVEBUCKSOFF",
  "optional": false,
  "merchant_id": "A3GH440E2AFGH4",
  "discount_amount": 500
}

Price components object

Example price components object

{
  "converted_payment_total": 1999,
  "currency": "USD",
  "payment_currency": "USD",
  "shipping" : 0,
  "subtotal" : 1999,
  "tax" : 0,
  "total" : 1999
}

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"
}

Account status object

Example account status object

{
  "prime": true,
  "fresh": false,
  "business": false,
  "charity": null
}

Product offer object

Example product offer object

{
  "seller": {
    "num_ratings": null,
    "percent_positive": null,
    "first_party": false,
    "name": "Amazon Warehouse",
    "id": "A2L77EE7U53NWQ"
  },
  "marketplace_fulfilled": true,
  "international": false,
  "offer_id": "eMLzuculxk%2",
  "available": true,
  "handling_days": {
    "max": 0,
    "min": 0
  },
  "price": 928,
  "prime_only": false,
  "condition": "Used - Very Good",
  "addon": false,
  "shipping_options": [
    {
      "price": 0,
      "delivery_days": {
        "max": 4,
        "min": 4
      },
      "name": "one-day"
    }
  ],
}

Tracking object

Example tracking object

    {
      "merchant_order_id": "112-111111-6553065",
      "carrier": "ZNLOGIC",
      "tracking_number": "ZPYAA0051111007YQ",
      "delivery_status": "InTransit",
      "product_ids": [
        "B000R31KH2"
      ],
      "tracking_url": "https://t.17track.net/en#nums=ZPYAA0051111007YQ",
      "retailer_tracking_number": "TBA111189418000",
      "retailer_tracking_url": "https://www.amazon.com/progress-tracker/package/ref=oh_aui_hz_st_btn?_encoding=UTF8&itemId=khlnkqmn1111n&orderId=112-111111-6553065",
      "obtained_at": "2018-11-29T20:53:05.924Z"
    }

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:

Frequently Asked Questions

If we wish to place a large quantity of orders, is it best to place a large number of orders with one product per order or a smaller number of orders with multiple products in each?

• Either will work but there are tradeoffs. Orders with a single product will produce better error messages when something goes wrong and will not cause other items to not be ordered when individual items fail. Larger quantities in a single order will process faster as there is a cap on the number of orders that can be placed in a short time frame, and will be more likely to have free shipping, depending on the retailer.

Will placing many orders in short succession cause the retailer to lock our account?

• No. Our system throttles the requests for individual accounts so we should not trigger lockouts from retailers.

What products can I buy with the Automatic Ordering API?

• The API supports most products, but there are some notable exceptions: digital products (such as e-books), gift cards, Prime Pantry, Amazon Fresh items, and speciality Amazon products (such as the Echo and Kindle) are not supported. Also, products that require local pickup, scheduled delivery, age verification, or any other extra specialty step during checkout will fail.

I submitted a lot of orders at once, why are they processing slower?

• They are not, they are just queued on our end. For each Amazon account, orders are placed one by one, since you can't have more than one shopping cart at a time. For example, each Amazon order takes about 2 minutes to process, so if you submit 10 orders at the same time for the same Amazon account, the last order will take about 20 minutes to process. If you need orders placed faster, consider using multiple retailer accounts.

I received an internal_error response from the Automatic Ordering API. How do I handle this?

• Internal errors are caused by either an outage on the retailer's side (e.g. Amazon or Walmart are having issues) or a temporary Zinc problem. Internal errors are safe to retry -- we recommend using exponential backoff to place another order if you receive an internal error.

My item has variants, how do I ensure I order the correct item with Zinc?

• Each Amazon ASIN corresponds to a single variant. Please use our free Google Chrome extension YakPal to look up variants for any product page on Amazon. Simply pass the ASIN to Zinc under product_id.

How can I disable using a max_price?

• You can set max_price to an arbitrarily high number, such as 10000000, to avoid getting a max_price_exceeded error.

I am receiving an Amazon security code text asking me to verify my identity when placing the order.

• This is common when placing orders on a new account for the first time, since we are accessing Amazon from a new IP address. See our documentation about Amazon email verification.

My payment methods are saved in my Amazon account. Can I just pass Zinc the last 4 digits of my credit card during checkout?

• You need to provide us the the full card because Amazon asks to verify it when shipping to new addresses. Alternative, you can select gift cards as your payment method (and you can use Piranha to both purchase gift cards as well as automatically load them onto your Amazon accounts).

When will my tracking number post?

• Our algorithm checks at various times based on our knowledge of when tracking becomes available. We post this response via webhook.

What is the structure of the POST body sent to the webhooks?

• All webhook POST bodies are identical to the Order Response object outlined here.

Can I authenticate Zinc webhooks?

• Yes, use basic auth in the webhook URL as detailed by RFC 1738: “https://:@some.server.com/webhookpath” where and are the basic auth username and password respectively.

I am not receiving POSTs to the my webhook URLs.

• Make sure that your server is configured to accept POST requests from any other server. To debug this, we recommend creating a requestbin URL, passing that in as your webhook, and looking at what the data that we returns looks like. This will also confirm to you that our webhooks are working properly.

Why am I getting multiple POSTs to my “order_placed” or other webhook?

• We will retry POSTing the webhook until you return a 200 status code, so make sure you are returning a 200 at your webhook endpoint.

Do you have any sample code for using the API?

• Sample code that includes an example of a bulk order query can be found in this github repo.

Blank Offers Page

Recently, Amazon has begun to return an empty page instead of a list of product offers. This appears to be an anti-bot response by Amazon, caused by the IP addresses used to place orders.

This appears to primarily affect the UK, DE, and IN regions. US, CA, and FR currently appear unaffected.

When this happens, our ordering agent will respond with the error amazon_antibot_blank_offers_page.

This is done because we cannot guarantee full ordering safeguards without accessing this offers page.

There are two workarounds that can be attempted:

1. Set take_buybox_offers to true on the top level of the ordering object. This will automatically accept the first offer on the Amazon product page, without applying any seller_selection_criteria. For safety, it is suggested to set max_price and max_delivery_days as well. Because this accepts the default offer, it will not require loading the broken page.

2. Bring your own proxy with BYOP. Ideally, you should use a real residential IP that is dedicated to your ordering flow. For more details, review the BYOP docs.

We will continue to monitor the situation and update this page as new details emerge.