{
  "openapi": "3.1.0",
  "info": {
    "title": "ASINScope API",
    "version": "1.0.0",
    "summary": "Amazon product lookups by ASIN, UPC or EAN: ASIN to UPC/EAN, UPC/EAN to ASIN, and product details across 13 Amazon marketplaces.",
    "description": "The ASINScope API returns Amazon product data for up to 10 identifiers per request: UPC, EAN and MPN codes, title, brand, category, current lowest new price, Best Sellers Rank, package dimensions and images.\n\n**Authentication.** Send your API key in the `x-api-key` header on every request. The `key` query parameter is also accepted, but a key in the URL ends up in logs and proxies, so prefer the header. Keys are issued in the API dashboard (https://asinscope.com/en/dashboard/api) once an API plan is active.\n\n**One identifier type per request.** Send exactly one of `asin`, `upc` or `ean`, as a comma-separated list of 1 to 10 codes (Enterprise plans allow more; the 400 error states your limit). Mixing types, or sending none, is a 400.\n\n**Tokens.** Every code costs at least one token, even when it matches nothing. ASIN lookups cost exactly one token per ASIN. UPC/EAN lookups cost one token per listing returned: a barcode shared by 56 listings costs 56 tokens, so a request costs `max(codes sent, listings returned)`. Every successful lookup reports `consumedTokens`, `dailyTokensLeft` and `bucketSize`, so quota-aware code reads them from each response instead of polling. `GET /account/tokens` reports the same state without consuming tokens.\n\n**Two limits, both HTTP 429.** A daily allowance (Basic 1,000, Pro 10,000 tokens per day, reset at 00:00 UTC) and a short-term bucket that refills continuously (Basic: 60 tokens, refilling 10 per minute; Pro: 120 tokens, refilling 60 per minute). Tell them apart by the `code` in the body: `DAILY_LIMIT_REACHED` will not clear until 00:00 UTC, so stop; `TOKEN_BUCKET_EMPTY` clears within about a minute, so wait and retry. Both carry `retryAfterSeconds` in the body and a `Retry-After` header.\n\n**Errors.** Every 4xx error body carries a stable `code`. Branch on `code`, never on the message text, which may change. Never retry 400, 401 or 403.\n\n**Matching results.** Do not rely on the order of `items` or on one entry per code. Match items back to your codes by `asin`, `upcList` or `eanList`. A code with no matching item, or whose item has no `title`, was not found on that marketplace.\n\nAI integration guide: https://docs.asinscope.com/asinscope-api/ai/. Plain-text reference: https://docs.asinscope.com/llms-full.txt.",
    "termsOfService": "https://asinscope.com/en/terms-of-service",
    "contact": {
      "name": "ASINScope support",
      "email": "support@asinscope.com",
      "url": "https://docs.asinscope.com/asinscope-api/"
    }
  },
  "externalDocs": {
    "description": "API reference and AI integration guide",
    "url": "https://docs.asinscope.com/asinscope-api/"
  },
  "servers": [
    {
      "url": "https://api.asinscope.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "ApiKeyQuery": []
    }
  ],
  "tags": [
    {
      "name": "Products",
      "description": "Product lookups by ASIN, UPC or EAN."
    },
    {
      "name": "Account",
      "description": "Token balance and limits."
    }
  ],
  "paths": {
    "/products/lookup": {
      "get": {
        "operationId": "lookupProducts",
        "tags": ["Products"],
        "summary": "Look up products by ASIN, UPC or EAN",
        "description": "Returns product details for up to 10 codes of one identifier type. Use `asin` for ASIN to UPC/EAN lookups, and `upc` or `ean` for barcode to ASIN lookups. Barcode lookups can return several listings per code, and each listing returned costs one token.",
        "parameters": [
          {
            "name": "asin",
            "in": "query",
            "required": false,
            "description": "Comma-separated ASINs (1 to 10). Send exactly one of `asin`, `upc`, `ean`.",
            "schema": {
              "type": "string"
            },
            "example": "B088H39PXX,B01NAL48FU"
          },
          {
            "name": "upc",
            "in": "query",
            "required": false,
            "description": "Comma-separated 12-digit UPC-A codes (1 to 10). Keep them as strings so leading zeros survive. Each listing returned costs one token. Send exactly one of `asin`, `upc`, `ean`.",
            "schema": {
              "type": "string"
            },
            "example": "793610399007"
          },
          {
            "name": "ean",
            "in": "query",
            "required": false,
            "description": "Comma-separated 13-digit EAN-13 codes (1 to 10). A UPC-A is the same product as the EAN-13 with a leading 0. Each listing returned costs one token. Send exactly one of `asin`, `upc`, `ean`.",
            "schema": {
              "type": "string"
            },
            "example": "4006381333931"
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Amazon marketplace. Defaults to `com` (amazon.com); pass it explicitly for every other marketplace.",
            "schema": {
              "$ref": "#/components/schemas/Domain"
            }
          },
          {
            "name": "desc",
            "in": "query",
            "required": false,
            "description": "`1` adds the listing `description` and `bullets` to each item. They make responses much larger, so request them only when needed.",
            "schema": {
              "type": "string",
              "enum": ["0", "1"],
              "default": "0"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products and the token state after this request. Codes that matched nothing have no usable item but are still charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductsLookupResponse"
                },
                "examples": {
                  "asinLookup": {
                    "summary": "ASIN to UPC/EAN",
                    "value": {
                      "items": [
                        {
                          "asin": "B088H39PXX",
                          "ean": "0793610399007",
                          "upc": "793610399007",
                          "mpn": "2143",
                          "bsr": 95,
                          "category": "Sports & Outdoors",
                          "brand": "CUKU",
                          "title": "Magnetic Dart Board - 12pcs Magnetic Darts (Red Green Yellow) - Excellent Indoor Game and Party Games",
                          "productGroup": "Sports",
                          "lowestNewPrice": 22.79,
                          "lowestFormattedPrice": "$22.79",
                          "soldByAmazon": false,
                          "packageDimensions": {
                            "height": 1.77,
                            "width": 13.46,
                            "length": 13.58,
                            "weight": 2.07
                          },
                          "upcList": ["793610399007"],
                          "eanList": ["0793610399007"],
                          "totalNew": 2,
                          "smallImage": "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg",
                          "mediumImage": "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg",
                          "images": [
                            "https://images-na.ssl-images-amazon.com/images/I/91we94LQPhL.jpg",
                            "https://images-na.ssl-images-amazon.com/images/I/91WKu-Y+P4L.jpg"
                          ]
                        }
                      ],
                      "dailyTokensLeft": 9998,
                      "bucketSize": 119,
                      "msBeforeNextDailyToken": 82524143,
                      "consumedTokens": 1
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed parameters. Fix the request; never retry it unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "noIdentifier": {
                    "summary": "None or several of asin/upc/ean",
                    "value": {
                      "error": "Invalid input. Exactly one of asin, upc or ean must be present",
                      "code": "INVALID_REQUEST"
                    }
                  },
                  "tooManyCodes": {
                    "summary": "More codes than the plan allows",
                    "value": {
                      "error": "The max number of codes in one request is 10, but 12 were requested.",
                      "code": "TOO_MANY_CODES"
                    }
                  },
                  "badDomain": {
                    "summary": "Unsupported domain",
                    "value": {
                      "error": "Invalid input. domain must be one of the following values: com, ca, de, fr, it, nl, es, in, uk, jp, au, mx, pl",
                      "code": "INVALID_REQUEST"
                    }
                  },
                  "missingKey": {
                    "summary": "No API key sent",
                    "value": {
                      "error": "Invalid input. API key is required.",
                      "code": "MISSING_API_KEY"
                    }
                  },
                  "noValidCodes": {
                    "summary": "No valid ASIN in the list",
                    "value": {
                      "error": "Invalid input. The request contains no valid product codes.",
                      "code": "INVALID_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "A limit was hit. Branch on `code`: `DAILY_LIMIT_REACHED` clears at 00:00 UTC, so stop; `TOKEN_BUCKET_EMPTY` refills continuously, so wait `retryAfterSeconds` and retry.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DailyLimitError"
                    },
                    {
                      "$ref": "#/components/schemas/ErrorBody"
                    }
                  ]
                },
                "examples": {
                  "dailyLimit": {
                    "summary": "Daily limit reached (stop until 00:00 UTC)",
                    "value": {
                      "statusCode": 429,
                      "message": "Daily limit reached. Please try again in 312 minutes",
                      "error": "Too Many Requests",
                      "code": "DAILY_LIMIT_REACHED",
                      "retryAfterSeconds": 18720
                    }
                  },
                  "bucketEmpty": {
                    "summary": "Short-term bucket empty (wait and retry)",
                    "value": {
                      "error": "Not enough tokens in the bucket. Restore rate: 10 / min",
                      "code": "TOKEN_BUCKET_EMPTY",
                      "retryAfterSeconds": 60
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/account/tokens": {
      "get": {
        "operationId": "getTokens",
        "tags": ["Account"],
        "summary": "Get the current token balance and limits",
        "description": "Returns the daily balance and the short-term bucket state without consuming any tokens. Call it before taking work off a queue, or once at startup to read `tokensPerMinute` for pacing. Lookup responses already carry the balance, so there is no need to call this between lookups.",
        "responses": {
          "200": {
            "description": "Current token state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokensResponse"
                },
                "example": {
                  "dailyTokensLeft": 9812,
                  "dailyTokensLimit": 10000,
                  "minutelyTokensLeft": 119,
                  "minutelyBucketCapacity": 120,
                  "tokensPerMinute": 60,
                  "msBeforeNextDailyReset": 82524143
                }
              }
            }
          },
          "400": {
            "description": "No API key was sent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "error": "API key is required.",
                  "code": "MISSING_API_KEY"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Preferred. Your API key, from https://asinscope.com/en/dashboard/api."
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "key",
        "description": "Also accepted for existing integrations. A key in the URL ends up in logs and proxies, so prefer the `x-api-key` header."
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Seconds to wait before the request can succeed. Same value as `retryAfterSeconds` in the body.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "InvalidApiKey": {
        "description": "The API key is not valid. Never retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorBody"
            },
            "example": {
              "error": "Invalid API key",
              "code": "INVALID_API_KEY"
            }
          }
        }
      },
      "Forbidden": {
        "description": "No active subscription. Never retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorBody"
            },
            "example": {
              "error": "The subscription is not active.",
              "code": "NO_ACTIVE_SUBSCRIPTION"
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error. Retry a few times with exponential backoff.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      }
    },
    "schemas": {
      "Domain": {
        "type": "string",
        "description": "Amazon marketplace: com = amazon.com, ca = amazon.ca, de = amazon.de, fr = amazon.fr, it = amazon.it, nl = amazon.nl, es = amazon.es, in = amazon.in, uk = amazon.co.uk, jp = amazon.co.jp, au = amazon.com.au, mx = amazon.com.mx, pl = amazon.pl.",
        "enum": ["com", "ca", "de", "fr", "it", "nl", "es", "in", "uk", "jp", "au", "mx", "pl"],
        "default": "com"
      },
      "ProductItem": {
        "type": "object",
        "description": "One Amazon listing. Match it to your input by `asin`, `upcList` or `eanList`.",
        "required": ["asin", "upcList", "eanList", "images"],
        "properties": {
          "asin": {
            "type": "string",
            "description": "Amazon Standard Identification Number."
          },
          "upc": {
            "type": ["string", "null"],
            "description": "Primary UPC-A. A listing can carry several; see `upcList`."
          },
          "ean": {
            "type": ["string", "null"],
            "description": "Primary EAN-13. A listing can carry several; see `eanList`."
          },
          "mpn": {
            "type": ["string", "null"],
            "description": "Manufacturer part number."
          },
          "bsr": {
            "type": ["integer", "null"],
            "description": "Best Sellers Rank in the main category."
          },
          "category": {
            "type": ["string", "null"],
            "description": "Main category name."
          },
          "brand": {
            "type": ["string", "null"]
          },
          "title": {
            "type": ["string", "null"],
            "description": "Listing title. Empty or null means the code wasn't found on this marketplace."
          },
          "productGroup": {
            "type": ["string", "null"]
          },
          "lowestNewPrice": {
            "type": ["number", "null"],
            "description": "Current lowest new price in the marketplace currency."
          },
          "lowestFormattedPrice": {
            "type": "string",
            "description": "`lowestNewPrice` with the currency symbol. Absent when there is no price."
          },
          "soldByAmazon": {
            "type": "boolean",
            "description": "Whether Amazon itself sells the product."
          },
          "packageDimensions": {
            "type": "object",
            "description": "Package size. Absent when Amazon has no package data.",
            "properties": {
              "height": {
                "type": "number",
                "description": "Inches."
              },
              "width": {
                "type": "number",
                "description": "Inches."
              },
              "length": {
                "type": "number",
                "description": "Inches."
              },
              "weight": {
                "type": "number",
                "description": "Pounds."
              }
            }
          },
          "upcList": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every UPC Amazon lists for the product."
          },
          "eanList": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every EAN Amazon lists for the product."
          },
          "totalNew": {
            "type": ["integer", "null"],
            "description": "Number of new offers."
          },
          "smallImage": {
            "type": "string",
            "format": "uri",
            "description": "First product image. Absent when there are no images."
          },
          "mediumImage": {
            "type": "string",
            "format": "uri",
            "description": "First product image. Absent when there are no images."
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "description": {
            "type": "string",
            "description": "Listing description. Only with `desc=1`."
          },
          "bullets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Listing bullet points. Only with `desc=1`."
          }
        }
      },
      "ProductsLookupResponse": {
        "type": "object",
        "required": [
          "items",
          "dailyTokensLeft",
          "bucketSize",
          "msBeforeNextDailyToken",
          "consumedTokens"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductItem"
            },
            "description": "Matching listings. Not ordered like your codes, and not one entry per code."
          },
          "dailyTokensLeft": {
            "type": "integer",
            "description": "Tokens left for today after this request. Resets at 00:00 UTC."
          },
          "bucketSize": {
            "type": "integer",
            "description": "Tokens left in the short-term bucket after this request."
          },
          "msBeforeNextDailyToken": {
            "type": "integer",
            "description": "Milliseconds until the daily allowance resets."
          },
          "consumedTokens": {
            "type": "integer",
            "description": "Tokens this request cost: max(codes sent, listings returned)."
          }
        }
      },
      "TokensResponse": {
        "type": "object",
        "required": [
          "dailyTokensLeft",
          "dailyTokensLimit",
          "minutelyTokensLeft",
          "minutelyBucketCapacity",
          "tokensPerMinute",
          "msBeforeNextDailyReset"
        ],
        "properties": {
          "dailyTokensLeft": {
            "type": "integer",
            "description": "Tokens left for today."
          },
          "dailyTokensLimit": {
            "type": "integer",
            "description": "Daily allowance of your plan."
          },
          "minutelyTokensLeft": {
            "type": "integer",
            "description": "Tokens currently in the short-term bucket."
          },
          "minutelyBucketCapacity": {
            "type": "integer",
            "description": "Maximum size of the short-term bucket."
          },
          "tokensPerMinute": {
            "type": "integer",
            "description": "Bucket refill rate. Use it to pace requests."
          },
          "msBeforeNextDailyReset": {
            "type": "integer",
            "description": "Milliseconds until the daily allowance resets at 00:00 UTC."
          }
        }
      },
      "ErrorCode": {
        "type": "string",
        "description": "Stable, machine-readable error code. Branch on this, not on the message text. INVALID_REQUEST: malformed or missing parameters. MISSING_API_KEY: no key was sent. TOO_MANY_CODES: more codes than the plan allows in one request. INVALID_API_KEY: the key is not valid. NO_ACTIVE_SUBSCRIPTION: the key has no active API plan. TOKEN_BUCKET_EMPTY: the short-term bucket is empty; wait `retryAfterSeconds` and retry. DAILY_LIMIT_REACHED: the daily allowance is used up; stop until 00:00 UTC.",
        "enum": [
          "INVALID_REQUEST",
          "MISSING_API_KEY",
          "TOO_MANY_CODES",
          "INVALID_API_KEY",
          "NO_ACTIVE_SUBSCRIPTION",
          "TOKEN_BUCKET_EMPTY",
          "DAILY_LIMIT_REACHED"
        ]
      },
      "ErrorBody": {
        "type": "object",
        "required": ["error", "code"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable reason. May change; do not match on it."
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "retryAfterSeconds": {
            "type": "integer",
            "description": "Seconds until the request can succeed. Only on 429 responses."
          }
        }
      },
      "DailyLimitError": {
        "type": "object",
        "description": "Daily allowance used up. It resets at 00:00 UTC.",
        "required": ["statusCode", "message", "error", "code", "retryAfterSeconds"],
        "properties": {
          "statusCode": {
            "type": "integer",
            "const": 429
          },
          "message": {
            "type": "string",
            "description": "Human-readable reason. May change; do not match on it."
          },
          "error": {
            "type": "string",
            "const": "Too Many Requests"
          },
          "code": {
            "type": "string",
            "const": "DAILY_LIMIT_REACHED"
          },
          "retryAfterSeconds": {
            "type": "integer",
            "description": "Seconds until the daily allowance resets."
          }
        }
      }
    }
  }
}
