Migrating to Creators API from Product Advertising API

If you are an existing Product Advertising API (PA-API 5.0) customer, you need to migrate to the new Creators API. The Creators API provides the same functionality as PA-API 5.0 with enhanced authentication using OAuth 2.0 and improved credential management.

Key Differences

The main differences between Product Advertising API and Creators API are:

The primary difference is the shift from AWS Signature Version 4 authentication to OAuth 2.0, which simplifies the authentication process and enables token caching. All request and response parameters have been converted from PascalCase to lowerCamelCase.

Your existing Product Advertising API credentials (AWS Access Key and Secret Key) will not work with the Creators API. You must register for Creators API and generate new credentials.

Migration Steps

Step 1: Register for Creators API

Complete the registration process to obtain your new credentials:

1. Navigate to Associates Central or look for "CreatorsAPI" tab under the Tools hamburger menu

2. Click Create Application - Enter a name for your application

3. Click Create Credential - Copy and securely store the following values:

   • Credential ID (replaces AWS Access Key)

   • Credential Secret (replaces AWS Secret Key)

   • Version (credential version assigned based on your region)

For complete registration instructions, see Register for Creators API.

Store your Credential Secret securely. It will only be displayed once during creation. If lost, you'll need to generate a new credential.

Step 2: Choose Your Migration Path

You have two options to migrate your existing Product Advertising API applications:

Option A: Use the New SDKs (Recommended)

The Creators API provides SDKs for Node.js, Python, PHP, and Java that automatically handle OAuth 2.0 authentication and token management.

Benefits:

• Automatic token caching and renewal

• Simplified authentication flow

• Built-in error handling

• Same familiar SDK structure as PA-API 5.0

To get started with SDKs:

1. Download the SDK for your language from Using SDK

2. Replace your AWS credentials with the new Credential ID, Credential Secret, and Version

3. Update API operation names if needed (endpoints remain similar)

Example Migration (Python):

Before (PA-API 5.0):

from paapi5_python_sdk.api.default_api import DefaultApi
from paapi5_python_sdk.models.search_items_request import SearchItemsRequest

access_key = "YOUR_ACCESS_KEY"
secret_key = "YOUR_SECRET_KEY"
partner_tag = "yourtag-20"

api_instance = DefaultApi(
    access_key=access_key,
    secret_key=secret_key,
    host="webservices.amazon.com",
    region="us-east-1"
)

After (Creators API):

from creators_api.api.default_api import DefaultApi
from creators_api.models.search_items_request import SearchItemsRequest

credential_id = "YOUR_CREDENTIAL_ID"
credential_secret = "YOUR_CREDENTIAL_SECRET"
version = "YOUR_CREDENTIAL_VERSION"  # Assigned when you create credentials
partner_tag = "yourtag-20"

api_instance = DefaultApi(
    credential_id=credential_id,
    credential_secret=credential_secret,
    version=version,
    marketplace="www.amazon.com"
)

For detailed SDK setup, see Using SDK.

Option B: Update Your Direct API Calls

If you're making direct HTTP requests (using cURL, axios, requests, etc.) instead of using SDKs, you'll need to:

1. Update Authentication Flow:

   • Remove AWS Signature Version 4 signing logic

   • Implement OAuth 2.0 token retrieval

   • Add token caching and renewal logic

2. Update API Endpoints:

   • Change from https://webservices.amazon.com/paapi5/* to https://creatorsapi.amazon/catalog/v1/*

3. Update Request Headers:

   • Replace AWS signature headers with OAuth 2.0 Bearer token

   • Add credential version to Authorization header (v2.x credentials only)

   • Add marketplace header (x-marketplace)

Example Migration (cURL):

Before (PA-API 5.0):

curl -X POST https://webservices.amazon.com/paapi5/searchitems \
  -H "Content-Type: application/json" \
  -H "X-Amz-Date: 20231215T120000Z" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=..." \
  -d '{
    "Keywords": "headphones",
    "PartnerTag": "yourtag-20",
    "PartnerType": "Associates",
    "Marketplace": "www.amazon.com",
    "Resources": ["Images.Primary.Small", "ItemInfo.Title"]
  }'

After (Creators API):

First, obtain an access token (see Using cURL for the token endpoint for your credential version):

curl -X POST YOUR_TOKEN_ENDPOINT \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'YOUR_CREDENTIAL_ID:YOUR_CREDENTIAL_SECRET' | base64)" \
  -d "grant_type=client_credentials&scope=creatorsapi/default"

Then make API calls with the token:

curl -X POST https://creatorsapi.amazon/catalog/v1/searchItems \
  # For v2.x credentials, include the version in the header:
  #   -H "Authorization: Bearer YOUR_ACCESS_TOKEN, Version YOUR_CREDENTIAL_VERSION"
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-marketplace: www.amazon.com" \
  -d '{
    "keywords": "headphones",
    "partnerTag": "yourtag-20",
    "marketplace": "www.amazon.com",
    "resources": ["images.primary.small", "itemInfo.title"]
  }'

For complete cURL examples and authentication details, see Using cURL.

Step 3: Update Request Parameters

While most request parameters remain similar, note the following changes:

Step 4: Test Your Migration

1. Start with a simple GetItems or SearchItems request

2. Verify authentication and token management works correctly

3. Test all API operations your application uses

4. Implement proper error handling for new error codes

5. Monitor API rate limits and adjust throttling if needed

Access tokens are valid for 3600 seconds (1 hour). Implement token caching and renewal logic to avoid unnecessary authentication requests. SDKs handle this automatically.

For regional endpoint details including authentication token endpoints by version, see the Regional Endpoints section in Using cURL.

Common Migration Issues

If you encounter errors during migration, check the Error Codes and Messages documentation for detailed troubleshooting steps.

Additional Resources

• Common Request Headers and Parameters - Locale-specific configuration

• GetItems Operation - Retrieve product details

• SearchItems Operation - Search for products

• Error Codes and Messages - Troubleshooting errors

• API Rates - Understanding rate limits

For most developers, using the SDKs is the fastest migration path. The SDKs handle authentication, token management, and request formatting automatically, allowing you to focus on your application logic.