searchPromotions

get

https://sellingpartnerapi-na.amazon.com/promotions/2025-12-01/promotions

Search and filter promotions based on various criteria. Returns a paginated list of promotion summaries.

Query Params

marketplaceIds

array of strings

required

length ≤ 1

The Amazon stores from which to retrieve promotions. Refer to Store Identifiers for a list of Amazon store values.

marketplaceIds*

locale

string

^[a-z]{2}_[A-Z]{2}$

Defaults to en_US

The locale from which to retrieve promotions. Formatted as an ISO 639 language code, followed by an underscore, followed by an ISO 3166-1 alpha-2 country code.

statuses

array of strings

The statuses of promotions to retrieve, formatted as a comma-delimited list.

statuses

Allowed:

asins

array of strings

length ≤ 10

The ASINs to which promotions apply, formatted as a comma-delimited list.

asins

skus

array of strings

length ≤ 10

The SKUs to which promotions apply, formatted as a comma-delimited list.

skus

promotionTypes

array of strings

The promotion types to which promotions apply, formatted as a comma-delimited list.

promotionTypes

Allowed:

startDateBefore

date-time

Promotions that start before this date are returned. Formatted in ISO 8601 format, including the timezone. For example: 1970-01-01T00:00:00-07:00.

startDateAfter

date-time

Promotions that start after this date are returned. Formatted in ISO 8601 format, including the timezone. For example: 1970-01-01T00:00:00-07:00.

endDateBefore

date-time

Promotions that end before this date are returned. Formatted in ISO 8601 format, including the timezone. For example: 1970-01-01T00:00:00-07:00.

endDateAfter

date-time

Promotions that end after this date are returned. Formatted in ISO 8601 format, including the timezone. For example: 1970-01-01T00:00:00-07:00.

updateDateAfter

date-time

Filter promotions that were last modified after this timestamp. Zoned Datetime in ISO 8601 format (e.g., 1970-01-01T00:00:00-07:00).

updateDateBefore

date-time

Filter promotions that were last modified before this timestamp. Zoned Datetime in ISO 8601 format (e.g., 1970-01-01T00:00:00-07:00).

paginationToken

string

A token that you use to retrieve the next page of results. The response includes paginationToken when the number of results exceeds the specified limit value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until paginationToken is null. Note that this operation can return empty pages.

revision

string

enum

Defaults to PUBLISHED

Specifies which promotion revision or revisions to match against when filtering. This controls which promotions are included in search results, not the shape of the response. The response always returns the published revision in the main body, with latestRevision included when the latest revision diverges.

Allowed:

limit

int64

1 to 100

Defaults to 20

The maximum number of response results per page.

includedData

array of strings

A comma-delimited list of datasets to include in the response.

includedData

Allowed:

Responses

Language

Loading…

Response

Choose an example:

application/json

200Successfully retrieved promotions.

400Request has missing or invalid parameters and cannot be parsed.

403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.

404The resource specified does not exist.

413The request size exceeded the maximum accepted size.

415The request payload is in an unsupported format.

429The frequency of requests was greater than allowed.

500An unexpected condition occurred that prevented the server from fulfilling the request.

503Temporary overloading or maintenance of the server.