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):

1. Presenting the gift card to a user in-app
2. Sending the customer the gift code via SMS
3. Sending an email to the customer in your own bespoke template
4. Mailing the customer a print out of the gift card code
5. Resale to other businesses

• Introduction
• Operations
  • CreateGiftCard
    • Requests
    • Responses
  • CancelGiftCard
    • Requests
    • Responses
• Required for Resellers: ProgramID
• Example operation requests with signing details
  • Required parameters
  • Sample CreateGiftCard & CancelGiftCard Payloads
  • Known-answer V4 Signature Example
• Error Handling
  • Error Codes
• 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."

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

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.

↑ 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

Transaction Amount Limits

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

Example Request

• Required Parameters
• Reseller Use Case
• Product Use Case
• 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>
</CreateGiftCardRequest>

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>

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>

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.

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
• RefundedToPurchaser
• Expired

<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>

<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>

<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

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

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 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

Canonical Headers can look like this:

• CreateGiftCard
  JSON Headers XML Headers
• CancelGiftCard
  JSON Headers XML 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

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: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: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

• CreateGiftCard Request
  HTTP POST Request (JSON) HTTP POST Request (XML) Response (JSON) Response (XML)
• CancelGiftCard Request
  HTTP POST Request (JSON) HTTP POST Request (XML) Response (JSON) Response (XML)

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

6193dc333ef1db9edae1f17989c71ce5f1939706a79be5bb924fc2e92bc23961

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

447277eb7144a2280508b8bf047706381beb832306a5b28ee0bb69a00b9bde0d

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

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

66872de215ae457cd978a49be377caf7cd3b5ab2914785339c2b8242e3631a71

agcod-v2-gamma.amazon.com

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
    }
}

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

e0d405956e60622bee7a1161b179f7b77149cd0e43f389b0baad8ea9fc8503e0

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

4378e45d89236494f3321d3690cf624f0e3fe91d22bdf1bf0a0a6cde85fd86eb

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

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790

agcod-v2-gamma.amazon.com

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>

{
"cardInfo": {
    "cardNumber": null,
    "cardStatus": "RefundedToPurchaser",
    "expirationDate": null,
    "value": {
    "amount": 1,
    "currencyCode": "USD"
    }
},
"creationRequestId": "AwssbTSpecTest001",
"gcClaimCode": "Z7NV-LBBG39-75MU",
"gcExpirationDate": null,
"gcId": "A2GCN9BRX5QS76",
"status": "SUCCESS"
}

<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>

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

7492d98f807281c82b8abef76b75398d72bf4265c8a7ea1726b5cbee0a39be9d

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

0488271c96d8657cd9b4dade4a2e6f357b4fa1c4666d4a14f3c02cbe2d6d6a9b

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

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949

agcod-v2-gamma.amazon.com

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"
}

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

bea0ab33efe45db874d639de92b3b286353c7f2d494e20889d70f02d9574316d

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

8b9e30824d9aaf2539caa2e56519475185fda4850f138db66b7fe4c223618e11

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

48428b0d3bd97f08fbefc9d675975d7d914788ee3bc509ae27decf874f16921b

0bef87e8b01aec57fca532e79a5819fcc55d3c02cfafcdf08495ed4a26d0cd87

agcod-v2-gamma.amazon.com

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>

{
    "creationRequestId": "AwssbTSpecTest001",
    "gcId": "A2GCN9BRX5QS76",
    "status": "SUCCESS"
}        

<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

• Prepare to launch with our Test Plan Guide

Last updated: Sep 24, 2021