This is a multi-page printable view. Click here to print.

API Library

Table of contents

1. ECHO
2. INQUIRE
3. REDEEM
4. REVERSE

This section includes the four (4) AIR MILES Cash API endpoints listed below. Each page offers a brief summary of the API endpoint in question, common use-case scenarios, and sample request/response messages with response codes.

API endpoints

ECHO

Used to test and confirm that the real-time checkout platform is up and ready to process requests.

INQUIRE

Used to retrieve account balances and AIR MILES Cash offer information.

REDEEM

Used to redeem AIR MILES Cash Miles from a Collector’s account to be used towards their purchase.

REVERSE

Used to refund (aka reverse) an AM Cash Miles redemption.

Idempotent requests

All the API calls shown above (excluding ECHO & INQUIRY) support idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to redeem miles from a Collector does not receive a response due to a network connection error, you can retry the request with the same idempotency key to guarantee that additional miles aren’t accidentally redeemed from the Collector’s account.

Note

To perform an idempotent request, you need to provide an additional Idempotency-Key: <key> header to the request.

What is an “Idempotency Key”

An “Idempotency Key” is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

WARNING

If you omit the header in the request, then the content of the transaction itself will be used to detect if it’s a duplicate. This requires that you send the exact same request as before, including an identical timestamp. This process however does not guarantee idempotency and should only be used as a last resort.

Sample header with Idempotency

