Digital Gift Cards
Introduction
The Incentives API lets you create and distribute Amazon Gift Card claim codes quickly and as your business needs them. You can buy Amazon Gift Card claim codes using a web service, and can distribute these codes to your customers in a way that suits your business. This document describes how developers can use the AGCOD API to create Amazon Gift Card claim codes. You can use these codes in many ways, including (but not limited to):
- Presenting the gift card to a user in-app
- Sending the customer the gift code via SMS
- Sending an email to the customer in your own bespoke template
- Mailing the customer a print out of the gift card code
- Resale to other businesses
- Introduction
- Operations
- Required for Resellers: ProgramID
- Example operation requests with signing details
- Error Handling
- Handling Gift Card Claim Codes
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
creationRequestIdvalue 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. |
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:
- Customer sends a
CreateGiftCardrequest to the Incentives API. - Amazon confirms sufficient funds for the request by checking the pre-payment account.
- Amazon deducts the order amount and responds with a synchronous
CreateGiftCardresponse message that containsgcClaimCode(the live gift card claim code) andgcExpirationDate(expiration date, does not apply to GCs created in the US, Canada, and Australia). - Your code must store the
creationRequestId,amount, andcurrencyCodevalues, and must handle thegcClaimCodesecurely. See Data Storage Guidelines for details.
Note: Looking for endpoints? you can find them here
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. |
Note: For the
externalReference only opaque order references without natural language content are permissible in this field. The identifier passed in the externalReference field appears with the transaction in the Incentives API Portal, in the Detailed Activity download. The following example includes an 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 |
Note: A recipient from Ireland should be able able to redeem their gift card from United Kingdom and Germany retail websites and use it for shopping on Amazon. Both these marketplaces deliver to Ireland.
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.
Note: One invocation of the
CreateGiftCard call results in the creation of only one gift card claim code (bulk creation is not supported at this time).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>
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.
Important: This operation can only be started within 15 minutes of the creation request time stamp. Once the time period has elapsed, the claim code cannot be cancelled and charges will be deducted from your prepaid balance. If you need to cancel refunds past this timeframe please reach out to our operations team. Contact Details can he found Here
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>
Required for Resellers: ProgramID
If you are integrating into the AGCOD API with the aim to resell the gift codes onto other businesses, you'll need to enter our reseller program. This is simple to do and more information can be found by contacting our account management team here. When you are up and running, you'll need to add a programID to the CreateGiftCard request as a mandatory field.
The programID is a pre-defined field which is generated when you add one of your clients to the Reseller Program in the Amazon Incentives Portal. The programID is then approved by Amazon. The programID is alphanumeric and can be up to 100 characters in length. You can use the programID field to help track client and use case transactions.
Example operation requests with signing details
This section shows example calls to CreateGiftCard and CancelGiftCard, including example signature values.
Required parameters
Note: The currency value (USD, GBP, EUR, JPY, AUD, TRY, AED) might vary based on your locale.
| 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
Note: The examples below were created using an Amazon test account. You should use your own access identifiers (
accessKeyId, partnerId, requestId)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.com.rproxy.goskope.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>
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.
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
- Prepare to launch with our Test Plan Guide
Last updated: Sep 24, 2021