Account Linking API

Clients will make a call to Prime’s account linking API to link customers on Amazon side after an offer redemption. This will help linking customers 3P and Amazon accounts, once they have redeemed the offer.

Account Linking API Request

POST https://prime-apis.amazon.com/v1/customer/link-benefit/{benefit-id}?
customerIdentifierType={customerIdentifierType}&customerIdentifier={customerIdentifierValue}

Request Parameters

Parameter Name	Data type	Description
benefit-id	String	benefit-id 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.

Request Payload

Content-Type: application/json
{
    "benefitsStatus": <benefitsStatus>,
    "clientCustomerId": <clientCustomerIdentifier>,
    "linkChannel": <linkChannel>
}

Parameter Name	Data type	Description
benefitsStatus	Enum Value (Active/Inactive)	This value indicates if the client is providing benefit to the customer or not in the current state.
clientCustomerId	String Value	This value indicates the customerId on client side that Prime can use for any future communications such as notification of change of Customer state etc.
linkChannel	Enum Value (Online/Offline)	This value indicates the link channel from where the customer data was acquired by the client.

HTTP Headers

Along with the conventional request headers, additional http headers need to be passed for account linking API.

Header Name	Value
Content-Type	application/json
x-amz-pay-idempotency-key (Required only for APay based integration)	unique value - How to create

Sample API Request

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

AWS Sigv4 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"

-H "Content-Type: application/json"

-d '{"benefitsStatus":"Active","clientCustomerId":"ghkapi","linkChannel":"Online"}'

-X POST

'https://prime-apis.amazon.com/v1/customer/link-benefit/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"

-H "x-amz-pay-idempotency-key: AVLo5tI10BHgEk2jEXAMPLEKEY"

-H "Content-Type: application/json"

-d '{"benefitsStatus":"Active","clientCustomerId":"ghkapi","linkChannel":"Online"}'

-X POST

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

Account Linking API Response

1. Success

When a call to the API is successful, clients can expect below response:

HTTP status code : 200
Content-Type: application/json
{
    "message" : "success"
}

2. Failure

Response when there is error:

Http Status Code: <code>
Content-Type: application/json
Body:
{
    "error":{
        "code": "<code>",
        "message": "<message>"
    }
}

Error codes are highlighted in detail here.

API Explorer

Explore Account Linking API with Swagger to send test requests and see the response.

Appendix - Various Scenarios for calling the Account Linking API

1. Customer goes through co-branded flow and gets client offer.

Content-Type: application/json
{
    "benefitsStatus": "Active",
    "clientCustomerId": "ghkapi",
    "linkChannel": "Online"
}

2. Customer cancels their Prime membership and hence Client cancels 3P membership of a given customer.

Content-Type: application/json
{
    "benefitsStatus": "Inactive",
    "clientCustomerId": "ghkapi",
    "linkChannel": "Online"
}

3. Customer resumes their Prime membership and hence Client resumes 3P membership of a given customer.

Content-Type: application/json
{
    "benefitsStatus": "Active",
    "clientCustomerId": "ghkapi",
    "linkChannel": "Online"
}