DEV Community

Cover image for Amazon PA-API v5 deprecates April 30, 2026 and retires May 15. Here is what changes at the auth layer.
Nate
Nate

Posted on • Originally published at paapiplugin.com

Amazon PA-API v5 deprecates April 30, 2026 and retires May 15. Here is what changes at the auth layer.

#wordpress #webdev #amazon #tutorial

If you maintain anything that calls Amazon's Product Advertising API v5 (PA-API), this affects you. Amazon's published timeline has two dates: April 30, 2026 is the deprecation date and Amazon's recommended migration cutoff, and May 15, 2026 is when the endpoint itself is retired. Amazon explicitly recommends completing migration by April 30 to avoid service disruption. The replacement is the Creators API, and the migration is not a config change. It is a different authentication scheme, a different request shape, and a different token lifecycle.

This post is a quick technical orientation: what changes at the auth layer, what changes in the request payload, and how to test your migration before the cutoff. Useful whether you are maintaining a WordPress plugin, a custom Node integration, or a one-off affiliate scraper.

What changes at the auth layer

PA-API v5 uses AWS Signature Version 4. You sign every request with your AWS Access Key ID and Secret Access Key, derive a signing key from your secret + date + region + service, and attach an Authorization header that looks like this:

Authorization: AWS4-HMAC-SHA256 Credential=AKIA.../20260413/us-east-1/ProductAdvertisingAPI/aws4_request,
               SignedHeaders=content-encoding;content-type;host;x-amz-date;x-amz-target,
               Signature=...
Enter fullscreen mode Exit fullscreen mode

You also send X-Amz-Date, X-Amz-Target, and Content-Encoding: amz-1.0. The signing process is finicky: every header has to be canonicalized, the body has to be hashed, and the timestamp window is tight (15 minutes). If you have ever debugged Sig V4, you know.

The Creators API replaces all of that with OAuth 2.0 client credentials. You register your application in the Amazon Associates portal, get a Client ID and Client Secret, and exchange them for a bearer access token:

# The URL depends on your credential Version (Amazon shows this on your credential page).

# v2.x credentials (Cognito-fronted OAuth):
POST https://creatorsapi.auth.us-east-1.amazoncognito.com/oauth2/token   # v2.1 (NA)
POST https://creatorsapi.auth.eu-south-2.amazoncognito.com/oauth2/token  # v2.2 (EU)
POST https://creatorsapi.auth.us-west-2.amazoncognito.com/oauth2/token   # v2.3 (FE)

# v3.x credentials (Login with Amazon path):
POST https://api.amazon.com/auth/o2/token      # v3.1 (NA)
POST https://api.amazon.co.uk/auth/o2/token    # v3.2 (EU)
POST https://api.amazon.co.jp/auth/o2/token    # v3.3 (FE)

# Common headers and body for v2.x (Cognito):
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials&scope=creatorsapi/default
Enter fullscreen mode Exit fullscreen mode

Amazon issues credentials with a Version (2.1, 2.2, 2.3 for the Cognito path; 3.1, 3.2, 3.3 for the LwA path). The token endpoint, scope format, and Authorization header shape all depend on which Version you hold. For v3.x credentials, the scope is creatorsapi::default (double colon) and the product Authorization header is Bearer <access_token> without the Version suffix.

Amazon documents both forms as valid for v2.x credentials: you can send client_id and client_secret in the body, or use the Authorization: Basic <base64(id:secret)> header shown above. The Basic header form is what Amazon shows in the migration guide example, so that is the one I would default to.

You get back a JSON envelope:

{
  "access_token": "<opaque-string>",
  "token_type": "bearer",
  "expires_in": <seconds>
}
Enter fullscreen mode Exit fullscreen mode

For v2.x credentials, every product request carries Authorization: Bearer <access_token>, Version <credential_version> plus an x-marketplace header naming your storefront (for example www.amazon.com). The Version suffix is how Amazon ties the token to your Associates credential version - do not drop it. For v3.x credentials (Login with Amazon path), the header is just Authorization: Bearer <access_token> without the Version suffix.

Practical implications:

  • No more derived signing keys, no more canonical request strings, no more 15-minute timestamp window.
  • The token is opaque to you. You do not roll your own crypto.
  • You do need a token cache layer. In WordPress, any shared persistent store works: set_transient with a TTL under expires_in, or update_option with a companion expiry timestamp that your code checks before each request. The must-have is "shared across PHP-FPM workers," not "auto-expiring" - you will check expiry yourself before every request anyway.
  • Pre-emptive refresh works well here: keep an expires_at timestamp next to your cached token and refresh before you hit it (a 60-second buffer is plenty). Refresh-on-401 also works as a fallback if a request races with expiry, but pre-emptive refresh keeps the common path to a single HTTP call.