curl -X POST https://cert.airmilesapis.ca/checkout/amcash/echo \
    -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000' \
    -d '{

Handling request/response messages

As described above, the RESTful specification defines a transaction as a pair of request and response messages that are used for information interchange.

Note

Mandatory parameters will be marked with an asterisk (*) in the subsequent pages.

Message Type Description

Request All mandatory parameters MUST be included in each API call.
All other parameters are optional, unless stated otherwise.

Response Indicates which parameters/elements are always returned.
The “Response” Content-Type is specified in the Header (e.g., application/json.
A “Response” resulting in an ‘error condition’ will include an accompanying responseCode.
Partners are expected to verify and handle each Response Code as necessary.
All response values are NOT not case-sensitive.
Data elements that contain null or ‘empty’ values are automatically excluded from the response body.
The ‘POS’ terminal may use the response elements to display/print information for the customer.

Message Type	Description
Request	All mandatory parameters MUST be included in each API call. All other parameters are optional, unless stated otherwise.
Response	Indicates which parameters/elements are always returned. The “Response” `Content-Type` is specified in the Header (e.g., `application/json`. A “Response” resulting in an ‘error condition’ will include an accompanying `responseCode`. Partners are expected to verify and handle each Response Code as necessary. All response values are NOT not case-sensitive. Data elements that contain `null` or ‘empty’ values are automatically excluded from the response body. The ‘POS’ terminal may use the response elements to display/print information for the customer.

Handling request timeouts

A request timeout has likely occurred if either of the following are true.

You received a Response Code of 0008
You didn’t receive any response at all

Upon experiencing a request timeout, your POS terminal should immediately attempt to retry the same request. The reattempted request MUST be identical to the initial request.

Important

If the new request does not match exactly with the initial request, the system will not recognize it as a “retry” request, but will register it as a brand new transaction. If the request continues to timeout and/or fail, an error message should be displayed to the cashier, as suggested in the section Displaying the reversal result.

If at any time, AIR MILES real-time encounters an internal problem or network error while trying to return a “redemption response” to the partner, the redemption request will be automatically cancelled. Thereby ensuring the customer is not charged for a redemption that could not be redeemed.

Note

If the retry succeeds, then the transaction must be included in the reconciliation report sent to AIR MILES.
If the retry fails, the transaction must NOT be included in the reconciliation report, as no Miles were processed for the transaction.

For all other Response codes; when a particular code is received (e.g., 0002, 0096, etc.), the appropriate message should be displayed to the cashier, as shown in POS Workflows > Redemption.

Status/response codes

Status Code	Response Code	Display Message	Description
`200`	`0000`	Approved	The transaction was successful. The POS terminal AND receipt should display the appropriate information.
`202`	`0001`	Approved - balance suppressed	The transaction was successful, however the Collector opted to not view their rewards balances. The printed receipt MUST NOT show the Collector’s ‘Cash’/‘Dream’ balances, or the available “AM Cash” that can be redeemed.
`401`	`0002`	Collector account inactive	The Collector account is not active. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center.
`408`	`0008`	Transaction timeout	The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`403`	`0009`	Card not swiped or scanned	Redemption offers will not be sent if the Collector Card is not presented. The Collector Card is physically required to perform instant cash redemptions. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`401`	`0025`	Invalid Collector number	The Collector number is invalid. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`202`	`0051`	Insufficient reward miles	The Collector has not earned enough in their “AIR MILES Cash” balance for the requested redemption amount. Please ask the Collector to go to airmiles.ca and check their redemption/earning history.
`400`	`0057`	Invalid redemption confirmation number	The `redemptionConfirmationNumber` submitted is invalid. Please resubmit the request with the correct Redemption Confirmation Number.
`202`	`0065`	Exceeded daily redemption limit	The Collector has exceeded the daily redemption limit. The Collector’s account has exceeded the maximum daily redemption amount. Please ask the Collector to wait until the following day to redeem more Cash miles.
`202`	`0066`	Insufficient basket size	The Collector’s basket size is too small to make a redemption. The purchase amount is not enough to make a redemption. Ask the customer if they wish to add more items to their basket in order to make an AM Cash redemption.
`408`	`0067`	Offer is temporarily unavailable	The offer being requested is temporarily unavailable. Please advise the Collector to try redeeming this offer at a later time.
`409`	`0080`	Reversal window expired	The reversal window for the redemption has expired; meaning a reversal can no longer be submitted for this transaction. This usually happens when a reversal is attempted after 3:00 AM the day after the original transaction. Any reversals that are attempted past the 3:00 AM time-frame should be refunded to the customer via in-store credit or gift card. Please DO NOT RETURN CASH to the customer.
`503`	`0092`	Scheduled outage	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	`0096`	Server error or no response	An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`null`	`null`	Missing or invalid “bearer” token	No valid “Bearer Token” present. Please generate a valid “Bearer” Token and submit to continue."

1 - ECHO

Used to test and confirm that the real-time checkout platform is up and ready to process requests.

POST /checkout/amcash/echo

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

This test ensures there are no known connectivity issues between AIR MILES and our partners. The ECHO call functions similarly to a standard ‘ping’ request, determining if a client or host is online and accessible. To receive a “Bearer Token” and authorize your request, use the client_id/client_secret provided to you by AIR MILES.

Note

It is highly recommended that all Partners use the ECHO test upon starting their integration, to ensure both systems can communicate properly. Also at the partner’s discretion, we recommend performing periodic ECHO tests at regular intervals to be notified immediately in the case of any unforeseen outages.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/echo \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "deviceId": "001",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "000012345678",
  "vendorId": "100087"
}'

Header parameters

Parameter	Description
Authorization	Token from authentication. Example: `Bearer eyJhbGciOiJSUzI1NiIsI…`
Content-Type	Default value: `application/json`
cache-control	Default value: `no-cache`

Query parameters

Parameter	Description
none	none

Body parameters

* Required field

Parameter	Description
`deviceId`*	ID number used to identify the POS terminal currently in use. Example: `"001"`
`sponsorCode`*	Alpha-numeric value used to identify the Partner. Example: `"LOY1"` To be provided by AIR MILES
`storeId`*	Alpha-numeric value used to identify the Partner’s location. Example: `"0001"` To be provided by Partner
`traceId`*	Partner’s unique transaction tracking number. Example: `"000012345678"` This value can be recycled after a year To be provided by Partner
`vendorId`*	Number used to identify the Partner and for downstream financial payments. Example: `"555555"` To be provided by AIR MILES

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
  "deviceId": "001",
  "message": "Approved",
  "responseCode": "0000",
  "sponsorCode": "1234",
  "storeId": "0001",
  "traceId": "000012345678",
  "transDateTime": "2019-01-30T03:59:03",
  "vendorId": "1234567890"
}

Response model

Includes all “Request” parameters listed above, plus the additional ones below.

Parameter	Description
`message`	Text description of the response code. Example: `"Approved"`
`responseCode`	Number indicating the result of the transaction. Example: `"0000"` `0000`: Request processed successfully `0001`: Approved (balance suppressed). `0002`: Collector profile inactive. `0005`: Unable to redeem (balance suppressed). `0006`: Unable to redeem. `0008`: Transaction timed-out, request needs to be retried. `0009`: Card not swiped or scanned. `0025`: Invalid collector number. `0035`: Invalid request parameter. `0051`: Insufficient AIR MILES Cash Miles. `0057`: Invalid redemption confirmation number. `0065`: Exceeded daily redemption limit. `0066`: Insufficient basket size. `0067`: Offer is temporarily unavailable. `0080`: Reversal window expired. `0092`: Scheduled outage. `0096`: System error.
`transDateTime`	Date and time when the response was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`

Note

Responses will always include the responseCode and message fields. If the original request was successful, the response will include the same parameters sent in the request body.

Status/Response codes

Status Code	Response Code	Display Message	Description
`200`	`0000`	Approved	The transaction was successful. The POS terminal AND receipt should display the appropriate information.
`408`	`0008`	Transaction timeout	The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`503`	`0092`	Scheduled outage	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	`0096`	Server error or no response	An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
none	none	Missing or invalid Bearer token	No valid Bearer token present. Please generate a valid Bearer token and submit to continue."

2 - INQUIRE

Used to retrieve account balances and AIR MILES Cash offer information.

POST /checkout/amcash/inquire

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Used to retrieve account balances and AIR MILES Cash offer information. Once a Partner receives a response, the POS terminal can acquire the reward miles Cash/Dream balances.

Note

These balances SHOULD be shown on the Collector’s sales-receipt, but SHOULD NOT be displayed on the POS terminal. The receipt and/or POS terminal may also display the Collector’s remaining daily availableCashBalance and availableDollarAmount taken from the response.

See the Response Model below for more information - or, for additional details on Response Messages and POS System Integration, please refer to POS Terminal Workflows.

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/inquire \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "acquirerId": "100000",
  "cardEntryMode": "SWIPE",
  "collectorNumber": "84095202006",
  "dateTime": "1972-07-16T13:32:00+0400",
  "deviceId": "001",
  "instantMessage": "en-CA",
  "postTaxBasketAmount": "16.12",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Parameter	Description
Authorization	Token from authentication. Example: `Bearer eyJhbGciOiJSUzI1NiIsI…`
Content-Type	Default value: `application/json`
cache-control	Default value: `no-cache`

Query parameters

Parameter	Description
none	none

Body parameters

* Required field

Parameter	Description
`acquirerId`*	The acquirer ID identifies the party that sends the request, usually this is the partner. Example: `"100000"` To be provided by AIR MILES
`cardEntryMode`*	The method that was used to enter the AIR MILES account number. Example: `"SWIPE"` `SWIPE` The card's magstripe was swiped. `SCAN` The card's barcode is scanned at the POS using an I/R reader. `PREREGISTERED` The information is passed automatically as with an online-checkout or mobile app purchase. `MANUAL` The card number is manually entered into the POS system. WARNING This does not work for Redemption.
`collectorNumber`*	The customer’s AIR MILES account number. Example: `"81111111111"`
`dateTime`*	Date and time when the request was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`deviceId`*	ID number used to identify the POS terminal currently in use. Example: `"001"`
`instantMessage`	The Partner’s language preference for receiving the POS display messages. Example: `["en-CA", "fr-CA"]` Default value: `en-CA`
`postTaxBasketAmount`*	The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout). Example: `"16.12"`
`sponsorCode`*	Alpha-numeric value used to identify the Partner. Example: `"LOY1"` To be provided by AIR MILES
`storeId`*	Alpha-numeric value used to identify the Partner’s location. Example: `"0001"` To be provided by Partner
`traceId`*	Partner’s unique transaction tracking number. Example: `"000012345678"` This value can be recycled after a year To be provided by Partner
`vendorId`*	Number used to identify the Partner and for downstream financial payments. Example: `"555555"` To be provided by AIR MILES

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "acquirerId": "100000",
    "availableCashBalance": "95",
    "availableDollarAmount": "10",
    "availableOfferUnits": "1",
    "cashBalance": "120",
    "collectorNumber": "1234567890123456789",
    "dailyOfferLimit": "10",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "545",
    "message": "Approved",
    "offerDescEn": "Sample offer description in English.",
    "offerDescFr": "Exemple de description de l'offre en français.",
    "offerId": "1111111111",
    "offerType": "RGL",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2019-01-30T11:41:55",
    "unitValueAMCash": "95",
    "unitValueDollars": "10.00",
    "vendorId": "555555"
}

Response model

Includes all “Request” parameters listed above, plus the additional ones below.

Parameter	Description
`availableCashBalance`	The remaining available daily limit of AM Cash redemptions, in Miles (post-transaction); or the Collector’s total Miles balance - whichever is lower. Example: `"95"` Standard default is $750 CAD or 7,125 Miles per day
`availableDollarAmount`	The dollar ($) amount available that the Collector can redeem. Example: `"10"` This value is rounded down to the nearest $10
`availableOfferUnits`	The number of AM Cash units available to the Collector at checkout (in multiples of $10/95 miles). Example: `"1"`
`cashBalance`	The Collector’s “AM Cash” account balance in Miles (post-transaction). Example: `"120"`
`dailyOfferLimit`	The limit of AM Cash units the Collector can redeem today. Example: `"1"`
`dreamBalance`	The Collector’s “AIR MILES Dream” account balance. Example: `"550"`
`message`	Text description of the response code. Example: `"Approved"`
`offerDescEn`	Offer description (English)
`offerDescFr`	Offer description (French)
`offerId`	AM Cash offer ID. Example: `"1111111111"`
`offerType`	Either RGL (regular offers) or SPL (special/discounted offers). Example: `["RGL", "SPL"]`
`responseCode`	Number indicating the result of the transaction. Example: `"0000"` `0000`: Request processed successfully. `0001`: Approved (balance suppressed). `0002`: Collector profile inactive. `0005`: Unable to redeem (balance suppressed). `0006`: Unable to redeem. `0008`: Transaction timed-out, request needs to be retried. `0009`: Card not swiped or scanned. `0025`: Invalid collector number. `0035`: Invalid request parameter. `0051`: Insufficient AIR MILES Cash Miles. `0057`: Invalid redemption confirmation number. `0065`: Exceeded daily redemption limit. `0066`: Insufficient basket size. `0067`: Offer is temporarily unavailable. `0080`: Reversal window expired. `0092`: Scheduled outage. `0096`: System error.
`transDateTime`	Date and time when the response was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`unitValueAMCash`	The number of AM Cash miles required for a single redemption unit. Example: `"95"`
`unitValueDollars`	The dollar ($) value for a single unit of redemption. Example: `"10"`

Note

Responses will always include the responseCode and message fields. In addition, all fields that contain values (i.e., not null) will also be included in the response model.

Conditional parameters

The optional data elements contain information required to show the number of miles that can be redeemed and the discount that would be applied towards the purchase.

Note

The conditional response parameters listed below will ONLY be returned if the following conditions are met:

The Collector number is swiped or scanned (i.e., cardEntryMode = SWIPE, SCAN, or PREREGISTERED)
The Collector has enough reward miles in their balance.
The Collector has not exceeded their daily redemption limit.

Parameter	Description
`availableOfferUnits`	Redemption offer units available for the current transaction. Example: `"1"` (i.e., 1 unit = $10, so 5 units = $50 in redemptions.)
`dailyOfferLimit`	The maximum number of units a Collector can redeem in a single day (i.e., a 24 hour period). Example: `"10"`
`offerDescEn`	Offer description (English)
`offerDescFr`	Offer description (French)
`offerId`	AM Cash offer ID. Example: `"1111111111"`
`offerType`	Either RGL (regular offers) or SPL (special/discounted offers). Example: `["RGL", "SPL"]`
`unitValueAMCash`	The number of “AM Cash” miles required for a single redemption unit. Example: `"95"`
`unitValueDollars`	The dollar ($) value for a single unit of redemption. Example: `"10"`

Status/Response codes

Status Code	Response Code	Display Message	Description
`200`	`0000`	Approved	The transaction was successful. The POS terminal AND receipt should display the appropriate information.
`202`	`0001`	Approved - Balance suppressed	The transaction was successful, however the Collector opted to not view their rewards balances. The printed receipt MUST NOT show the Collector’s ‘Cash’/‘Dream’ balances, or the available “AM Cash” that can be redeemed.
`401`	`0002`	Collector account inactive	The Collector account is not active. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center.
`202`	`0005`	Balance suppressed, unable to redeem	The transaction was successful, but the Collector opted to not view their balances, or allow instant cash redemptions. The POS terminal MUST NOT prompt for an “AM Cash” Redemption.
`202`	`0006`	Unable to redeem	The transaction was successful, but the Collector account is set to not allow instant “AM Cash” redemptions. The POS terminal MUST NOT prompt for an “AM Cash” Redemption.
`408`	`0008`	Transaction timeout	The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`403`	`0009`	Card not swiped or scanned	Redemption offers will not be sent if the Collector Card is not presented. The Collector Card is physically required to perform instant cash redemptions. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`401`	`0025`	Invalid collector number	The Collector number is invalid. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`202`	`0051`	Insufficient AIR MILES reward Miles	The Collector has not earned enough in their “AIR MILES Cash” balance for the requested redemption amount. Please ask the Collector to go to airmiles.ca and check their redemption/earning history.
`408`	`0067`	Offer is temporarily unavailable	The offer being requested is temporarily unavailable. Please advise the Collector to try redeeming this offer at a later time.
`503`	`0092`	Scheduled outage	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	`0096`	Server error or no response	An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
none	none	Missing or invalid “Bearer token”	No valid “Bearer Token” present. Please generate a valid “Bearer” Token and submit to continue."

3 - REDEEM

Used to redeem AIR MILES Cash Miles from a Collector’s account to be used towards their purchase.

POST /checkout/amcash/redeem

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

To redeem Miles, the Collector’s card must be either scanned, swiped, or pre-registered (e.g., e-commerce site).

Important

Key-entering the Collector’s number manually is not a valid way to process a redemption request. Using this method will cause the transaction to fail.

Redemption process

The sales associate makes a redemption request at checkout by submitting a dollarRedeemRequest.
The maximum redemption amount is displayed on-screen, which is less than or equal to the postTaxBasketAmount.
The sales associate selects the appropriate redemption amount (unitsRedeemed) before completing the transaction.

Tip

Default redemption amount to be displayed

The total purchase amount after tax, rounded down to the nearest $10.
(e.g., if the post-tax basket amount is $43.35, the maximum allowable redemption would be $40)
Or, the Collector’s maximum redeemable Cash balance - in multiples of $10.

Calculating the dollar amount

The dollar amount to be applied towards the purchase is calculated by multiplying the number of unitsRedeemed by unitValueDollars (which is currently $10 CAD).

Upon receiving the redemption response from our real-time checkout, the POS terminal should display and print the transaction confirmation number (i.e., txtConfirmationNumber).

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/redeem \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "acquirerId": "100000",
  "cardEntryMode": "SWIPE",
  "collectorNumber": "84095202006",
  "dateTime": "1972-07-16T13:32:00+0400",
  "deviceId": "001",
  "dollarRedeemRequest": "16.12",
  "instantMessage": "en-CA",
  "originalPostTaxBasketAmount": "16.12",
  "originalPreTaxAmount": "16.12",
  "postTaxBasketAmount": "16.12",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Parameter	Description
Authorization	Token from authentication. Example: `Bearer eyJhbGciOiJSUzI1NiIsI…`
Content-Type	Default value: `application/json`
cache-control	Default value: `no-cache`

Query parameters

Parameter	Description
none	none

Body parameters

* Required field

Parameter	Description
`acquirerId`*	The acquirer ID identifies the party that sends the request. Usually this is the partner. Example: `"100000"`
`cardEntryMode`*	The method that was used to enter the AIR MILES account number. Example: `"SWIPE"` `SWIPE` The card's magstripe was swiped. `SCAN` The card's barcode is scanned at the POS using an I/R reader. `PREREGISTERED` The information is passed automatically as with an online-checkout or mobile app purchase. `MANUAL` The card number is manually entered into the POS system. WARNING This does not work for Redemption.
`collectorNumber`*	The customer’s AIR MILES account number. Example: `"81111111111"`
`dateTime`*	Date and time when the request was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`deviceId`*	ID number used to identify the POS terminal currently in use. Example: `"001"`
`dollarRedeemRequest`*	The dollar amount available to be redeemed. Example: `"16.12"`
`instantMessage`	The partner’s language preference for receiving the POS display messages. Example: `["en-CA", "fr-CA"]` Default value: `en-CA`
`originalPostTaxBasketAmount`	Original purchase amount, post-tax. Example: `"33.87"`
`originalPreTaxAmount`	Original purchase amount, pre-tax. Example: `"29.97"`
`postTaxBasketAmount`*	The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout). Example: `"16.12"`
`sponsorCode`*	Alpha-numeric value used to identify the Partner. Example: `"LOY1"` To be provided by AIR MILES
`storeId`*	Alpha-numeric value used to identify the Partner’s location. Example: `"0001"` To be provided by Partner
`traceId`*	Partner’s unique transaction tracking number. Example: `"000012345678"` This value can be recycled after a year To be provided by Partner
`vendorId`*	Number used to identify the Partner and for downstream financial payments. Example: `"555555"` To be provided by AIR MILES

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "acquirerId": "100000",
    "availableCashBalance": "95",
    "availableDollarAmount": "10",
    "cashBalance": "120",
    "collectorNumber": "80000000001",
    "dailyOfferLimit": "10",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "550",
    "message": "Approved",
    "milesRedeemed": "95",
    "offerDescEn": "Sample offer description in English.",
    "offerDescFr": "Exemple de description de l'offre en français.",
    "offerId": "1111111111",
    "offerType": "RGL",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2018-10-27T02:25:10",
    "txnConfirmationNumber": "0000",
    "unitsRedeemed": "1",
    "unitValueAMCash": "95",
    "unitValueDollars": "10.00",
    "vendorId": "555555"
}

Response model

Includes all “Request” parameters listed above, plus the additional ones below.

Parameter	Description
`availableCashBalance`	The remaining available daily limit of AM Cash redemptions, in Miles (post-transaction); or the Collector’s total Miles balance - whichever is lower. Example: `"95"` Standard default is $750 CAD or 7,125 Miles per day
`availableDollarAmount`	The dollar ($) amount available that the Collector can redeem. Example: `"10"` This value is rounded down to the nearest $10
`cashBalance`	The Collector’s AM Cash account balance in Miles (post-transaction). Example: `"120"`
`dailyOfferLimit`	The maximum number of units a Collector can redeem in a single day (i.e., a 24 hour period). Example: `"10"`
`dreamBalance`	The Collector’s “AIR MILES Dream” account balance. Example: `"545"`
`message`	Text description of the response code. Example: `"Approved"`
`milesRedeemed`	The number of AM Cash miles redeemed in the transaction. Example: `"475"`
`offerDescEn`	Offer description (English)
`offerDescFr`	Offer description (French)
`offerId`	AM Cash offer ID. Example: `"1111111111"`
`offerType`	Either RGL (regular offers) or SPL (special/discounted offers). Example: `["RGL", "SPL"]`
`responseCode`	Number indicating the result of the transaction. Example: `"0000"` `0000`: Request processed successfully. `0001`: Approved (balance suppressed). `0002`: Collector profile inactive. `0005`: Unable to redeem (balance suppressed). `0006`: Unable to redeem. `0008`: Transaction timed-out, request needs to be retried. `0009`: Card not swiped or scanned. `0025`: Invalid collector number. `0035`: Invalid request parameter. `0051`: Insufficient AIR MILES Cash Miles. `0057`: Invalid redemption confirmation number. `0065`: Exceeded daily redemption limit. `0066`: Insufficient basket size. `0067`Offer is temporarily unavailable. `0080`: Reversal window expired. `0092`: Scheduled outage. `0096`: System error.
`transDateTime`	Date and time when the response was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`txnConfirmationNumber`	The confirmation number returned upon a successful redemption. This value should be printed on the purchase receipt and is required to process a reversal. Example: `"83445182010"` To be provided by AIR MILES
`unitsRedeemed`	The number of AM Cash units redeemed in the transaction. Example: `"5"`
`unitValueAMCash`	The number of AM Cash miles required for a single redemption unit. Example: `"95"`
`unitValueDollars`	The dollar ($) value for a single unit of redemption. Example: `"10"`

Note

Responses will always include the responseCode and message fields. In addition, all fields that contain values (i.e., not null) will also be included in the response model.

Status/Response codes

Status Code	Response Code	Display Message	Description
`200`	`0000`	Approved	The transaction was successful. The POS terminal AND receipt should display the appropriate information.
`202`	`0001`	Approved - balance suppressed	The transaction was successful, however the Collector opted to not view their rewards balances. The printed receipt MUST NOT show the Collector’s ‘Cash’/‘Dream’ balances, or the available “AM Cash” that can be redeemed.
`401`	`0002`	Collector account inactive	The Collector account is not active. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center.
`202`	`0005`	Balance suppressed, unable to redeem	The transaction was successful, but the Collector opted to not view their balances, or allow instant cash redemptions. The POS terminal MUST NOT prompt for an “AM Cash” Redemption.
`202`	`0006`	Unable to redeem	The transaction was successful, but the Collector account is set to not allow instant “AM Cash” redemptions. The POS terminal MUST NOT prompt for an “AM Cash” Redemption.
`408`	`0008`	Transaction timeout	The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`403`	`0009`	Card not swiped or scanned	Redemption offers will not be sent if the Collector Card is not presented. The Collector Card is physically required to perform instant cash redemptions. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`401`	`0025`	Invalid collector number	The Collector number is invalid. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`202`	`0051`	Insufficient AIR MILES reward Miles	The Collector has not earned enough in their “AIR MILES Cash” balance for the requested redemption amount. Please ask the Collector to go to airmiles.ca and check their redemption/earning history.
`202`	`0065`	Exceeded daily redemption limit	The Collector has exceeded the daily redemption limit. The Collector’s account has exceeded the maximum daily redemption amount. Please ask the Collector to wait until the following day to redeem more Cash miles.
`202`	`0066`	Insufficient basket size	The Collector’s basket size is too small to make a redemption. The purchase amount is not enough to make a redemption. Ask the customer if they wish to add more items to their basket in order to make an AM Cash redemption.
`408`	`0067`	Offer is temporarily unavailable	The offer being requested is temporarily unavailable. Please advise the Collector to try redeeming this offer at a later time.
`503`	`0092`	Scheduled outage	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	`0096`	Server error or no response	An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
none	none	Missing or invalid “Bearer token”	No valid “Bearer Token” present. Please generate a valid “Bearer” Token and submit to continue."

4 - REVERSE

Used to refund (aka reverse) an AM Cash Miles redemption.

POST /checkout/amcash/reverse

Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.

Prior to requesting a “reversal”, a valid “redemption request”/“redemption response” must be exchanged in order to create the txnConfirmationNumber required for the “reversal”.

WARNING

Key-entering the Collector’s number manually is not a valid way to process a redemption request. Using this method will cause the transaction to fail.

Also, please note that reversals can only be issued up until 3:00 AM EST the same day of the purchase, for a given transaction.

Reversal process

The sales associate makes a REVERSAL request at checkout by submitting the redemptionConfirmationNumber for the transaction in question.
The POS system will prompt the sales associate to accept the return and issue a full monetary refund.
Once completed, a response message containing all relevant fields will be returned to the POS system.

Tip

Calculating the reversal amount

The AM Cash API will calculate the Miles to reversed to the Collector when processing a reversal request. This number is based on the transaction ID of the original transaction, which is why it’s required to provide the redemptionConfirmationNumber before proceeding.

Upon receiving the reversal response from our real-time checkout, the POS terminal should display and print the transaction confirmation number (i.e., txtConfirmationNumber).

Receiving a timeout

If you receive a timeout (i.e., responseCode 0008) or you receive NO response at all, your POS terminal should automatically retry the reversal request. If the error persists, the POS terminal should display an error message (as explained in POS Terminal Workflows > Processing a Reversal).

Sample request

curl -X POST \
  https://cert.airmilesapis.ca/checkout/amcash/reverse \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "acquirerId": "100000",
  "cardEntryMode": "SWIPE",
  "collectorNumber": "84095202006",
  "dateTime": "1972-07-16T13:32:00+0400",
  "deviceId": "001",
  "redemptionConfirmationNum": "10000000000",
  "sponsorCode": "LOY1",
  "storeId": "0001",
  "traceId": "999999999999",
  "vendorId": "100087"
}'

Header parameters

Parameter	Description
Authorization	Token from authentication. Example: `Bearer eyJhbGciOiJSUzI1NiIsI…`
Content-Type	Default value: `application/json`
cache-control	Default value: `no-cache`

Query parameters

Parameter	Description
none	none

Body parameters

* Required field

Parameter	Description
`acquirerId`*	The acquirer ID identifies the party that sends the request, usually this is the partner. Example: `"100000"` To be provided by AIR MILES
`cardEntryMode`*	The method that was used to enter the AIR MILES account number. Example: `"SWIPE"` `SWIPE` The card's magstripe was swiped. `SCAN` The card's barcode is scanned at the POS using an I/R reader. `PREREGISTERED` The information is passed automatically as with an online-checkout or mobile app purchase. `MANUAL` The card number is manually entered into the POS system. WARNING This does not work for Redemption.
`collectorNumber`*	The customer’s AIR MILES account number. Example: `"81111111111"`
`dateTime`*	Date and time when the request was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`deviceId`*	ID number used to identify the POS terminal currently in use. Example: `"001"`
`redemptionConfirmationNum`*	Number used to identify the redemption transaction to reverse (void). Example: `"10000000000"`
`sponsorCode`*	Alpha-numeric value used to identify the Partner. Example: `"LOY1"` To be provided by AIR MILES
`storeId`*	Alpha-numeric value used to identify the Partner’s location. Example: `"0001"` To be provided by Partner
`traceId`*	Partner’s unique transaction tracking number. Example: `"000012345678"` This value can be recycled after a year To be provided by Partner
`vendorId`*	Number used to identify the Partner and for downstream financial payments. Example: `"555555"` To be provided by AIR MILES

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2018 15:27:34 GMT
{
    "acquirerId": "100000",
    "availableCashBalance": "95",
    "availableDollarAmount": "10",
    "cashBalance": "120",
    "collectorNumber": "80000000001",
    "dateTime": "2019-01-30T04:39:59.503-0400",
    "deviceId": "001",
    "dreamBalance": "550",
    "message": "Approved",
    "milesReversed": "95",
    "responseCode": "0000",
    "sponsorCode": "1234",
    "storeId": "0001",
    "traceId": "000012345678",
    "transDateTime": "2019-01-30T04:39:59",
    "txnConfirmationNumber": "0000",
    "unitsReversed": "1",
    "unitValueAMCash": "95",
    "unitValueDollars": "10",
    "vendorId": "1234567890"
}

Response model

Includes all “Request” parameters listed above, plus the additional ones below.

Parameter	Description
`availableCashBalance`	The remaining available daily limit of AM Cash redemptions, in Miles (post-transaction); or the Collector’s total Miles balance - whichever is lower. Example: `"95"` Standard default is $750 CAD or 7,125 Miles per day
`availableDollarAmount`	The dollar ($) amount available that the Collector can redeem. Example: `"10"` This value is rounded down to the nearest $10
`cashBalance`	The Collector’s AM Cash account balance in Miles (post-transaction). Example: `"120"`
`dreamBalance`	The Collector’s “AIR MILES Dream” account balance. Example: `"550"`
`message`	Text description of the response code. Example: `"Approved"`
`milesReversed`	The number of AM Cash miles reversed (refunded). Example: `"95"`
`responseCode`	Number indicating the result of the transaction. Example: `"0000"` `0000`: Request processed successfully. `0001`: Approved (balance suppressed). `0002`: Collector profile inactive. `0005`: Unable to redeem (balance suppressed). `0006`: Unable to redeem. `0008`: Transaction timed-out, request needs to be retried. `0009`: Card not swiped or scanned. `0025`: Invalid collector number. `0035`: Invalid request parameter. `0051`: Insufficient AIR MILES Cash Miles. `0057`: Invalid redemption confirmation number. `0065`: Exceeded daily redemption limit. `0066`: Insufficient basket size. `0067`Offer is temporarily unavailable. `0080`: Reversal window expired. `0092`: Scheduled outage. `0096`: System error.
`transDateTime`	Date and time when the response was sent. (see ISO-8601) Example: `"1972-07-16T13:32:00+0400"`
`txnConfirmationNumber`	The confirmation number returned upon a successful redemption. This value should be printed on the purchase receipt and is required to process a reversal. Example: `"83445182010"` To be provided by AIR MILES
`unitsReversed`	The number of AM Cash units reversed (refunded). Example: `"1"`
`unitValueAMCash`	The number of AM Cash miles required for a single redemption unit. Example: `"95"`
`unitValueDollars`	The dollar ($) value for a single unit of redemption. Example: `"10"`

Note

Responses will always include the responseCode and message fields. In addition, all fields that contain values (i.e., not null) will also be included in the response model.

Status/Response codes

Status Code	Response Code	Display Message	Description
`200`	`0000`	Approved	The transaction was successful. The POS terminal AND receipt should display the appropriate information.
`202`	`0001`	Approved - balance suppressed	The transaction was successful, however the Collector opted to not view their rewards balances. The printed receipt MUST NOT show the Collector’s ‘Cash’/‘Dream’ balances, or the available “AM Cash” that can be redeemed.
`401`	`0002`	Collector account inactive	The Collector account is not active. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center.
`408`	`0008`	Transaction timeout	The transaction timed out when a request was sent to the “Instant POS” Switch. The Partner’s Switch/POS Terminal should retry the request one (1) time. If a cashier receives this error, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
`403`	`0009`	Card not swiped or scanned	Redemption offers will not be sent if the Collector Card is not presented. The Collector Card is physically required to perform instant cash redemptions. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`401`	`0025`	Invalid collector number	The Collector number is invalid. Please ask the Collector to visit the airmiles.ca self-serve page, online chat support, or contact our call-center to request a replacement card.
`400`	`0035`	Invalid request parameter	A mistake was made when submitting the request. Please correct the error and try again.
`202`	`0051`	Insufficient AIR MILES reward Miles	The Collector has not earned enough in their “AIR MILES Cash” balance for the requested redemption amount. Please ask the Collector to go to airmiles.ca and check their redemption/earning history.
`400`	`0057`	Invalid redemption confirmation number	The `redemptionConfirmationNumber` submitted is invalid. Please resubmit the request with the correct Redemption Confirmation Number.
`202`	`0065`	Exceeded daily redemption limit	The Collector has exceeded the daily redemption limit. The Collector’s account has exceeded the maximum daily redemption amount. Please ask the Collector to wait until the following day to redeem more Cash miles.
`202`	`0066`	Insufficient basket size	The Collector’s basket size is too small to make a redemption. The purchase amount is not enough to make a redemption. Ask the customer if they wish to add more items to their basket in order to make an AM Cash redemption.
`408`	`0067`	Offer is temporarily unavailable	The offer being requested is temporarily unavailable. Please advise the Collector to try redeeming this offer at a later time.
`409`	`0080`	Reversal window expired	The reversal window for the redemption has expired; meaning a reversal can no longer be submitted for this transaction. This usually happens when a reversal is attempted after 3:00 AM the day after the original transaction. Any reversals that are attempted past the 3:00 AM time-frame should be refunded to the customer via in-store credit or gift card. Please DO NOT RETURN CASH to the customer.
`503`	`0092`	Scheduled outage	The system is unavailable due to scheduled maintenance. No requests can be sent.
`500`	`0096`	Server error or no response	An unknown error occurred while calling the “Instant POS” Switch". The Sponsor Switch/POS Terminal should retry one time and if the error persists, they should escalate the issue as indicated in the “AM Cash - Sponsor Escalation Guide”.
none	none	Missing or invalid “Bearer token”	No valid “Bearer Token” present. Please generate a valid “Bearer” Token and submit to continue."

Handling timeouts

A request timeout has occurred if either of the following scenarios is true:

You received a “response code” of 0008
You received no response at all

Upon experiencing a request timeout, your POS terminal should immediately attempt a retry of the same transaction request. The “Retry Request” must match the initial request exactly.

If the new request does not match exactly with the initial request, the system will not recognize it as a “retry”, but will register it as a brand new transaction. If the request continues to timeout/fail, an error message should be displayed to the cashier and/or the customer, as suggested in the section Displaying the reversal result.

If at any time, our real-time checkout encounters an internal problem or network error while trying to return a “redemption response”; the redemption request will be automatically cancelled, thereby ensuring the customer is not charged for a redemption that could not be delivered.

For all other response codes; when a particular code is received (e.g., 0002, 0096, etc.), the appropriate message should be displayed to the cashier, as shown in POS Workflows > Redemption.

Important

Notes regarding “file reconciliation”:

If the retry succeeds then the transaction must be included in the reconciliation report sent to AIR MILES.
If the retry fails, the transaction MUST NOT be included in the reconciliation report, as no Miles were processed for the transaction.