Amazon Ads Advanced Tools Documentation

The primary source for complete documentation on Amazon Ads advanced tools (including the Amazon Ads API and bulk operations) is the Amazon Ads advanced tools center.

This repository serves as a supplement to the official documentation, providing:

• Postman collections for API testing
• Code artifacts
• Other developer resources

Amazon Ads reporting recognizes three specific reserved attribute names. Using these names allows for specialized reporting functionality:

• brand: Represents the product or company brand name.
• product: Represents the product identifier or name.
• category: Represents the product or service category.

When migrating to the Unified API, note the following architectural shifts:

Important Lifecycle Note: You cannot create a campaign or ad group in an active state. You must create them with state: "PAUSED" and then perform a subsequent update to set the state to "ENABLED" to start delivery.

In the Unified API, instead of using different endpoints for different ad types, you use the single endpoint POST /adsApi/v1/create/ads. The specific ad type is determined by the corresponding field within creative.componentCreative in your request body.

| v4 Endpoint | Unified API Creative Field |
|-------------|------------------------------|
| `/sb/v4/ads/autoCollection` | `creative.componentCreative.autoCollectionSettings` |
| `/sb/v4/ads/manualCollection` | `creative.componentCreative.manualCollectionSettings` |
| `/sb/v4/ads/productCollection` | `creative.componentCreative.productCollectionSettings` |
| `/sb/v4/ads/storeSpotlight` | `creative.componentCreative.storeSpotlightSettings` |
| `/sb/v4/ads/video` | `creative.componentCreative.productVideoSettings` |
| `/sb/v4/ads/brandVideo` | `creative.componentCreative.productVideoSettings` (with STORE landing page) |

To distinguish between ASIN exact and expanded targeting in the Unified API, use the matchType within the productTarget object:

• ASIN exact (精准): targetType: "PRODUCT" + productTarget.matchType: "PRODUCT_EXACT" (corresponds to SP v3 ASIN_SAME_AS).
• ASIN expanded (扩展): targetType: "PRODUCT" + productTarget.matchType: "PRODUCT_SIMILAR" (corresponds to SP v3 ASIN_EXPANDED_FROM).
• Category targeting: targetType: "PRODUCT_CATEGORY".

When migrating targeting, map your SP v3 target types to the following Unified API targetType values:

Note on Product ID Types: The Unified API supports both ASIN and SKU via the productIdType field.

The SBC ad format follows a specific hierarchy. A Campaign must be created first, followed by an Ad Group, which contains Ads and Targets.

Hierarchy Structure:

• Campaign (adProduct: SPONSORED_BRANDS, costType: CPC)
  • Ad Group
    • Ad (Uses either autoCollectionSettings or manualCollectionSettings)
    • Targets (Can be keyword, product, productCategory, or theme)

Campaign (costType: CPC, adProduct: SPONSORED_BRANDS)
  └── Ad Group
       ├── Ad (creative: autoCollectionSettings OR manualCollectionSettings)
       └── Targets (keyword, product, productCategory, theme)

All create, update, and delete endpoints in the Unified API return a Multi-Status response pattern. This structure separates successful operations from errors, allowing for partial success in batch requests. You must check both the success and error arrays in the JSON response to determine the outcome of each item in your request.

{
  "success": [
    { "index": 0, "campaign": { "campaignId": "123456789", ... } }
  ],
  "error": [
    { "index": 1, "errors": [{ "code": "FIELD_VALUE_IS_INVALID", "message": "..." }] }
  ]
}

The ads-api-migration-assistant agent uses a two-layer knowledge system to answer developer queries:

1. Primary Layer (SKILL.md files): The agent first loads the specific skill files as context. These contain high-level migration guides, field mappings, and code examples.
2. Fallback Layer (api-specs/*.json): If the skill files do not contain enough detail, the agent automatically searches the full OpenAPI schemas (located in the api-specs/ directory) to find precise field types, enum values, or schema details.

This allows the agent to provide both strategic migration advice and precise technical implementation details.