Se connecter
Se connecter
Merci de votre visite. Cette page est disponible en anglais uniquement.

Amazon Product Voucher Guide

Introduction

In addition to Amazon Gift Cards, the Amazon Incentives API also offers Amazon Product Vouchers which are designed for purchasing a custom, pre-determined set of products. For example, the Health and Wellness Product Voucher can only be redeemed for eligible health-focused products.

Available Amazon Product Voucher types vary by marketplace. Please reach out to the Amazon Incentives team here to learn more about the Amazon Product Vouchers available in your marketplace.

Using our existing Digital Gift Card product, Amazon Product Vouchers can be generated as an optional parameter in the CreateGiftCard call. If you are already approved to use Amazon Product Vouchers, refer to the guide below for information on how to integrate into our service.

Operations

Your code makes signed HTTP POST requests to our endpoints to create or cancel claim codes. (We do not accept SOAP requests.) The body of your HTTP requests will contain JSON or XML. Every request to an Incentives API operation endpoint must be digitally signed using your Incentives API security credentials and the Signature Version 4 signature algorithm."

Operation Description
CreateGiftCard If sufficient funds are in the pre-payment account, deducts the amount and responds with a live gift card claim code, along with other transaction details.
CancelGiftCard Cancels a live gift card claim code if gift card has not been claimed by an Amazon customer, and has not expired.

The following table describes concepts and elements you will use when calling these endpoints:

Item Description
partnerId A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
creationRequestId A unique identifier for every CreateGiftCard request. You must generate a new value for every Create request (except for retries). (See notes below.)
CreateGiftCard response and CancelGiftCard response Each request to these endpoints returns a response your code must examine and may need to store.
Transaction A transaction is any request-response that results in the Create/Cancel of a gift card within Amazon systems.

To keep the creationRequestId globally unique, follow these requirements:

  • Generate an alphanumeric value that is unique within your system. This ID can have up to 40 alphanumeric characters.
  • Begin the creationRequestId value with your partnerID.
Example
If your partnerID is Amzn1, your creationRequestId must start with Amzn1 and any additional characters you would like in your ID (example: Amzn154321). Since the API is idempotent, if a request is sent in with a creationRequestId that was used prior, the Incentives API will return the original status that was created the first time the creationRequestId was used.

↑ Back to top

CreateGiftCard

The CreateGiftCard operation creates a live gift card claim code and deducts the amount from the pre-payment account. The response contains details you must store. The creationRequestId value uniquely identifies each creation request, along with other details like the amount, currency, etc. (in addition to the meta-data about that request, authentication info, etc.) To perform this operation, the following steps must occur:

  1. Customer sends a CreateGiftCard request to the Incentives API.
  2. Amazon confirms sufficient funds for the request by checking the pre-payment account.
  3. Amazon deducts the order amount and responds with a synchronous CreateGiftCard response message that contains gcClaimCode (the live gift card claim code) and gcExpirationDate (expiration date, does not apply to GCs created in the US, Canada, and Australia).
  4. Your code must store the creationRequestId, amount, and currencyCode values, and must handle the gcClaimCode securely. See Data Storage Guidelines for details.

Requests

Request Parameters

Parameter Name Req. Constraints Type Description
creationRequestId Yes Max 40 Characters

Prefixed with partnerID

AlphaNumeric		 String A unique identifier for every CreateGiftCard request. You must generate a new value for every Create request (except for retries). (See notes below.)
partnerID Yes Pre-defined value String A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.
value Yes Object Object that holds the currencyCode and amount parameters.
currencyCode Yes ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
amount Yes Long Card amount, in card currency.
transactionSource B&M Only Object Object that holds the sourceID, institutionID and sourceDetails parameters.
sourceID B&M Only Max 20 characters String Identifier of a transaction source entity (Example: Store Number or Store ID).
institutionID B&M Only Max 20 characters String Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
sourceDetails B&M Only Max 200 characters JSON String string to provide further information about transaction source. It must contain institutionName key with value as name of the source (e.g. Merchant Name). Other information such as source location, phone-number, etc. should be included.
programID Reseller Only Pre-defined value String You can use the programID field to help track client and use case transactions. The programID is an approved identifier provided by Amazon through a submission process. You must first submit client and use case information through your account manager.
productType PV Use Case Only Pre-defined value String required for the creation of an Amazon Product Voucher Claim Code. You must receive authorization to use this field. Available productType options can be found here.
externalReference Optional Max 100 characters String The externalReference field may be used to store a convenient mapping to assist you with tracking. For example, you might specify insurance claims, kiosks, customer cases, order Ids, reseller customer accounts, or store information within the externalReference field.

