Thank you for your visit. This page is only available in English at this time.

Create claim codes

Please make sure to set up your Amazon Incentives API account before starting integration. Create Incentives API account.


The Incentives API lets you create and distribute Amazon Gift Card claim codes quickly through the internet.

You can buy Amazon Gift Card claim codes using a web service, and can distribute these codes to your customers. 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:

  • Inserting claim codes into electronic gift cards
  • Group gifting
  • Real time redemption of claim codes in loyalty programs (i.e. points programs).

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.
GetAvailableFunds Returns balance of pre-payment account.

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.

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.

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

Example response

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

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.

Required for Resellers: ProgramID

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. Approved submissions receive a reference number called a programID that your code will include in each transaction call to the API. The programID is alphanumeric and can be up to 100 characters in length.

The below example message highlights the modifications needed to accommodate the programID field.

<CreateGiftCardRequest>
  <creationRequestId>AwssbTSpecTest001</creationRequestId>
  <partnerId>Awssb</partnerId>
  <value>
    <currencyCode>EUR</currencyCode>
    <amount>1.00</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</CreateGiftCardRequest>

Required for Product Vouchers: productType

The productType field is required for the creation of an Amazon Product Voucher Claim Code. You must receive authorization to use this field. 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 attribute is alpha-numeric with a max length of 50 characters.

Available productType options can be found in this spreadsheet.

<CreateGiftCardRequest>
  <creationRequestId>Humana_2018072650</creationRequestId>
  <partnerId>Humana</partnerId>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>25</amount>
  </value>
  <b>&lt;productType>bookPV</productType></b>
</CreateGiftCardRequest>

Additional requirements at Brick and Mortar locations

Every call to CreateGiftCard that occurs at a brick-and-mortar location must include details of the location where the transaction occurred. Requests to these endpoints can include a transactionSource object that describes the physical location of the event.

Field in transactionSource Description
sourceId Identifier of a transaction source entity (Example: Store Number or Store ID).
institutionId Identifier of a parent entity of a transaction source (Example: Merchant Id). If parent entity does not exist, copy sourceId.
sourceDetails 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.
institutionParentCompany Name of the parent company for instituitionName. If there is no parent company, institutionName should be repeated.

There are two options for sending store location data to Amazon:

  1. Long form – partner provides specific store location data for each transaction (must include sourceId, institutionId and sourceDetails)
  2. Short form – partner provides only the sourceId and institutionId in the API request. A separate location mapping file must be sent that maps these identifiers to physical locations. See Location Mapping file instructions in this spreadsheet.

Sample "long form" payload for transaction source in both XML and JSON format is shown below. Note that sourceDetails must be formatted as a JSON blob. In the JSON example, the JSON blob uses the backslash to escape quotation marks.

Long form example of XML body (note that the sourceDetails value must be formatted as a JSON blob):

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Short form example of XML body:

<CreateGiftCardRequest>
    <creationRequestId>AppptsDCreat1221</creationRequestId>
    <partnerId>Apppt</partnerId>
    <transactionSource>
        <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
    </transactionSource>
</CreateGiftCardRequest>

Short form example of JSON body:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceId": "59990492",
    "institutionId": "99990492"
  }
}

Long form example of JSON body:

{
  "creationRequestId": "Myid1RequestId",
  "partnerId": "Myid1",
  "value": {
    "currencyCode": "USD",
    "amount": 30
  },
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

Optional: external reference attribute

You can use the externalReference field to pass your own reference identifier as a string when making claim code requests (up to 100 Unicode characters). 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.

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.

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>

Response fields

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

Item Description
gcClaimCode 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).
amount Card amount, in card currency.
currencyCode A ISO-4217 currency code that specifies the currency of the card.
cardStatus Status of card after this operation. Success value: Fulfilled
gcId Unique gift card identifier that indicates that a call to CreateGiftCard resulted in a gcClaimCode.
creationRequestId Unique identifier for this request. Starts with the Partner ID.
gcExpirationDate Expiration date. Card cannot be claimed by customer after this date. (Never present for cards issued in the United States, Canada, or Australia.)
status 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.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Fulfilled</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

RefundedToPurchaser – Claim code was successfully cancelled and refunded on prior call to CancelGiftCard.

