{
  "openapi": "3.0.0",
  "info": {
    "title": "Zinc API",
    "version": "1.0.0",
    "description": "API for placing orders and retrieving product data from top retailers."
  },
  "servers": [
    {
      "url": "https://api.zinc.io",
      "description": "Production server"
    }
  ],
  "security": [{ "basicAuth": [] }],
  "paths": {
    "/v1/orders": {
      "get": {
        "summary": "List Orders",
        "description": "Retrieve a list of orders within a specific timestamp range.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            },
            "description": "Maximum number of orders to return in the results (defaults to 10)"
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Number of order responses to skip before including up to limit orders in results"
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Timestamp of start of the range (inclusive)"
          },
          {
            "name": "ending_before",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Timestamp of end of the range (exclusive)"
          },
          {
            "name": "retailer",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Name of the retailer to include orders from. See [Supported Retailers](/v1/supported-retailers) for a list of supported retailers."
          }
        ],
        "responses": {
          "200": {
            "description": "List of orders retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OrderResponse"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Order",
        "description": "Place a new order with Zinc.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrderResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{request_id}": {
      "get": {
        "summary": "Retrieve Order",
        "description": "Retrieve details of a specific order by request ID.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the order request"
          }
        ],
        "responses": {
          "200": {
            "description": "Order details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Request is currently processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcessingError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{request_id}/retry": {
      "post": {
        "summary": "Retry Order",
        "description": "Retry a failed order after temporary conditions are resolved.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the order request to retry"
          }
        ],
        "responses": {
          "200": {
            "description": "Order retry initiated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetryOrderResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{request_id}/abort": {
      "post": {
        "summary": "Abort Order",
        "description": "Abort an order that is still in the request_processing stage. This functionality is intended to abort an order if it was made by mistake or if it is taking too long to process.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the order request to abort"
          }
        ],
        "responses": {
          "200": {
            "description": "Order abort response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AbortOrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Error response when order cannot be aborted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcessingError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{request_id}/cancel": {
      "post": {
        "summary": "Initiate Cancellation",
        "description": "Initiate a pre-shipment order cancellation on Amazon.com and Amazon.co.uk. This occurs after an order has been successfully placed and is distinct from aborting an order.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the order request to cancel"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancellationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancellation initiated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/cancellations/{request_id}": {
      "get": {
        "summary": "Retrieve Cancellation",
        "description": "Retrieve a cancellation response given a cancellation request id.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the cancellation request"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancellation details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Request is currently processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcessingError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{request_id}/return": {
      "post": {
        "summary": "Create Return",
        "description": "Create a return label for an order. Returns are only available on amazon and amazon_uk retailers.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The request id of the original order"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReturnRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateReturnResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/returns/{request_id}": {
      "get": {
        "summary": "Retrieve Return",
        "description": "Retrieve a return response given a return request id.",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The unique identifier for the return request"
          }
        ],
        "responses": {
          "200": {
            "description": "Return details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReturnDetailsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Return is currently in progress or other error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReturnErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/{product_id}": {
      "get": {
        "summary": "Get Product Details",
        "description": "Get up to date information on the title, description, manufacturer details, item specifics, and more for any product on our supported retailers.",
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The retailer's unique identifier for a particular product"
          },
          {
            "name": "retailer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The retailer for the product. See [Supported Retailers](/v1/supported-retailers) for a list of supported retailers."
          },
          {
            "name": "max_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "A number in seconds setting the maximum age of the response. Cannot specify with `newer_than`."
          },
          {
            "name": "newer_than",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "A timestamp setting the minimum time the response should be retrieved from. Cannot specify with `max_age`."
          },
          {
            "name": "async",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Determines whether the resulting response will be asynchronous. Defaults to false."
          }
        ],
        "responses": {
          "200": {
            "description": "Product details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductDetailsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Product Search",
        "description": "Search for products across supported retailers.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The search query"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "The page number for pagination"
          },
          {
            "name": "retailer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The retailer for the product. See [Supported Retailers](/v1/supported-retailers) for a list of supported retailers."
          }
        ],
        "responses": {
          "200": {
            "description": "Search results retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/{product_id}/offers": {
      "get": {
        "summary": "Product Offers",
        "description": "Retrieve offers for a specific product.",
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The retailer's unique identifier for a particular product"
          },
          {
            "name": "retailer",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The retailer for the product. See [Supported Retailers](/v1/supported-retailers) for a list of supported retailers."
          },
          {
            "name": "max_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "A number in seconds setting the maximum age of the response. Cannot specify with `newer_than`."
          },
          {
            "name": "newer_than",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            },
            "description": "A timestamp setting the minimum time the response should be retrieved from. Cannot specify with `max_age`."
          },
          {
            "name": "async",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Determines whether the resulting response will be asynchronous. Defaults to false."
          }
        ],
        "responses": {
          "200": {
            "description": "Product offers retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductOffersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{order_id}/case": {
      "get": {
        "summary": "Retrieve Case",
        "description": "Get the status and history of a case for a Managed Account order",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The order ID to retrieve case information for"
          }
        ],
        "responses": {
          "200": {
            "description": "Case information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaseResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create or Update Case",
        "description": "Open a new case or add a message to an existing case for a Managed Account order",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The order ID to create or update a case for"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Case created or updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CaseResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateOrderRequest": {
        "type": "object",
        "required": [
          "retailer",
          "products",
          "shipping_address",
          "is_gift"
        ],
        "properties": {
          "retailer": {
            "type": "string",
            "description": "The retailer code of the [supported retailer](/v1/supported-retailers)."
          },
          "products": {
            "type": "array",
            "description": "A list of product objects that should be ordered.",
            "items": {
              "type": "object",
              "properties": {
                "product_id": {
                  "type": "string",
                  "description": "The unique identifier for the product at the retailer."
                },
                "quantity": {
                  "type": "integer",
                  "description": "The number of units to order."
                },
                "seller_selection_criteria": {
                  "$ref": "#/components/schemas/SellerSelectionCriteria",
                  "description": "A seller selection criteria object containing information about which offers to choose when there are multiple offers available."
                }
              },
              "required": ["product_id", "quantity"]
            }
          },
          "shipping_address": {
            "$ref": "#/components/schemas/Address",
            "description": "An address object to which the order will be delivered."
          },
          "shipping_method": {
            "type": "string",
            "description": "The desired shipping method for the object. Available methods are `cheapest` (always select the cheapest method available), `fastest` (always select the fastest method available), `amazon_day` (choose default from Amazon or use `amazon_day` attribute from order), `free` (which will fail for items without some sort of free shipping), or `no_rush` (Amazon only - selects the slowest/cheapest No-Rush shipping option). You must provide either this or the `shipping` attribute, but not both."
          },
          "shipping": {
            "$ref": "#/components/schemas/Shipping",
            "description": "A shipping object with information as to which shipping method to use. You must provide either this or the `shipping_method` attribute, but not both."
          },
          "billing_address": {
            "$ref": "#/components/schemas/Address",
            "description": "An address object for the person associated with the credit card. Required for self-managed accounts. Do not include when using ZMA (`addax: true`)."
          },
          "payment_method": {
            "$ref": "#/components/schemas/PaymentMethod",
            "description": "A payment method object containing payment information for the order. Required for self-managed accounts. Do not include when using ZMA (`addax: true`)."
          },
          "retailer_credentials": {
            "$ref": "#/components/schemas/RetailerCredentials",
            "description": "A retailer credentials object for logging into the retailer with a preexisting account. Required for self-managed accounts. Do not include when using ZMA (`addax: true`)."
          },
          "addax": {
            "type": "boolean",
            "description": "Set to true to enable Zinc Managed Accounts (ZMA). When true, do not include `retailer_credentials`, `payment_method`, or `billing_address` fields."
          },
          "is_gift": {
            "type": "boolean",
            "description": "Whether or not this order should be placed as a gift. Typically, retailers will exclude the price of the items on the receipt if this is set."
          },
          "gift_message": {
            "type": "string",
            "description": "A message to include on the packing slip for the recipient. Max 240 characters or 9 lines."
          },
          "require_gift": {
            "type": "boolean",
            "description": "If `is_gift` is true, setting `require_gift` to true will cause the order to fail if any items in the order do not include a gift option."
          },
          "use_gift_wrap": {
            "type": "boolean",
            "description": "(Amazon only) If true, enables gift wrapping for the order. Requires `is_gift` to also be true."
          },
          "webhooks": {
            "$ref": "#/components/schemas/WebhooksObject"
          },
          "client_notes": {
            "type": "object",
            "description": "Any metadata to store on the request for future use. This object will be passed back in the response."
          },
          "promo_codes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PromoCode" },
            "description": "A list of promotion codes to use at checkout."
          },
          "strict_expired_product_id": {
            "type": "boolean",
            "description": "Defaults to false. If `true`, fail orders where the `product_id` is `expired` or `deprecated`. If unset or `false`, Amazon redirects to a valid `product_id` and buys that one."
          },
          "po_number": {
            "type": "number",
            "description": "(Amazon business accounts only) Adds a purchase order number to the order."
          },
          "amazon_day": {
            "type": "string",
            "description": "(Amazon only) Specify exact name of Amazon Day shipping selection when ship_method is set to amazon_day."
          },
          "fail_if_taxed": {
            "type": "boolean",
            "description": "Defaults to `false`. If `true`, fail orders where taxes are included in the total. Useful for ZMA orders which should not be placed if no tax exempt account is available."
          },
          "max_delivery_days": {
            "type": "number",
            "description": "(Amazon only) Defaults to unlimited. If set, fail orders with error `max_delivery_days_exceeded` if the retailer estimates delivery more than this many days in the future."
          },
          "take_buybox_offers": {
            "type": "boolean",
            "description": "Bypass the process of looking at all offers - takes whatever the default offer is on the item details page buy box."
          },
          "force_offers_postal_code": {
            "type": "string",
            "description": "Uses this postal code for offer selection instead of the `shipping_address.zip_code` value."
          },
          "zma_discount": {
            "type": "number",
            "description": "The percent below (or above, if negative) face value that you will be charged for this order. Can range from `-50` to `0`. Lower discount orders will be processed before higher discount orders. If discount is too high and we are unable to secure ordering at that discount, the order will time out with  `zma_temporarily_overloaded`. Defaults to `0`."
          },
          "addax_queue_timeout": {
            "type": "number",
            "description": "Defaults to `14400`. Number of seconds an order will stay in the ZMA queue before timing out with `zma_temporarily_overloaded`."
          },
          "zma_prime_optout": {
            "type": "boolean",
            "description": "Defaults to `false`. Set this value to `true` to force your ZMA order to use a non-prime fulfillment account."
          },
          "zma_priority_bid": {
            "type": "number",
            "description": "A fixed-value bid used to prioritize ZMA orders. Successful orders will include the bid value in their ZMA cost. A value of `100` equals a bid of $1.00. Orders with higher bids get a higher priority."
          },
          "max_price": {
            "type": "integer",
            "description": "The maximum price in cents for the order. If the final price exceeds this number, the order will not go through and will return a `max_price_exceeded` error. Required for ZMA orders (`addax: true`)."
          },
          "customs_id_number": {
            "type": "string",
            "description": "ID number required for customs clearance on international shipments. Required when shipping to certain countries. If needed but not provided, the order will fail with a `customs_id_number_required` error."
          },
          "tax_exemption_opt_out": {
            "type": "boolean",
            "description": "If true, opts out of tax exemption and requests that tax be charged on the order. Useful for accounts that have tax exemption enabled but need to be charged tax for a specific order."
          },
          "disable_weekend_shipping": {
            "type": "boolean",
            "description": "(Amazon only) If true, disables Saturday and Sunday delivery options. The order will only be scheduled for weekday delivery."
          }
        }
      },
      "CreateOrderResponse": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" }
        }
      },
      "RetryOrderResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The unique identifier for the new order request"
          }
        }
      },
      "AbortOrderResponse": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["error"]
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "enum": ["aborted_request", "request_processing"]
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "data": {
            "type": "object",
            "description": "Additional error data"
          },
          "request_id": {
            "type": "string",
            "description": "The unique identifier for the order request"
          },
          "request": {
            "type": "object",
            "description": "The original request that was sent to the Zinc API"
          }
        }
      },
      "CancellationRequest": {
        "type": "object",
        "required": ["merchant_order_id"],
        "properties": {
          "merchant_order_id": {
            "type": "string",
            "description": "The merchant order id of the order that you would like to cancel. If the order has multiple merchant_order_ids you must cancel each separately."
          },
          "webhooks": {
            "$ref": "#/components/schemas/WebhooksObject",
            "description": "A webhooks object including URLs that will receive POST requests after `request_succeeded` and `request_failed`"
          }
        }
      },
      "CancellationResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The unique identifier for the cancellation request"
          }
        }
      },
      "CancellationDetailsResponse": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["cancellation_response"]
          },
          "merchant_order_id": {
            "type": "string",
            "description": "The merchant order id of the order that was cancelled"
          },
          "request": {
            "type": "object",
            "description": "The original request that was sent to the Zinc API"
          }
        }
      },
      "OrderResponse": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["order_response"]
          },
          "price_components": {
            "$ref": "#/components/schemas/PriceComponents"
          },
          "merchant_order_ids": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MerchantOrderId"
            },
            "description": "A merchant order ids object which contains details about the retailer's order identifiers"
          },
          "tracking": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tracking"
            },
            "description": "An array of tracking objects that contain the order's tracking information"
          },
          "request": {
            "type": "object",
            "description": "The original request that was sent to the Zinc API"
          },
          "delivery_dates": {
            "type": "array",
            "description": "An array of ordered products and their given delivery dates"
          },
          "account_status": {
            "$ref": "#/components/schemas/AccountStatus",
            "description": "(Amazon only) An account status object that gives details about the ordering account"
          }
        }
      },
      "ProcessingError": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["error"]
          },
          "code": {
            "type": "string",
            "description": "Error code. Most commonly `request_processing`, but can be any error code from the [Error Handling](/v1/api-reference/introduction/error-handling) documentation."
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "data": {
            "type": "object",
            "description": "Additional error data"
          }
        }
      },
      "PriceComponents": {
        "type": "object",
        "properties": {
          "converted_payment_total": {
            "type": "integer",
            "description": "Converted payment total in cents"
          },
          "currency": {
            "type": "string",
            "description": "Currency code"
          },
          "payment_currency": {
            "type": "string",
            "description": "Payment currency code"
          },
          "shipping": {
            "type": "integer",
            "description": "Shipping cost in cents"
          },
          "subtotal": {
            "type": "integer",
            "description": "Subtotal in cents"
          },
          "tax": {
            "type": "integer",
            "description": "Tax amount in cents"
          },
          "total": {
            "type": "integer",
            "description": "Total amount in cents"
          }
        }
      },
      "MerchantOrderId": {
        "type": "object",
        "properties": {
          "merchant_order_id": {
            "type": "string",
            "description": "The merchant's order identifier"
          },
          "merchant": {
            "type": "string",
            "description": "The merchant name"
          },
          "account": {
            "type": "string",
            "description": "The account email"
          },
          "placed_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the order was placed"
          }
        }
      },
      "Tracking": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string",
            "description": "The product identifier"
          },
          "merchant_order_id": {
            "type": "string",
            "description": "The merchant's order identifier"
          },
          "carrier": {
            "type": "string",
            "description": "The shipping carrier"
          },
          "tracking_number": {
            "type": "string",
            "description": "The tracking number"
          },
          "obtained_at": {
            "type": "string",
            "format": "date-time",
            "description": "When tracking was obtained"
          }
        }
      },
      "Address": {
          "type": "object",
          "required": ["first_name", "last_name", "address_line1",  "city", "state", "zip_code", "country", "phone_number"],
          "properties": {
            "first_name": { 
              "type": "string"
            },
            "last_name": { 
              "type": "string"
            },
            "address_line1": { 
              "type": "string"
            },
            "address_line2": { 
              "type": "string"
            },
            "zip_code": { 
              "type": "string"
            },
            "city": { 
              "type": "string"
            },
            "state": { 
              "type": "string",
              "description": "The USPS abbreviation for the state of the address (e.g. AK)"
            },
            "country": { 
              "type": "string",
              "description": "The ISO abbreviation for the country of the address (e.g. US). A list of all available two-letter country codes can be found [here](https://www.theodora.com/country_digraphs.html)."
            },
            "phone_number": { 
              "type": "string"
            },
            "instructions": { 
              "type": "string",
              "description": "Optional instructions to include with the shipping addresses"
            }
          }
        },
      "PaymentMethod": {
        "type": "object",
        "properties": {
          "name_on_card": { "type": "string" },
          "number": { "type": "string" },
          "security_code": { "type": "string" },
          "expiration_month": { "type": "integer" },
          "expiration_year": { "type": "integer" },
          "use_gift": { "type": "boolean" }
        }
      },
      "RetailerCredentials": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "password": { "type": "string" },
          "totp_2fa_key": { "type": "string" }
        }
      },
      "Shipping": {
        "type": "object",
        "required": ["order_by", "max_days", "max_price"],
        "properties": {
          "order_by": { 
            "type": "string",
            "description": "The ordering of available shipping methods that meet the desired criteria. Available values are `price` or `speed`. If ordering by price, then the Zinc API will choose the cheapest shipping method that meets the desired criteria, while speed will choose the fastest shipping method meeting the criteria."
          },
          "max_days": { 
            "type": "integer",
            "description": "The maximum number of days allowed for shipping on the order."
          },
          "max_price": { 
            "type": "integer",
            "description": "The maximum price in cents allowed for the shipping cost of the order."
          }
        }
      },
      "SellerSelectionCriteria": {
        "type": "object",
        "properties": {
          "addon": { 
            "type": "boolean",
            "description": "(Amazon only) Specifies whether the selected offer should be an addon item"
          },
          "buy_box": { 
            "type": "boolean",
            "description": "(Amazon only) Specifies whether the selected offer should be Amazon's default buy box offer"
          },
          "condition_in": { 
            "type": "array",
            "items": { "type": "string" },
            "description": "An array of item conditions that the Zinc API must order from"
          },
          "condition_not_in": { 
            "type": "array",
            "items": { "type": "string" },
            "description": "An array of item conditions that the Zinc API must not order from"
          },
          "first_party_seller": { 
            "type": "boolean",
            "description": "Is the seller first-party? e.g. sold by Walmart.com on walmart"
          },
          "handling_days_max": { 
            "type": "integer",
            "description": "The maximum number of allowable days for shipping and handling"
          },
          "international": { 
            "type": "boolean",
            "description": "Specifies whether the item should come from an international supplier"
          },
          "max_item_price": { 
            "type": "integer",
            "description": "The maximum allowable price in cents for an item"
          },
          "merchant_id_in": { 
            "type": "array",
            "items": { "type": "string" },
            "description": "(Amazon only) An array of merchant ids that the Zinc API must order from"
          },
          "merchant_id_not_in": { 
            "type": "array",
            "items": { "type": "string" },
            "description": "(Amazon only) An array of merchant ids that the Zinc API must not order from"
          },
          "min_seller_num_ratings": { 
            "type": "integer",
            "description": "(Amazon only) The minimum number of ratings required for an Amazon seller's offer to be selected"
          },
          "min_seller_percent_positive_feedback": { 
            "type": "integer",
            "description": "(Amazon only) The minimum percentage of positive ratings of an Amazon seller for their offer to be selected"
          },
          "prime": { 
            "type": "boolean",
            "description": "(Amazon only) Specifies whether the selected offer should be an Amazon Prime offer"
          },
          "allow_oos": { 
            "type": "boolean",
            "description": "(Amazon only) Specifies whether we should still attempt to complete ordering with the cheapest offer if all offers appear unavailable"
          }
        }
      },
      "CreateReturnRequest": {
        "type": "object",
        "required": ["products", "reason_code", "method_code", "explanation"],
        "properties": {
          "products": {
            "type": "array",
            "description": "A list of product objects that should be returned",
            "items": {
              "type": "object",
              "properties": {
                "product_id": {
                  "type": "string",
                  "description": "The product ID to return"
                },
                "quantity": {
                  "type": "integer",
                  "description": "The quantity to return"
                }
              }
            }
          },
          "reason_code": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "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": {
            "type": "string",
            "description": "Any extra information that will be passed to Amazon or the Amazon seller. It is required for some return reasons."
          },
          "webhooks": {
            "type": "object",
            "description": "A webhooks object including URLs that will receive POST requests after particular events have finished.",
            "properties": {
              "request_succeeded": {
                "type": "string",
                "description": "URL to receive success webhooks"
              },
              "request_failed": {
                "type": "string",
                "description": "URL to receive failure webhooks"
              }
            }
          },
          "cancel_pending": {
            "type": "boolean",
            "description": "Whether or not this request should cancel any pending returns while creating a new return. Defaults to false."
          },
          "return_address": {
            "type": "object",
            "description": "An address object from which the return is sent. If not provided, the default return address from Amazon will be used."
          }
        }
      },
      "CreateReturnResponse": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The unique identifier for the return request"
          }
        }
      },
      "ReturnDetailsResponse": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["return_response"]
          },
          "merchant_return_id": {
            "type": "string",
            "description": "A unique identifier for the return"
          },
          "return_by": {
            "type": "string",
            "description": "The date before which the products must be returned by"
          },
          "label_urls": {
            "type": "array",
            "description": "A list of URLs for the generated return labels",
            "items": {
              "type": "string"
            }
          },
          "request": {
            "type": "object",
            "description": "The original order request that was sent to the Zinc API"
          }
        }
      },
      "ReturnErrorResponse": {
        "type": "object",
        "properties": {
          "_type": {
            "type": "string",
            "description": "Response type",
            "enum": ["error"]
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "enum": ["return_in_progress"]
          },
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "Status description"
                  },
                  "description": {
                    "type": "string",
                    "description": "Status details"
                  }
                }
              },
              "error": {
                "type": "string",
                "description": "Additional error information"
              }
            }
          },
          "request": {
            "type": "object",
            "description": "The original request that was sent to the Zinc API"
          }
        }
      },
      "ProductDetailsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status of the request. You will only see `processing` if `async: true` was set on the request",
            "enum": ["processing", "failed", "completed"]
          },
          "retailer": {
            "type": "string",
            "description": "The retailer for the product"
          },
          "product_id": {
            "type": "string",
            "description": "The retailer's unique identifier for the product"
          },
          "timestamp": {
            "type": "string",
            "description": "The timestamp that the resource was accessed"
          },
          "title": {
            "type": "string",
            "description": "Title of the product"
          },
          "product_details": {
            "type": "array",
            "description": "An array of strings providing details about the product",
            "items": {
              "type": "string"
            }
          },
          "feature_bullets": {
            "type": "array",
            "description": "An array of strings providing highlights of the product",
            "items": {
              "type": "string"
            }
          },
          "brand": {
            "type": "string",
            "description": "The brand of the product (if available)"
          },
          "main_image": {
            "type": "string",
            "description": "The URL of the primary image associated with the product"
          },
          "images": {
            "type": "array",
            "description": "An array of image URLs associated with the product",
            "items": {
              "type": "string"
            }
          },
          "variant_specifics": {
            "type": "array",
            "description": "Array of objects containing information about the types and values of a particular product variant",
            "items": {
              "type": "object",
              "properties": {
                "dimension": {
                  "type": "string",
                  "description": "The type of the variant (e.g. 'Color')"
                },
                "value": {
                  "type": "string",
                  "description": "The specific value available"
                }
              }
            }
          },
          "all_variants": {
            "type": "array",
            "description": "An array of variant_specifics objects detailing all variants of the product as well as their product IDs",
            "items": {
              "type": "object",
              "properties": {
                "variant_specifics": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "dimension": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    }
                  }
                },
                "product_id": {
                  "type": "string"
                }
              }
            }
          },
          "categories": {
            "type": "array",
            "description": "Array of different categories that the product belongs in",
            "items": {
              "type": "string"
            }
          },
          "authors": {
            "type": "array",
            "description": "Array of author names (only available for products that are books)",
            "items": {
              "type": "string"
            }
          },
          "product_description": {
            "type": "string",
            "description": "The description of the product"
          },
          "epids": {
            "type": "array",
            "description": "Array of objects containing external product identifier (epid) objects",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "The name of the external product identifier"
                },
                "value": {
                  "type": "string",
                  "description": "The identifier's value"
                }
              }
            }
          },
          "epids_map": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "An array of the epids with the epid type as the field and the epid value as the value"
          },
          "package_dimensions": {
            "type": "array",
            "description": "An array detailing the packaging details if available. Each dimension contains a 'amount' and 'unit'",
            "items": {
              "type": "object",
              "properties": {
                "amount": {
                  "type": "number"
                },
                "unit": {
                  "type": "string"
                }
              }
            }
          },
          "item_location": {
            "type": "string",
            "description": "(AliExpress only) The originating location of the product"
          },
          "original_retail_price": {
            "type": "number",
            "description": "(Amazon only) The 'List Price' in cents of the product (present if the retailer is presenting a crossed out list price)"
          },
          "price": {
            "type": "number",
            "description": "(Amazon only) The price in cents of the buy box price of the item. **This is not always returned and is often not the cheapest option. If you want a product's price you should use [Product Offers](/v1/api-reference/products/offers).**"
          },
          "review_count": {
            "type": "number",
            "description": "(Amazon only) The number of reviews of the product"
          },
          "stars": {
            "type": "number",
            "description": "(Amazon only) The review score of the product"
          },
          "question_count": {
            "type": "number",
            "description": "(Amazon only) The number of questions on the Amazon question section"
          },
          "asin": {
            "type": "string",
            "description": "(Amazon only) The ASIN of the product"
          },
          "fresh": {
            "type": "boolean",
            "description": "(Amazon only) `TRUE` if the item is an Amazon Fresh item"
          },
          "pantry": {
            "type": "boolean",
            "description": "(Amazon only) `TRUE` if the item is an Amazon Pantry item"
          },
          "handmade": {
            "type": "boolean",
            "description": "(Amazon only) `TRUE` if the item is an Amazon Handmade item"
          },
          "digital": {
            "type": "boolean",
            "description": "(Amazon only) `TRUE` if the item is a digital-only item (software subscription, downloadable software, digital video, game codes, etc.)"
          },
          "buyapi_hint": {
            "type": "boolean",
            "description": "(Amazon only) False if the item cannot be ordered via the buyapi, `TRUE` if it might be orderable"
          },
          "item_number": {
            "type": "string",
            "description": "(Costco only) The Costco item number of the product (may not contain variant details)"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "description": "Response for product search",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status of the request. You will only see `processing` if `async: true` was set on the request",
            "enum": ["processing", "failed", "completed"]
          },
          "timestamp": {
            "type": "number",
            "description": "Timestamp of the search"
          },
          "retailer": {
            "type": "string",
            "description": "The retailer searched"
          },
          "results": {
            "type": "array",
            "description": "Array of search results",
            "items": {
              "type": "object",
              "properties": {
                "product_id": {
                  "type": "string",
                  "description": "The product ID"
                },
                "title": {
                  "type": "string",
                  "description": "The product title"
                },
                "image": {
                  "type": "string",
                  "description": "The product image URL"
                },
                "num_reviews": {
                  "type": "number",
                  "description": "Number of reviews"
                },
                "stars": {
                  "type": "string",
                  "description": "Star rating"
                },
                "fresh": {
                  "type": "boolean",
                  "description": "Whether the item is fresh"
                },
                "price": {
                  "type": "number",
                  "description": "The product price in cents"
                }
              }
            }
          }
        }
      },
      "ProductOffersResponse": {
        "type": "object",
        "description": "Response for product offers",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status of the request. You will only see `processing` if `async: true` was set on the request",
            "enum": ["processing", "failed", "completed"]
          },
          "retailer": {
            "type": "string",
            "description": "The retailer for the product. See [Supported Retailers](/v1/supported-retailers) for a list of supported retailers."
          },
          "offers": {
            "type": "array",
            "description": "Array of offers for the product",
            "items": {
              "$ref": "#/components/schemas/ProductOffer"
            }
          }
        }
      },
      "AccountStatus": {
        "type": "object",
        "properties": {
          "prime": {
            "type": "boolean",
            "description": "Indicates if the account has Prime enabled"
          },
          "fresh": {
            "type": "boolean",
            "description": "Indicates if the account has Fresh enabled"
          },
          "business": {
            "type": "boolean",
            "description": "Indicates if the account has Business enabled"
          },
          "charity": {
            "type": "string",
            "description": "Indicates if the account has a Charity associated"
          }
        }
      },
      "PromoCode": {
        "type": "object",
        "required": ["code"],
        "properties": {
          "code": {
            "type": "string",
            "description": "The promo code to apply (required)"
          },
          "optional": {
            "type": "boolean",
            "description": "Should we continue placing the order if this code fails to apply? Defaults to false."
          },
          "merchant_id": {
            "type": "string",
            "description": "If supplied, only try this code if we selected an offer from the given merchant."
          },
          "discount_amount": {
            "type": "number",
            "description": "Fixed amount in cents by which we should discount the matching merchant's offers during offer selection. Only makes sense if merchant_id is also supplied. Defaults to 0."
          },
          "discount_percentage": {
            "type": "number",
            "description": "Percentage amount (between 0 and 100) by which we should discount the matching merchant's offers during offer selection. Only makes sense if merchant_id is also supplied. Defaults to 0."
          },
          "cost_override": {
            "type": "number",
            "description": "If supplied, we will assume all offers by this merchant cost exactly this many cents. Only makes sense if merchant_id is also supplied. Overrides other discount methods."
          }
        }
      },
      "CaseRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "The reason for opening a case (required when opening a new case)",
            "enum": [
              "return.request_label",
              "nondelivery.not_delivered",
              "nondelivery.damaged",
              "nondelivery.empty_box",
              "tracking.request_update",
              "cancel.forced_cancellation",
              "other"
            ]
          },
          "message": {
            "type": "string",
            "description": "Message content for the case"
          }
        },
        "required": ["message"]
      },
      "CaseResponse": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string",
            "description": "Current state of the case",
            "enum": ["open", "closed"],
            "nullable": true
          },
          "messages": {
            "type": "array",
            "description": "Array of case messages and updates",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Type of case message",
                  "enum": [
                    "case.opened.return.request_label",
                    "case.opened.nondelivery.not_delivered",
                    "case.opened.nondelivery.damaged",
                    "case.opened.nondelivery.empty_box",
                    "case.opened.tracking.request_update",
                    "case.opened.cancel.forced_cancellation",
                    "case.opened.other",
                    "case.freetext",
                    "case.return.label_generated",
                    "case.return.status_updated",
                    "case.refund.partial",
                    "case.refund.full",
                    "case.closed"
                  ]
                },
                "message": {
                  "type": "string",
                  "description": "Message content"
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When the message was created"
                }
              }
            }
          }
        }
      },
      "ProductOffer": {
        "type": "object",
        "properties": {
          "addon": {
            "type": "boolean",
            "description": "Whether or not the product is an addon item that can only be purchased in a bundle"
          },
          "condition": {
            "type": "string",
            "description": "The condition of the product",
            "enum": [
              "New",
              "Refurbished",
              "Used - Like New",
              "Used - Very Good",
              "Used - Good",
              "Used - Acceptable",
              "Unacceptable"
            ]
          },
          "handling_days": {
            "type": "object",
            "properties": {
              "max": {
                "type": "number",
                "description": "The maximum number of days required for shipping and handling"
              },
              "min": {
                "type": "number",
                "description": "The minimum number of days required for shipping and handling"
              }
            }
          },
          "international": {
            "type": "boolean",
            "description": "Whether or not the product ships from outside of the United States"
          },
          "offer_id": {
            "type": "string",
            "description": "(Amazon only). The unique identifier that identifies an item sold by any merchant on Amazon"
          },
          "price": {
            "type": "number",
            "description": "The price of the item, not including shipping in cents."
          },
          "marketplace_fulfilled": {
            "type": "boolean",
            "description": "Whether or not the product ships direct from retailer. For Amazon, this indicates if the item is shipped with Prime shipping."
          },
          "seller": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "The merchant's unique identifier for the product"
              },
              "name": {
                "type": "string",
                "description": "The name of the seller of the current offer"
              },
              "num_ratings": {
                "type": "number",
                "description": "The number of ratings that the seller has accumulated"
              },
              "percent_positive": {
                "type": "number",
                "description": "Number between 0 and 100 denoting the percentage of positive ratings the seller has received"
              },
              "first_party": {
                "type": "boolean",
                "description": "Whether the seller is first-party"
              }
            }
          },
          "shipping_options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "price": {
                  "type": "number",
                  "description": "The cost to ship the item in cents"
                },
                "delivery_days": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "type": "number",
                      "description": "The minimum time in days it might take for the item to be delivered"
                    },
                    "max": {
                      "type": "number",
                      "description": "The maximum time in days it might take for the item to be delivered"
                    }
                  }
                },
                "name": {
                  "type": "string",
                  "description": "The name of the shipping option"
                }
              }
            }
          },
          "prime_only": {
            "type": "boolean",
            "description": "(Amazon only). Whether or not the product only ships using Amazon Prime"
          },
          "member_only": {
            "type": "boolean",
            "description": "(Costco only) Whether or not the purchase must be from a Costco Member"
          },
          "available": {
            "type": "boolean",
            "description": "Whether the offer is currently available"
          }
        }
      },
      "WebhooksObject": {
        "type": "object",
        "description": "A webhooks object including URLs that will receive `POST` requests after particular events have finished. See [Webhooks](/v1/api-reference/introduction/webhooks) for more details.",
        "properties": {
          "request_succeeded": {
            "type": "string",
            "description": "The webhook URL to send data to when a request succeeds"
          },
          "request_failed": {
            "type": "string",
            "description": "The webhook URL to send data to when a request fails"
          },
          "tracking_obtained": {
            "type": "string",
            "description": "The webhook URL to send data to when ALL tracking for an order is retrieved (placing orders call only)"
          },
          "tracking_updated": {
            "type": "string",
            "description": "The webhook URL to send data to when ANY tracking for an order is retrieved (placing orders call only)"
          },
          "status_updated": {
            "type": "string",
            "description": "The webhook URL to send data to when the status of a request is updated"
          },
          "case_updated": {
            "type": "string",
            "description": "The webhook URL to send data to when a ZMA case associated with the order receives an update"
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic", 
        "description": "Use your client token as the username. Leave the password blank."
      }
    }
  }
}