Transaction Amount Limits

Calls to CreateGiftCard must specify a currency code authorized by your account, within the range allowed for the country of issuance.

Country Currency Code Range Expiration
Australia AUD 0.01 - 5000.00 10 Years
Belgium EUR 1.00 - 5000.00 10 Years
Canada CAD 0.01 - 5000.00 N/A
Egypt EGP 1.00 - 6000.00 10 Years
France EUR 0.15 - 5000.00 10 Years
Netherlands EUR 1.00 - 5000.00 10 Years
Germany EUR 0.15 - 5000.00 10 Years
Italy EUR 0.01 - 5000.00 10 Years
Japan JPY 1.00 - 500000.00 10 Years
KSA SAR 1.00 - 5000.00 10 Years
Mexico MXN 5.00 - 5000.00 5 Years
Poland PLN 1.00 - 21000.00 10 Years
Spain EUR 0.15 - 5000.00 10 Years
Singapore SGD 0.01 - 500.00 10 Years
South Africa ZAR 1.00 - 6000.00 10 Years
Sweden SEK 1.00 - 10000.00 10 Years
Turkey TRY 1.00 - 5000.00 10 Years
United Arab Emirates AED 1.00 - 6000.00 10 Years
United Kingdom GBP 0.01 - 5000.00 10 Years
United States USD 0.01 - 2000.00 N/A

Example Request

Required Parameters
POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>
Reseller Use Case
POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
    <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</CreateGiftCardRequest>
Product Use Case
POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>25</amount>
    </value>
    <productType>bookPV</productType>
</CreateGiftCardRequest>
Optional Parameters
POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>EUR</currencyCode>
        <amount>1.00</amount>
    </value>
    <externalReference>889jj14797<externalReference>
</CreateGiftCardRequest>

This operation is idempotent, so if the Incentives API receives more than one request with the same creationRequestId, only the first request will result in the creation of a new gift card, and all subsequent responses will return the same original gift card. They will not be treated as different transactions.

Responses

Response Parameters

These items can appear in the response body of a successful call to the CreateGiftCard operation.

Parameter Name Constraints Type Description
gcClaimCode String Code a customer can use for manual redemption later. Only store securely and erase after distribution. Available from Amazon later through an identical call to CreateGiftCard (see below).
value Object Object that holds the currencyCode and amount parameters.
amount Long Card amount, in card currency.
currencyCode ISO-4217 Currency Code String A ISO-4217 currency code that specifies the currency of the card.
cardStatus String Status of card after this operation. Success value: Fulfilled
gcId String Unique gift card identifier that indicates that a call to CreateGiftCard resulted in a gcClaimCode.
creationRequestId Max 40 Characters

Prefixed with partnerID

AlphaNumeric		 String Unique identifier for this request. Starts with the Partner ID.
gcExpirationDate Not provided on cards issued in NA, CA & AU UnixDate Expiration date. Card cannot be claimed by customer after this date. (Never present for cards issued in the United States, Canada, or Australia.)
status String Outcome of this operation. Success value: SUCCESS

You can re-request an existing gcClaimCode later by calling CreateGiftCard again with the same creationRequestId, currencyCode, and amount values. The CreateGiftCard endpoint returns the current cardStatus of a claim code. Fulfilled – Claim code has been successfully created.

