AMC API migration: from the instance-level APIs to the Amazon Ads API

The situation

The instance-level APIs have been officially retired since August 1, 2024; a call may return a 410 error. The new AMC APIs run on the Amazon Ads API, use the OAuth 2.0 standard and a consistent base URL. Multiple users and partners can access one instance at the same time, which helps agencies with many instances.

If you only look for the error: our HTTP 410 error page explains the cause.

Migration checklist

• Create an Amazon developer account with the email address you use for the Amazon Ads console. Only the original creator of the account can complete onboarding.
• Under Login with Amazon create a security profile (name, description, privacy policy URL) and enter the allowed return URL under Web Settings.
• Apply for API access, as a partner or as a direct advertiser. According to Amazon approval takes up to one business day. Amazon issues a single client ID per company.
• Assign access to the Login with Amazon application. For most calls you need the scope advertising::campaign_management. For advertiser audiences and advertiser data upload you also need data provider access, which provides the scope advertising::audiences.
• Create the authorization URL, receive the code (single use, valid for 5 minutes according to Amazon) and exchange it with grant_type=authorization_code for access and refresh tokens.
• Adjust the bucket policy of your results bucket (see below).

S3 bucket policy for results

You get the results of an execution (POST /amc/reporting/{instanceId}/workflowExecutions) either through a pre-signed URL or from the S3 bucket you registered for the instance. For delivery to continue after the migration, the IAM policy of the bucket must allow the Amazon account 811639200769 the actions s3:PutObject and s3:PutObjectAcl on arn:aws:s3:::<bucket>/*. Amazon named May 1, 2024 as the deadline; without the permission, results were no longer delivered to the bucket.

Advertiser data upload: from ADU 1.0 to ADU 2.0

• Since the retirement on August 1, 2024 you can no longer upload or query data with ADU 1.0.
• Beforehand you need the data provider scope in addition to campaign management, and a set-up S3 bucket.
• Datasets must be recreated with POST /amc/advertiserData/{instanceId}/dataSets, with a new dataSetId (for example myfirstdatasetv2 instead of myfirstdataset).
• ADU 1.0 datasets cannot be read, modified or filled through the ADU 2.0 APIs. Only the ADU 1.0 paths edit them further.

Step by step

1. Developer account and security profile. Create an Amazon developer account, create a Login with Amazon security profile, set the return URL.
2. Apply for API access. Apply as a partner or direct advertiser and assign it to the profile.
3. Get the token. Open the authorization URL, copy the code and exchange it for access and refresh tokens.
4. Adjust the bucket policy. Allow the Amazon account s3:PutObject and s3:PutObjectAcl on your results bucket.
5. Recreate ADU datasets. Create datasets with a new dataSetId through the ADU 2.0 API and upload the data again.

Frequently asked questions