What changes in the request payload

The request body shape stays largely the same, but every parameter name has been converted from PascalCase to lowerCamelCase. SearchItems now takes keywords, searchIndex, itemCount, resources[]. GetItems takes itemIds[]. Both also take partnerTag (lowercase p) and marketplace. If you are porting existing PA-API v5 code, a find-and-replace across parameter names is mandatory - Amazon will reject the PascalCase forms. The big differences beyond the casing:

  • Endpoint host changes. PA-API v5 is webservices.amazon.com (regional). Creators API uses a single global endpoint: https://creatorsapi.amazon/catalog/v1/. Unlike PA-API v5 (which had regional hosts like webservices.amazon.com baked into Sig V4 signing), Creators API is region-agnostic at the host level - regional routing is driven by your x-marketplace header and credential Version. Note the .amazon TLD - that is Amazon's own top-level domain, not a typo.
  • No regional signing. Sig V4 had us-east-1, eu-west-1, etc. baked into the signing key. The Creators API decouples auth from marketplace - you specify the marketplace in the request body and the x-marketplace header, not in the auth itself.
  • Per-request item caps you will hit. SearchItems returns up to 10 items per call (itemCount max 10). GetItems accepts up to 10 itemIds per call. If you were batching more than 10 ASINs per GetItems request on PA-API v5, you will need to split. The resources[] field-selection array length is not numerically capped in Amazon's public docs - add what you need.
  • Throttling behavior may shift. Check the Creators API rate-limit docs before assuming PA-API v5 limits carry over one-for-one.

How to test your migration before the cutoff

Three steps that do not require burning your production setup:

  1. Apply for Creators API credentials now. Prerequisites you may hit: you need final-accepted Amazon Associates status, and Amazon requires at least 10 qualifying referred sales in the last 30 days to access Creators API. Only the primary account owner can register. If you clear those gates, go to Associates Central -> Tools -> Creators API, apply, and wait for approval. This unblocks everything else.
  2. Run both auth methods side-by-side on a staging site. Keep your existing PA-API v5 wiring intact. Add a feature flag or a config toggle that routes a copy of each search to the Creators API endpoint with the bearer token. Compare the response shapes for the same query. You will catch any payload differences (mostly minor field naming) without touching production.
  3. Migrate one site, then the rest. Pick your lowest-traffic affiliate site, flip it to Creators API, run for a week, watch error rates and CTR. If clean, roll the rest. Do not flip everything on April 29.

Common gotchas

A few things that catch people:

  • Token caching across processes. If you are running PHP-FPM with multiple workers, each worker can request its own token if you cache in process memory. Use a shared cache (WordPress options, transients, Redis, memcached) instead.
  • Clock skew on the staging server. OAuth tokens are timestamped. If your server clock is off by more than a few minutes, token validation can fail. ntpdate is your friend.
  • Marketplace defaults. Make sure your migration code passes the same marketplace as your old code, both in the request body AND the x-marketplace header. Default endpoint behavior is not always identical.
  • Throttling under load. The new API may enforce different rate-limit shapes. If you were already cache-walking PA-API v5 (search 30 min, product 1 hr is a common pattern), keep that behavior - the cache layer insulates you from whatever the new limits turn out to be.

After April 30

April 30 is Amazon's recommended migration deadline and the official deprecation date - documentation stops being maintained and Amazon's guidance is to be off v5 by then. The endpoint itself keeps accepting requests until it retires on May 15, so you have a two-week tail, but there is no documented grace period on the retirement itself. Plugins and integrations that still send AWS Sig V4 requests after May 15 will start getting auth failures. The path forward is straightforward, but the window is fixed and the application-and-test cycle takes more than zero days. (These dates come from Amazon's April 2026 notification to existing PA-API customers. Amazon's public Creators API migration guide does not currently publish an endpoint retirement date, so if a reader checks that and finds nothing, this is why.)

If you do nothing else this week: apply for Creators API credentials. Everything downstream depends on having them in hand.

Footnote: I maintain Product Search for Amazon, a WordPress plugin that supports both PA-API v5 and the Creators API during the migration window. If you are running WordPress and want a reference implementation of the dual-auth pattern, the source is on the WordPress.org plugin directory. Not the point of this post - just disclosing relevant context.

Top comments (0)