Example responses

Successful
<CreateGiftCardResponse>
    <gcClaimCode>W3GU-YD4NGH-88C8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>EUR</currencyCode>
            <amount>1.00</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A3B6AC387ESRIX</gcId>
    <creationRequestId> AwssbTSpecTest001</creationRequestId>
    <gcExpirationDate>Mon Jun 09 21:59:59 UTC 2025</gcExpirationDate>
    <status>SUCCESS</status>
</CreateGiftCardResponse>
RefundedToPurchaser
<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>RefundedToPurchaser</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>
Expired
<CreateGiftCardResponse>
    <gcClaimCode>G22G-WACQNJ-27S8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>JPY</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Expired</cardStatus>
    </cardInfo>
    <gcId>A2BWWZ1SGEZF2F</gcId>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

↑ Back to top

CancelGiftCard

You can cancel a gift card, as long as the gift card is not claimed by an Amazon customer. The original creationRequestId used for creating the gift card will be necessary to cancel a gift card.

To perform this operation, send a CancelGiftCard request, and the Incentives API responds with a synchronous

Requests

Request Parameters

Parameter Name Req. Constraints Type Description
creationRequestId Yes Max 40 Characters

Prefixed with partnerID

AlphaNumeric		 String A unique identifier for every CreateGiftCard request. You must generate a new value for every Create request (except for retries). (See notes below.)
partnerID Yes Pre-defined value String A unique identifier (CASE SENSITIVE, 1st letter is capitalized and the next four are lower case) provided by the Amazon team. This value appears in the payload of every AGCOD Gateway request.

Example request

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-eu-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
	<creationRequestId>AwssbTSpecTest001</creationRequestId>
	<partnerId>Awssb</partnerId>
</CancelGiftCardRequest>

Responses

Response Parameters

Parameter Name Constraints Type Description
creationRequestId Max 40 Characters

Prefixed with partnerID

AlphaNumeric		 String A unique identifier for every CreateGiftCard request. You must generate a new value for every Create request (except for retries). (See notes below.)
status String Outcome of this operation. Success value: SUCCESS

Both CreateGiftCard and CancelGiftCard operation are idempotent, so if the Incentives API receives more than one such request with the same creationRequestId, then the first request will result in the creation/cancellation of the gift card request, while all subsequent responses will do nothing, and will not be treated as a unique transaction.

Example response

<CancelGiftCardResponse>
	<creationRequestId>AwssbTSpecTest001</creationRequestId>
	<status>SUCCESS</status>
</CancelGiftCardResponse>

↑ Back to top

Required for Amazon Product Vouchers: productType

The biggest difference when working with Amazon Product Vouchers instead of Gift Cards is the inclusion of the productType field in the CreateGiftCard request.

The productType field is required for the creation of an Amazon Product Voucher Claim Code. This field will be different and unique for each Product Voucher Type. If this optional field is not passed, the Claim Code returned will be for an Amazon Gift Card. This parameter is alpha-numeric with a max length of 50 characters.

Example operation requests with signing details

This section shows example calls to CreateGiftCard and CancelGiftCard, including example signature values.

Required parameters

Header Value
HTTP Request Method POST
Canonical URI /CreateGiftCard OR /CancelGiftCard
Canonical Query String '' (empty string)
Canonical Headers (See below)
SignedHeaders content-type;host;x-amz-date;x-amz-target
Algorithm AWS4-HMAC-SHA256
Request Date 20130910T221949Z
CredentialScope 20130910/us-east-1/AGCODService/aws4_request
Service Name AGCODService
Creation Request Id AwssbTSpecTest001
Host agcod-v2-gamma.amazon.com (use applicable endpoint)
Region Name us-east-1 (use applicable endpoint)
Partner Id Awssb (use your own Partner ID)
Amount 1
Currency Code USD

Canonical Headers can look like this:

JSON Headers
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
XML Headers
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
JSON Headers
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
XML Headers
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

Sample CreateGiftCard & CancelGiftCard Payloads

