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