Benefit Discovery API

Clients will make a call to Prime’s benefit discovery API and check customer’s eligibility for client benefits. The Benefit ID to be passed as part of the request will be provided by Amazon Prime team during the onboarding process.

Benefit Discovery API Request

GET https://prime-apis.amazon.com/v1/customer/benefits/{benefit-Ids}?
customerIdentifierType={customerIdentifier-Type}&customerIdentifier={customerIdentifier-Value}

Request Parameters

Parameter Name	Data type	Description
benefit-ids	List of strings	List of benefit-ids that Prime provides during the time of client onboarding based on the deal construct.
customerIdentifierType	Enum	ApayBuyerId/LWAAccessToken will be the customer identifier type that will be passed as part of the request.
customerIdentifier	opaque value (String type)	Amazon Pay Buyer Id / LWA Access Token that is retrieved as part of the call to APay/LWA API respectively. Prime will derive the other customer details from this token.

HTTP Headers

All conventional request headers for Prime APIs need to be passed for benefit discovery API, which are highlighted in detail here.

Sample API Request

The following details give a view of how a sample request has to be passed to Prime Benefits Discovery API for US marketplace.

AWSSigV4 based signed request

curl -i

-H "Authorization: AWS4-HMAC-SHA256 Credential=A*************F/20210504/us-east-1/execute-
api/aws4_request, SignedHeaders=x-amz-marketplace;host;x-amz-date,
Signature=9160882a20351d49ae497e7a37367c6165c62ec5060f7361050f43ec064410bc"

-H "x-amz-date: 20210504T201012Z"

-H "x-amz-marketplace: US"

-H "x-amz-request-id: 1234"

-H "Host: prime-apis.amazon.com"

-X GET

'https://prime-apis.amazon.com/v1/customer/benefits/PRIME_3P_PARTNER_BENEFIT
?customerIdentifierType=LWAAccessToken
&customerIdentifier=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR'

APay based signed request

curl -i

-H "Authorization: AMZN-PAY-RSASSA-PSS PublicKeyId=****, SignedHeaders=x-amz-request-id;x-amz-marketplace;x-amzn-pay-date,
Signature=XmOUMM5mNQDCjcm94ttxBxkwQ4OuGWtotCF+"

-H "x-amz-marketplace: US"

-H "x-amz-request-id: 1234"

-H "x-amz-pay-date: 20210504T201012Z"

-X GET

'https://prime-apis.amazon.com/v1/customer/benefits/PRIME_3P_PARTNER_BENEFIT
?customerIdentifierType=ApayBuyerId
&customerIdentifier=amzn1.account.xxxx'

Benefit Discovery API Response

1. Success

When a call to the Benefit discovery API is successful, clients will get one of the responses below:

HTTP status code : 200
{
    "benefits": [<benefit-id1>, <benefit-id2>...]
}

“benefits” represent the list of client benefits which customer is eligible to access. A presence of the benefit id in the response should be treated as customer’s eligibility for the ongoing 3P offer/benefit (i.e customer is a valid Prime member).

Below is the another sample success response when customer is not eligible for any client benefit - Empty list will be passed to clients in response if the customer is not eligible for the 3P offer (This shows that the customer is not a Prime customer and is not eligible for the 3P offer/benefit).

HTTP status code : 200
{
  "benefits": []
}

2. Failure

Response when there is error:

Http Status Code: <code>
Body:
{
    "error":{
        "code": "<code>",
        "message": "<message>"
    }
}

Error codes are highlighted in detail here.

API Explorer

Explore Benefit Discovery API with Swagger to send test requests and see the response.