HTTP POST Request (JSON)

PAYLOAD

{
    "creationRequestId": "AwssbTSpecTest001",
    "partnerId": "Awssb",
    "value": {
        "currencyCode": "USD",
        "amount": 1
    }
}

HASHED PAYLOAD

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

CANONICAL REQUEST

POST/CreateGiftCard
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

HASHED CANONICAL REQUEST

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222620Z
20130910/us-east-1/AGCODService/aws4_request
447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222620Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71
{
    "creationRequestId": "AwssbTSpecTest001",
    "partnerId": "Awssb",
    "value": {
        "currencyCode": "USD",
        "amount": 1
    }
}
HTTP POST Request (XML)

PAYLOAD

<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>

HASHED PAYLOAD

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

CANONICAL REQUEST

POST
/CreateGiftCard
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
accept;content-type;host;x-amz-date;x-amz-target
e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

HASHED CANONICAL REQUEST

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T221949Z
20130910/us-east-1/AGCODService/aws4_request
4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
<CreateGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>1.00</amount>
    </value>
</CreateGiftCardRequest>
Response (JSON)
{
"cardInfo": {
    "cardNumber": null,
    "cardStatus": "RefundedToPurchaser",
    "expirationDate": null,
    "value": {
    "amount": 1,
    "currencyCode": "USD"
    }
},
"creationRequestId": "AwssbTSpecTest001",
"gcClaimCode": "Z7NV-LBBG39-75MU",
"gcExpirationDate": null,
"gcId": "A2GCN9BRX5QS76",
"status": "SUCCESS"
}
Response (XML)
<CreateGiftCardResponse>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <cardInfo>
        <value>
            <amount>1.0</amount>
            <currencyCode>USD</currencyCode>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <status>SUCCESS</status>
    <gcId>A2GCN9BRX5QS76</gcId>
    <gcClaimCode>Z7NV-LBBG39-75MU</gcClaimCode>
</CreateGiftCardResponse>
HTTP POST Request (JSON)

PAYLOAD

{
"creationRequestId": "AwssbTSpecTest001",
"partnerId": "Awssb",
"gcId": "A2GCN9BRX5QS76"
}

HASHED PAYLOAD

7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

CANONICAL REQUEST

POST/CancelGiftCard
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222545Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard

accept;content-type;host;x-amz-date;x-amz-target
7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

HASHED CANONICAL REQUEST

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222545Z
20130910/us-east-1/AGCODService/aws4_request
0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CancelGiftCard
HTTP/1.1accept:application/jsoncontent-type:application/jsonhost:agcod-v2-gamma.amazon.comx-amz-date:20130910T222545Zx-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCardAuthorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949
{
    "creationRequestId": "AwssbTSpecTest001",
    "partnerId": "Awssb",
    "gcId": "A2GCN9BRX5QS76"
}
HTTP POST Request (XML)

PAYLOAD

<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>

HASHED PAYLOAD

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

CANONICAL REQUEST

POST
/CancelGiftCard
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
accept;content-type;host;x-amz-date;x-amz-target
bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

HASHED CANONICAL REQUEST

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

STRING TO SIGN

AWS4-HMAC-SHA256
20130910T222449Z
20130910/us-east-1/AGCODService/aws4_request
8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

DERIVED SIGNING KEY

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

SIGNATURE

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CancelGiftCard HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8
content-type:application/x-www-form-urlencoded; charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20130910T222449Z
x-amz-target:com.amazonaws.agcod.AGCODService.CancelGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20130910/us-east-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87
<CancelGiftCardRequest>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <partnerId>Awssb</partnerId>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardRequest>
Response (JSON)
{
    "creationRequestId": "AwssbTSpecTest001",
    "gcId": "A2GCN9BRX5QS76",
    "status": "SUCCESS"
}
Response (XML)
<CancelGiftCardResponse>
    <creationRequestId>AwssbTSpecTest001</creationRequestId>
    <status>SUCCESS</status>
    <gcId>A2GCN9BRX5QS76</gcId>
