E-Commerce Strategies
The Amazon Attribution API helps you track how external ads (Google, Facebook, Instagram) impact your Amazon sales. It uses a 14-day last-touch attribution model to connect ad clicks to purchases, offering insights into campaign performance. Key benefits include automated tag creation for thousands of ads and access to metrics like Add to Cart, Detail Page Views, and New-to-Brand Sales.
Who Can Use It?
Professional sellers enrolled in Amazon Brand Registry
Vendors and agencies
Why It Matters:
Advertisers report an 18% increase in new-to-brand sales on average.
U.S. brand owners can earn a 10% bonus on sales through the Brand Referral Bonus program.
Quick Setup Steps:
Enroll in Amazon Brand Registry.
Secure an Advertising API Developer Account.
Obtain API credentials (Client ID, Client Secret, OAuth tokens).
Create attribution tags for campaigns.
Analyze performance data via the API.
This guide explains how to set up the API, manage tags, and troubleshoot common issues to improve your marketing strategy.
Amazon Attribution API Setup: 5-Step Implementation Process
How to Use Amazon Attribution | Updated Full Training
Requirements Before Setting Up Amazon Attribution API
To use the Amazon Attribution API, you must meet three key requirements. These are non-negotiable, as Amazon enforces them to ensure that only verified brand owners can access attribution data and manage external marketing campaigns effectively.
Amazon Brand Registry Enrollment
First, you need to enroll in Amazon Brand Registry as a representative of your brand. This applies to vendors, KDP authors, and agencies acting on behalf of brands. To complete the enrollment, your brand must have an active registered trademark that Amazon uses to verify ownership.
Why is this step important? Brand Registry enrollment grants access to the Amazon Advertising Console, where you can create and manage attribution tags. It also enables the API to track "brand halo" products - items within your brand that customers purchase after clicking an attribution link, even if those products weren’t the ones being promoted. This feature provides a more comprehensive view of how your external marketing efforts influence overall brand performance on Amazon.
Once this is set up, you’ll need to confirm your development setup with an Advertising API Developer Account.
Advertising API Developer Account
To use the Attribution API, integration through the Amazon Ads API is required. If you’re not building your own tools, you can collaborate with tool providers listed in the Amazon Ads partner directory. These providers, along with agencies and integrators, use the API to retrieve attribution tags and reporting data on behalf of their advertiser clients.
API Endpoint Permissions
Each API request must include the Amazon-Advertising-Api-Scope header, which is set to your profileId obtained from /v2/profiles. Without this header, your API requests will fail.
You can verify your access in the advertising console under "Access and Settings" > "Brands." Here, you can manage brand-to-product mapping and confirm your status as a brand representative. If any products are missing from your attribution setup, you can request updates to the mapping in this section.
Currently, the API is available in the US, CA, UK, DE, FR, IT, and ES marketplaces. Ensure your account operates in one of these supported regions to proceed successfully.
Getting API Credentials and Authorization
To connect your system with Amazon's servers, you'll need to secure your API credentials. This process includes creating a security profile, generating authentication tokens, and selecting the appropriate regional endpoint for your marketplace. Here's how to get started.
Register for Amazon Advertising API Access
First, log into the Amazon Developer Console and navigate to "API Access" under "My Settings." Here, create a new security profile to generate your Client ID and Client Secret - two essential pieces of information for API requests. Make sure to save these credentials immediately from the "Web Settings" tab because the Client Secret cannot be retrieved later.
Once your security profile is ready, map it to the Amazon Attribution API. To do this, select the API name on the "API Access" page and link it to your newly created profile. If you're not building your own integration, you can explore the Amazon Ads partner directory to find tools that are already integrated with the Amazon Ads API.
Generate OAuth Tokens
Next, you'll need to generate OAuth tokens to secure your session. Using your Client ID and Client Secret, send a POST request to the Login with Amazon (LWA) endpoint at https://api.amazon.com/auth/o2/token. Be sure to use the client_credentials grant type along with your saved credentials. A successful request will return an access_token, an expires_in value (usually 3,600 seconds or one hour), and the token_type (Bearer).
Keep an eye out for common OAuth errors during this step:
invalid_client: Indicates an incorrect secret key.invalid_scope: Means the scope value is incorrect.unsupported_grant_type: Occurs if the wrong authorization grant type is used.invalid_request: Happens when the content-type isn't set toapplication/x-www-form-urlencoded.
Select the Right API Region
It's crucial to select the API region that matches the marketplace where your products are sold. Amazon Attribution only tracks traffic within the same region as the Amazon site and your audience.
When setting up in the Amazon Ads Console, align your attribution time zone with platforms like Google Analytics to maintain consistency across reports. Misaligned time zones can result in discrepancies in your data. Additionally, choosing the wrong API region may lead to "Region Mismatch Errors", where the API can't locate your brand or product ASINs in the regional database. Keep in mind, newly added ASINs might take 4–7 days for approval before they can be tracked.
Creating and Managing Attribution Tags
Attribution tags play a crucial role in tracking the performance of external campaigns on Amazon. Managing these tags is key to leveraging the API's automation features, enabling you to measure conversions from platforms like Google, Facebook, and Instagram. Here's a closer look at how to create tags manually, generate them in bulk, and handle updates effectively.
Create Tags Manually via API
To create a single attribution tag, you’ll need to make an API call with the Amazon-Advertising-Api-Scope header, including your profileId value. This ensures the API connects the tag to your campaign. Once you provide the Amazon product detail page or Store page URL, the API automatically associates the relevant products - no need for manual ASIN mapping.
One standout benefit of using the API is the ability to create macro-enabled tags for platforms like Google, Facebook, and Instagram. These tags adapt automatically to track different campaign elements, such as creatives and keywords, without requiring individual tags for each variation. This flexibility makes them ideal for campaigns with multiple components. For larger campaigns, the bulk tagging process (discussed next) offers even greater efficiency.
Generate Multiple Tags at Once
For campaigns that involve a high volume of ads, the API simplifies the process by enabling bulk tag generation. Instead of creating separate tags for every creative or ad group, you can use one macro-enabled tag per publisher and client. This approach minimizes manual effort while still capturing detailed campaign data.
When you upload a bulk file of ads, the API identifies existing ads and reuses their tags, generating new ones only for fresh entries. This prevents duplication and streamlines the process. Just ensure that every API request includes the correct profileId in the Amazon-Advertising-Api-Scope header to avoid authorization issues.
Retrieve and Update Tags
The API also makes it simple to retrieve and update attribution tags. You can programmatically fetch tags for use across external platforms, which is especially helpful for agencies managing multiple accounts. Need to update tags in bulk? Just upload a new file - the system will recognize existing tags and create new ones only when necessary.
Another time-saving feature is the "no URL re-trafficking" capability. If you update a destination URL, there’s no need to generate a new tag. This is particularly useful for dynamic campaigns that frequently switch between product pages or promotional landing pages, saving both time and effort while maintaining campaign accuracy.
Using Attribution Tags with External Platforms
Once you've secured your API credentials and created your tags, the next step is to implement them across your advertising channels. After generating tags through the API, the process involves appending the attribution tag to your destination URL. This enables Amazon to track clicks and conversions. While the implementation details may vary slightly depending on the platform, the overall approach remains consistent.
Google Ads Integration
When it comes to Google Ads, you have a few options for adding attribution tags based on the size of your campaigns:
Manual tagging: Ideal for smaller campaigns, this involves adding the attribution tag to the Final URL or Tracking Template field for each ad group.
Bulk upload method: A better choice for large-scale campaigns with thousands of keywords. Here's how it works:
Download Amazon's bulk file template.
Export your keyword data from Google Ads Report Editor.
Fill out the template and upload it to generate up to 100,000 tags at once.
Within about 10 minutes, download the processed file.
Use the "Upload" option under the "Keywords" tab in Google Ads to apply the tags.
API-based approach: This method automates tracking by using macro-enabled tags, which adapt dynamically to different keywords and creatives, reducing the need for manual updates.
After launching your campaign, wait 1–2 days to ensure clicks are being recorded in the Amazon Attribution console before increasing your ad spend. Keep in mind that a 10%-20% discrepancy in traffic data between Google Ads and Amazon Attribution is normal due to differences in how clicks are counted. If you see clicks but no conversions, double-check that the correct product ASINs are assigned to your attribution campaign. For more detailed insights, consider applying tags at the keyword level to pinpoint which search terms are driving sales.
Facebook and Instagram Tracking
The process for Facebook and Instagram is similar, with manual and bulk upload options available:
Manual setup:
Create a campaign in the Amazon Advertising console.
Choose Facebook or Instagram as the publisher and "Social" as the channel.
Enter your destination URL (e.g., an Amazon product page or Store).
Add the generated attribution tag to the Destination URL field in Facebook Ads Manager for each ad.
Bulk upload method: Best for larger campaigns:
Select "Upload a file to create in bulk" and choose Facebook or Instagram as the publisher.
Download Amazon's bulk file template.
Export your ad data from Facebook Ads Manager using the "Export & Import" function.
Transfer the required columns into Amazon's template and upload it.
Within about 10 minutes, download the processed file.
Use the "Import Ads" function in Facebook Ads Manager to apply tags to up to 8,500 ads in one go.
For better organization, adopt clear naming conventions for your tags, such as "Channel_Product_CampaignDate", to easily identify which tag corresponds to which creative. Split your ad groups into paid ads and organic posts to compare performance. Keep in mind that Amazon's Attribution dashboard may take 12 to 48 hours to fully process data, so allow time before analyzing results. Also, ensure each tag is unique to its specific ad - reusing tags across multiple creatives can lead to inaccurate click reporting.
Validate Tag Parameters
Before scaling your campaigns, double-check that your tags are properly set up. If you're using bulk uploads, the Amazon Advertising console will automatically review your file for errors and flag issues like incorrect destination URLs, missing columns, or formatting problems.
Manually test each attribution tag by clicking on it to confirm it redirects to the correct Amazon page without errors. After launching your campaign, monitor the attribution dashboard for the first couple of days to ensure metrics like clicks, detail page views, and "add to cart" actions are being recorded. If metrics aren’t showing up, verify that your destination URL leads to the correct Amazon product or Store page, and make sure you're using the appropriate template for your platform (Google, Facebook, or Instagram templates have different formatting requirements).
For easier troubleshooting, create separate ad groups for each channel or creative tactic. For example, if Facebook ads show clicks but no conversions while Google Ads are performing well, this setup makes it simpler to pinpoint and resolve platform-specific issues without affecting other campaigns.
Analyzing Performance Data with Amazon Attribution API
Once your attribution tags are live, the next step is to dive into the API's reporting features for actionable insights. Instead of navigating the Amazon Advertising console every time, you can pull data directly into your analytics tools or third-party platforms. This streamlines the process and gives you more control over how you analyze and present your data.
Pull Conversion Metrics
The API allows you to access key metrics like Add to Cart, Detail Page Views, Product Sales, and New-to-Brand Sales. These metrics help you understand how external ads are driving sales on Amazon. Additionally, the API tracks Brand Halo metrics, which show when ads for one product result in sales of other items in your brand's catalog.
Keep in mind that the API uses a 14-day, last-touch attribution model, meaning conversions are credited to the most recent click within a 14-day window.
Campaign and Keyword-Level Analysis
The API provides detailed insights into performance at both the campaign and keyword levels. For keyword-level data, campaigns must be created via the bulk upload method or the API, as manually created campaigns only offer reporting at the campaign or ad group level. Available report types include:
Campaign reports: Daily performance metrics across all campaigns.
Keyword or Creative reports: Detailed data on specific search terms or ads.
Product reports: Performance insights for individual ASINs.
This detailed reporting helps pinpoint which keywords or creatives are driving conversions rather than just clicks. For example, metrics like Detail Page Views and Add to Cart can help you spot where potential customers drop off. If a keyword generates high traffic but few conversions, the issue might be with your product page or pricing strategy.
Expect a 10–20% discrepancy between Amazon Attribution metrics and publisher data (e.g., Google Ads) due to differences in click-counting methods. It's also a good idea to wait 1–2 days after launching a campaign before diving into a detailed analysis, as this ensures complete data capture.
Automate Data Sync Processes
While manual reporting can be useful, automating data sync processes is key for efficiency. Manual downloads can slow down scaling, but automated pipelines using ELT (Extract, Load, Transform) platforms can connect the Amazon Advertising API to a centralized data warehouse like Amazon Redshift, Snowflake, or Google BigQuery. These systems keep dashboards updated by regularly syncing key tables such as PERFORMANCE_REPORT_BY_CAMPAIGN, PERFORMANCE_REPORT_BY_CREATIVE, and PRODUCT_REPORT.
For example, the design company Papier initially relied on custom ETL scripts to import data into Amazon Redshift. However, this approach caused inconsistencies and required their CTO to spend an entire workday each week troubleshooting. By switching to Fivetran's automated data connectors, they seamlessly integrated ad provider data with purchase data, enabling them to calculate metrics like customer lifetime value and ROI with minimal effort. Automated connectors also adapt to API changes, reducing the maintenance headaches that come with custom scripts.
If near real-time insights are important for your strategy, consider using Amazon Marketing Stream, which provides continuous data updates compared to the standard 48-hour API delay. Most advertisers find daily syncs sufficient for attribution analysis, but those making frequent budget adjustments may benefit from hourly or real-time updates tailored to their needs.
Fixing Common Setup Problems
Even with thorough preparation, setting up the Amazon Attribution API can sometimes hit a few snags. The most common issues usually fall into three categories: region mismatches, authentication failures, and tag validation errors. Knowing how to quickly identify and resolve these problems can save you a lot of time and ensure your attribution data stays accurate.
Region Mismatch Errors
The Amazon Attribution API operates across three main regions: North America (NA), Europe (EU), and Far East (FE). A region mismatch happens when the API endpoint, authorization URL, or token exchange URL doesn’t align with the marketplace where your brand operates. For instance, if your brand sells in the United States but you’re using an EU endpoint, you’ll likely encounter "401 Unauthorized" or "Scope" errors.
To fix this, confirm that your API, token, and authorization URLs match the region of your target marketplace. Use the NA region for the US and Canada, the EU region for markets like the UK, Germany, and France, and the FE region for countries like Japan, Australia, and Singapore. When authorizing through OAuth, use an incognito or private browser window to avoid cached credentials that might log you into the wrong regional account. Update your configuration and re-authorize if needed.
Authentication and Token Issues
Once the region mismatch is ruled out, authentication problems are the next likely culprit. These issues are often caused by application status, redirect URI mismatches, or user permissions. If your application is still in Draft status, include version=beta in the authorization URI to enable OAuth production. Another common mistake is using a redirect URI that doesn’t exactly match what’s listed in the Amazon Developer Console - even a small discrepancy, like an extra #, can trigger an MD5110 error.
Always initiate the authorization process with the primary user account. Using a secondary account will result in an SPDC8143 error. If you’ve recently updated API roles in your developer profile, you’ll need to generate a new Login with Amazon (LWA) refresh token to reflect those changes. To troubleshoot, use tools like Postman to make a simple API call. This can help you pinpoint whether the problem lies in your code or with the authentication credentials.
Tag Validation Errors
After resolving region and authentication issues, the next step is to ensure your tags meet Amazon’s requirements. Validation errors often occur during bulk uploads or when destination URLs don’t comply with Amazon’s standards. Common problems include missing required fields like campaign name, ad group name, keyword ID, or destination URL. Keep in mind that the destination URL must link directly to an Amazon product detail page or a Brand Store page - other types of URLs will fail validation.
To avoid these errors, download the latest publisher-specific template from the Amazon advertising console. Using the wrong template - for example, a Google Ads template for a Meta campaign - will lead to processing errors. For Google Ads campaigns, make sure the bulk template includes fields like campaign name, ad group name, keyword, destination URL, keyword ID, and Final URL prefix. For Facebook or Instagram campaigns, export your data from Meta Ads Manager and copy it into the Amazon Attribution bulk template. If you encounter errors during upload, review the error log provided by the advertising console, make corrections, and re-upload the file instead of trying to fix tags one by one.
Conclusion
Setting up the Amazon Attribution API gives sellers a clearer understanding of how their off-Amazon marketing efforts contribute to sales. This insight is especially important since 87% of product searches now start outside of Amazon, making it crucial to track performance across different channels.
The API simplifies what used to be time-consuming tasks. With features like macro-enabled tags and bulk upload tools, managing large-scale campaigns becomes much more efficient. This means sellers can spend less time on repetitive processes and more time analyzing performance data to refine their strategies. These efficiencies often lead to noticeable business improvements.
The results speak for themselves. For instance, a previous campaign showed substantial growth, underlining the API's value. On average, advertisers who use Attribution insights to fine-tune their non-Amazon campaigns see an 18% boost in new-to-brand sales.
Additionally, brand owners in the U.S. should consider enrolling in the Brand Referral Bonus program. This program offers an average 10% bonus on sales generated through non-Amazon marketing efforts. When paired with the API's 14-day, last-touch attribution model, it creates a strong reason to invest in external traffic. By experimenting with different creatives, landing pages, and audience segments - and using unique attribution tags - sellers can identify the strategies that deliver the best conversion rates and attract first-time buyers.
With the right setup and a focus on consistent data analysis, the Amazon Attribution API can reshape how sellers approach their marketing strategies. By leveraging these insights, sellers can make more precise decisions that drive growth.
For personalized help with integrating and optimizing Amazon's marketing tools, consider reaching out to eStore Factory for solutions tailored to your business needs.
FAQs
What data can I track with the Amazon Attribution API?
The Amazon Attribution API is a tool that lets you monitor essential metrics from your external marketing campaigns. These metrics include clicks, conversions, sales, return on ad spend (ROAS), click-through rates (CTR), add-to-cart rates, and purchase rates.
It works across various channels like search, display, video, social media, and email campaigns. By providing these insights, the API helps you evaluate how well your campaigns are performing and refine your marketing strategies for better results.
How can I resolve region mismatch and OAuth token errors?
To resolve issues during Amazon Attribution API setup, follow these steps:
Double-Check Region Settings: Make sure your API requests align with your AWS account's region. A mismatch here can cause errors.
Generate Accurate OAuth Tokens: Use the official authorization process, ensuring you select the correct region during setup.
Review Permissions and Merchant Token: Verify that your account permissions are set correctly and that your Merchant Token corresponds to the appropriate region.
If problems continue, try regenerating your OAuth tokens and ensure they are still valid and active.
When should I use macro-enabled tags vs. bulk uploads?
Use macro-enabled tags to automatically insert campaign details into URLs, making it easier to track clicks and conversions across platforms like Google and Facebook. This approach simplifies performance measurement by automating the process.
For larger campaigns with numerous keywords or ads, opt for bulk uploads. This method allows you to upload multiple tags in one go, saving time and ensuring you have access to detailed data across a wide scale.