<CreateGiftCardResponse>
    <gcClaimCode>KR2G-W4CQNJ-WQS8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>USD</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>RefundedToPurchaser</cardStatus>
    </cardInfo>
    <gcId>A2BN7W2SGEZFFE</gcId>
    <creationRequestId>Awssb-ABR-09</creationRequestId>
    <status>SUCCESS</status>
</CreateGiftCardResponse>

Expired – Claim code was not claimed prior to the expiration date.

<CreateGiftCardResponse>
    <gcClaimCode>G22G-WACQNJ-27S8</gcClaimCode>
    <cardInfo>
        <value>
            <currencyCode>JPY</currencyCode>
            <amount>1.0</amount>
        </value>
        <cardStatus>Expired</cardStatus>
    </cardInfo>
    <gcId>A2BWWZ1SGEZF2F</gcId>
    <creationRequestId>Awssb-ABR-10</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.

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

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

Example response

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

GetAvailableFunds

This operation returns the amount of funds currently available in your Amazon Incentives account. It provides an alternative to logging into the Incentives API Portal to view available funds. You can use this operation to monitor your balance and raise alerts.

Request Parameter Description
partnerId A case sensitive unique identifier assigned to your account by Amazon
Response Parameter Description
amount The value of funds currently available in your prepay/postpay account. Note: the Sandbox environment will always return a zero value.
currencyCode The ISO-4217 currency code
status The status of the request. In normal operation, this value is success.
timestamp Date returned in UTC yyyy-MM-dd HH:mm:ss

Sample request

POST
/GetAvailableFunds HTTP/1.1

accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.GetAvailableFunds
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657

{"partnerId": "Aptuk"}

Sample response

{
"availableFunds":{
"amount":10.0,
"currencyCode":"USD"
},
"status":"SUCCESS",
"timestamp":20170915T200959Z
}

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

    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

or like this:

    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

CreateGiftCard

Sample CreateGiftCard HTTP POST request with JSON payload

PAYLOAD

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

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 /CjsonreateGiftCard 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.00}}

Sample CreateGiftCard HTTP POST request with XML payload

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>

Sample CreateGiftCard response

JSON response body

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

XML response body

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

CancelGiftCard

Sample CancelGiftCard HTTP POST request with JSON payload

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.1
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
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=7c27005003a87310297d588749efdd5203deabed8610fafe8ba8e82f0e759949
{
  "creationRequestId": "AwssbTSpecTest001",
  "partnerId": "Awssb",
  "gcId": "A2GCN9BRX5QS76"
}

Sample CancelGiftCard HTTP POST request with XML payload

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>

Sample CancelGiftCard response

JSON response body

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

XML response body

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

Required parameters

  • HTTP Request Method=POST
  • Canonical URI=/CancelGiftCard
  • Canonical Query String='' (empty string)
  • Canonical 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
    

    or

       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
    
  • SignedHeaders=content-type;host;x-amz-date;x-amz-target
  • Algorithm=AWS4-HMAC-SHA256
  • Request Date=20130910T222449Z
  • 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)

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

kSecret: 4157533466616b652d7365637265742d6b6579
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 180 days (6 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.

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
Australia AUD $ 1 - $ 2 000
Canada CAD $ 0,01 - $ 5 000
France EUR € 0,01 - € 5 000
Netherlands EUR € 1 - € 5 000
Germany EUR € 0,01 - € 5 000
Italy EUR € 0,01 - € 5 000
Japan JPY ¥ 1 - ¥ 500 000
Mexico MXN $5 - $ 5 000
Spain EUR € 0,01 - € 5 000
Turkey TRY ₺ 1 - ₺ 5 000
United Arab Emirates AED 1 AED - 6 000 AED
United Kingdom GBP £ 0.01 - £ 5 000
United States USD $ 0.01 - $ 2 000

Create Digital Codes Test Script

To verify your integration with the API, run through the following tests.

Test Description Test Case Detail Expected Result
1. Creating a claim code Initiate a CreateGiftCard request for a valid amount such as 100 units of your currency and handle the response received. You should receive a SUCCESS response. Your system should handle the SUCCESS response properly, based on the requirements.
2. Cancelling a claim code Initiate a CancelGiftCard request for the creationRequestId created in test (1). You should receive a SUCCESS response. Your system should handle the SUCCESS response properly, based on the requirements.
3. Idempotency Initiate a CreateGiftCard request for 1000 units of your currency and handle the response received. Send another CreateGiftCard request with the same creationRequestId. You should receive a SUCCESS response and the same gcId and claimCode.

Last updated: May 18, 2021