</CancelGiftCardResponse>

Known-answer V4 Signature Example

To assist you in the development, we have included a test example with fictitious Access Key/ Secret Keys to generate a known-answer test for different stages of the signing below. Details on how to perform each stage of the signing can be found here. Also see this diagram of the process.

Parameters used

Partner ID: Test
creationRequestId: Test001
AGCODAccess Key: fake-access-key
AGCOD Secret Key: fake-secret-key
Timestamp: 20140205T171524Z

kDate: 41b8dd5e0d1716ba90401d46b58b12d500accdd2ea9c2b22a2d275946c9d978e
kRegion: 7b47360ce7afbe1b839e0b0e55834df99979a5414bc7f846b17c9374d230d45d
kService: 68136b0a64b2d01c8934370288b46500243645e468f521503e0d1fa73526d409
kSigning: 27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

PAYLOAD

<CreateGiftCardRequest>
	<creationRequestId>Test001</creationRequestId>
	<partnerId>Test</partnerId>
	<value>
		<currencyCode>USD</currencyCode>
		<amount>10</amount>
	</value>
</CreateGiftCardRequest>

HASHED PAYLOAD

50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc

CANONICAL REQUEST

POST
/CreateGiftCard
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard

accept;content-type;host;x-amz-date;x-amz-target
50bf24a091a7463bb4a2661f93a7299c94774bc81f9fddf02af2925922b869dc`

HASHED CANONICAL REQUEST

7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

STRING TO SIGN

AWS4-HMAC-SHA256
20140205T171524Z
20140205/us-east-1/AGCODService/aws4_request
7d9f2765e4f23e85d3dce4ae264dac4f784c152f3746aff45ac7f3afd7fad649

DERIVED SIGNING KEY

27cb9f5b991c2933f5faae716e99bd50c66a45811b1424128269312bdd570dff

SIGNATURE

e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1

ENDPOINT

agcod-v2-gamma.amazon.com

SIGNED REQUEST

POST /CreateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140205T171524Z
x-amz-target:com.amazonaws.agcod.AGCODService.CreateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=fake-aws-key/20140205/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=e32110cf663ed86460621dff12bb1139afe29d015584d208df09f149fa1b69d1
<CreateGiftCardRequest>
	<creationRequestId>Test001</creationRequestId>
	<partnerId>Test</partnerId>
	<value>
		<currencyCode>USD</currencyCode>
		<amount>10</amount>
	</value>
</CreateGiftCardRequest>

↑ Back to top

Error Handling

Every response sent from the Incentives API has a status element that describes the execution status for the particular operation; there are three statusCode values: SUCCESS, FAILURE, and RESEND. See Error Handling for details.

Error Codes

We have provided mock error request IDs to simulate certain error responses with the (Create/Cancel) calls. When simulating an error response, the mock error request ID will need to be passed in to the creationRequestId field, similar to a normal request ID. The values passed in for the rest of the fields will simply be echoed in the response. To simulate a successful response, the value of F1000 can be passed in for the mock error request ID. See Mocking test examples and Error Handling for details.

↑ Back to top

Handling Gift Card Claim Codes

Gift Card Claim Codes have monetary value and need to be treated very securely. We recommend having controls in place to ensure safe and secure handling of sensitive data (gift card claim codes, security access credentials, etc.). This includes defining proper audit controls on the file systems/databases where sensitive information is stored. You should periodically change the password of your Incentives API Portal accounts that have access to secret key credentials. We recommend rotating your access keys at least once every 90 days (3 months). The Incentives API Portal lets you generate a new access key at any time. *However, AGCOD does not support automatic key rotation.

  • Claim codes should be kept confidential while in transit between Amazon and your systems.
  • Claim codes should not be stored.
  • There should be safe data handling practices in place at your premises where claim codes are accessible (either in transit or at rest).

For more details, see Guidelines for Incentives API Data Storage.

Suggested Content

Last updated: Sep 24, 2021