ASINScope Barcodes API Documentation for Circana

Overview

This document describes the custom ASINScope API endpoint created specifically for Circana to retrieve UPC and EAN barcode information for Amazon ASINs. The API is optimized for high-throughput processing with support for batch requests.

Current Status: Trial Access (30 products/minute, 1,000 products/day)
Full Subscription: 500 products/minute, 150,000 products/day (upon activation)

Base URL

https://api.asinscope.com/circana/barcodes

Authentication

Authentication is performed via API key passed as a POST parameter in the request body:

{
  "key": "<API_KEY>"
}

Getting Your API Key: You can find and copy your API key from the ASINScope API Dashboard.

Important: Keep your API key secure and do not share it publicly.

Request Format

HTTP Method

POST

Headers

Content-Type: application/json

Request Body

The request body must be a JSON object containing an array of ASINs and your API key:

{
  "key": "<API_KEY>",
  "asins": [
    "ASIN1",
    "ASIN2",
    "ASIN3",
    ...
  ]
}

Constraints:

• Maximum 100 ASINs per request
• ASINs must be valid Amazon.com product identifiers
• ASINs should be provided as strings

Example Request

curl --location 'https://api.asinscope.com/circana/barcodes' \
--header 'Content-Type: application/json' \
--data '{
    "key": "<API_KEY>",
    "asins": ["B0086FFHLS", "B00NNUMI86"]
}'

Response Format

Successful Response

The API returns a JSON object with the following structure:

{
  "items": [
    {
      "asin": "string",
      "title": "string",
      "upc": "string | null",
      "upcList": [
        "string"
      ],
      "ean": "string | null",
      "eanList": [
        "string"
      ]
    }
  ],
  "dailyTokensLeft": number,
  "msBeforeNextDailyToken": number
}

Field Descriptions

items - Array of product information objects

For each item:

• asin - The Amazon Standard Identification Number
• title - Product title from Amazon listing
• upc - Primary UPC currently assigned (null if not available)
• upcList - Array of all associated UPC codes (empty array if none)
• ean - Primary EAN currently assigned (null if not available)
• eanList - Array of all associated EAN codes (empty array if none)

dailyTokensLeft - Number of API tokens remaining for the day

msBeforeNextDailyToken - Milliseconds until the next token becomes available

Understanding UPC/EAN Fields

As discussed in our correspondence:

• Individual fields (upc, ean): Show the primary barcode currently assigned by the seller or Amazon
• List fields (upcList, eanList): Capture all associated barcodes including those from:
  • Listing merges
  • Product variations
  • Different market options
  • Historical barcode associations

Example Response

{
  "items": [
    {
      "asin": "B00NNUMI86",
      "title": "La Roche-Posay Lipikar AP+ Triple Repair Moisturizing Cream...",
      "upc": null,
      "upcList": [],
      "ean": null,
      "eanList": [
        "3337872418587"
      ]
    },
    {
      "asin": "B0086FFHLS",
      "title": "Philips Monster Vent TMV-3P Brush Reinforced Bristles...",
      "upc": "631102001550",
      "upcList": [
        "631102001550"
      ],
      "ean": "0631102001550",
      "eanList": [
        "0631102001550"
      ]
    }
  ],
  "dailyTokensLeft": 998,
  "msBeforeNextDailyToken": 86378782
}

Rate Limits and Quotas

Current Status: Trial Access

• Rate Limit: 30 products per minute
• Daily Limit: 1,000 products per day
• Request Counting: Requests are counted in multiples of 10
  • 1-10 ASINs = 10 tokens
  • 11-20 ASINs = 20 tokens
  • 21-30 ASINs = 30 tokens
  • etc.

Full Subscription Plan: 500 products/minute

Once trial testing is complete and the full subscription is activated:

• Rate Limit: 500 products per minute
• Daily Limit: 150,000 products per day
• Request Counting: Same token counting rules apply

Best Practices for Rate Management

1. Batch requests efficiently: Group ASINs to maximize the 100-per-request limit
2. Monitor dailyTokensLeft: Track your remaining daily quota
3. Implement exponential backoff: If rate limited, wait before retrying
4. Use msBeforeNextDailyToken: Plan request timing when approaching limits

Error Handling

HTTP Status Codes

• 200 OK - Request successful
• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Invalid or missing API key
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server-side error

Error Response Format

All error responses follow a consistent format with statusCode, error, and message fields:

{
  "statusCode": number,
  "error": "Error Type",
  "message": "Human-readable error description or array of error messages"
}

"message" may also be an array of strings for multiple validation errors.

Common Error Scenarios

1. Missing API Key

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "API key is required in request body"
}

2. Invalid API Key

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

3. Exceeded Request Size (More than 100 ASINs)

{
  "message": [
    "Maximum 100 ASINs allowed per request"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

4. Rate Limit Exceeded

{
  "statusCode": 429,
  "message": "Not enough capacity. Required: 10 products, Available: 0 products. Try again in 36 seconds",
  "error": "Too Many Requests"
}

Integration Examples

Python Example

import requests
import json

API_KEY = "<API_KEY>"  # Get your API key from https://asinscope.com/en/dashboard/asinscope-api
API_URL = "https://api.asinscope.com/circana/barcodes"

def get_barcodes(asins):
    """
    Retrieve barcode information for a list of ASINs
    
    Args:
        asins (list): List of ASIN strings (max 100)
    
    Returns:
        dict: API response with barcode data
    """
    headers = {"Content-Type": "application/json"}
    payload = {
        "key": API_KEY,
        "asins": asins
    }
    
    try:
        response = requests.post(API_URL, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        return None

# Example usage
asins = ["B0086FFHLS", "B00NNUMI86"]
result = get_barcodes(asins)

if result:
    for item in result["items"]:
        print(f"ASIN: {item['asin']}")
        print(f"UPCs: {', '.join(item['upcList']) if item['upcList'] else 'None'}")
        print(f"EANs: {', '.join(item['eanList']) if item['eanList'] else 'None'}")
        print("---")

Node.js Example

const axios = require('axios');

const API_KEY = '<API_KEY>'; // Get your API key from https://asinscope.com/en/dashboard/asinscope-api
const API_URL = 'https://api.asinscope.com/circana/barcodes';

async function getBarcodes(asins) {
    try {
        const response = await axios.post(API_URL, {
            key: API_KEY,
            asins: asins
        }, {
            headers: {
                'Content-Type': 'application/json'
            }
        });

        return response.data;
    } catch (error) {
        console.error('API request failed:', error.message);
        return null;
    }
}

// Example usage
(async () => {
    const asins = ['B0086FFHLS', 'B00NNUMI86'];
    const result = await getBarcodes(asins);

    if (result) {
        result.items.forEach(item => {
            console.log(`ASIN: ${item.asin}`);
            console.log(`UPCs: ${item.upcList.join(', ') || 'None'}`);
            console.log(`EANs: ${item.eanList.join(', ') || 'None'}`);
            console.log('---');
        });
    }
})();

Testing Recommendations

1. Start with small batches: Test with 1-10 ASINs initially
2. Verify response parsing: Ensure your code handles null values and empty arrays
3. Test error scenarios: Verify your error handling with invalid ASINs
4. Monitor performance: Track response times for different batch sizes
5. Validate data accuracy: Cross-reference a sample of results

Support

For technical and billing support or questions:

• Email: [email protected]
• Reference ticket: [## 1375 ##]

---

Last Updated: July 2025 Version: 1.0