AIR MILES API Documentation

• 1. AIR MILES Cash
• 1.1. Authentication & Authorization
• 1.2. API Library
• 1.2.1. ECHO
• 1.2.2. INQUIRE
• 1.2.3. REDEEM
• 1.2.4. REVERSE
• 1.3. AIR MILES Cash API Docs
• 1.4. Point-of-Sale Terminal Workflows
• 1.5. File Reconciliation
• 1.6. OpenAPI (Swagger-Spec)
• 2. AIR MILES Issuance
• 2.1. Authentication & Authorization
• 2.2. API Library
• 2.2.1. AMRP Calculated Endpoints
• 2.2.1.1. CALCULATE
• 2.2.1.2. ISSUE
• 2.2.1.3. RETURN
• 2.2.1.4. RECORD
• 2.2.2. Partner Calculated Endpoints
• 2.2.2.1. POST
• 2.2.2.2. POST/EVENT
• 2.2.2.3. REVERSE
• 2.2.2.4. REVERSE/EVENT
• 2.2.2.5. RECORD
• 2.3. AIR MILES Issuance API Docs
• 2.4. OpenAPI (Swagger-Spec)
• 3. Member Banner
• 4. Offer State
• 4.1. Authentication & Authorization
• 4.2. API Library
• 4.2.1. Health Check
• 4.2.2. state-reader/FIND
• 4.2.3. state-reader/GET
• 4.2.4. state-reader/COUNT
• 4.2.5. state-writer/PUT
• 4.3. Offer State API Docs
• 4.4. OpenAPI (Swagger-Spec)

1 - AIR MILES Cash

Target audience

This material is intended to be used by a Partner wishing to integrate with the AIR MILES Cash API.

What is real-time redemption

The AIR MILES real-time platform provides Partners with a streamlined method for redeeming Collector’s AIR MILES Cash Reward Miles, online or in-store. Real-time redemption ensures your customer’s will be able to see their updated balances immediately before and after using their AIR MILES Cash Reward Miles.

Service level objective

Please contact our Partner support team for details on our Service Level Agreement (SLA). Refer to our “Escalation Guide” for contact details.

Integration environments

There are two sets of environments used by partners to integrate with the real-time checkout platform. These environments are configured similarly for consistent production-level quality, whether the partner has deployed to production or is still performing non-production testing.

Your AMRP project team

In preparation for launch, an AIR MILES team is pulled together to assist Partners with integration and setup. This team will provide the following services:

• Consulting Partners on the best technical solution to support AIR MILES Issuance based on system compatibility.
• Providing guidance for assessing Partner requirements, data exchange methods, and reconciliation.
• As well as overseeing a broad range of activities to meet the requirements of launch, including:
  • Planning
  • Communications
  • Delivery
  • Execution
  • Monitoring

Commonly used acronyms

1.1 - Authentication & Authorization

For more information on “Auth0” and the various authentication flows, click the button below.

Which Authentication Flow Should I Use?

1.2 - API Library

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.

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.

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.

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.

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.

Status/response codes

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

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

Query parameters

Body parameters

* Required field

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.

Status/Response codes

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

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

Query parameters

Body parameters

* Required field

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.

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.

Status/Response codes

1.2.3 - 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).

Redemption process

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

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

Query parameters

Body parameters

* Required field

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.

Status/Response codes

1.2.4 - 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”.

Reversal process

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

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

Query parameters

Body parameters

* Required field

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.

Status/Response codes

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.

1.3 - AIR MILES Cash API Docs

1.4 - Point-of-Sale Terminal Workflows

Display Types

Pop-up displays

From here onward, we are assuming that your terminals can display a pop-up window over the main terminal display. However if your terminals have a more limited display functionality, a similar display interface can be built by integrating the new “AIR MILES Cash” elements into the main display area; this is shown in figure 1 below.

Text-based displays

There are also display mockups for text-based POS terminals. These mockups assume that the POS terminal has at least twenty (20) columns and four (4) rows. Throughout this section, the two mockups will be shown side-by-side where possible, to contrast the different interfaces.

Processing a Redemption

Upon receiving an AM Cash Inquiry response, the POS terminal should display relevant offer information to the Collector, which at a minimum should include the remaining daily limit of AM Cash units the Collector can request.

AIR MILES Cash Inquiry

In the example above, the AM Cash “Inquiry” screen displays the following key values:

As previously stated, an offer is returned ONLY if the Collector has enough reward Miles to redeem at least a single unit AND have not reached their daily redemption cap. If no offer is returned, the POS terminal won’t display any of the information shown above.

The Collector can redeem for a minimum of 95 reward Miles (which is equivalent to $10.00 CAD.), as well as further increments of 95 reward Miles.

If the AM Cash inquiry response has an offer available for the Collector, the POS terminal should give the cashier a visual cue, so they can ask the Collector for redemption.

We recommend using one of the following options:

Preferred method

Pop-up window with AIR MILES Cash information.

For embedded interfaces

Blinking cue for embedded AIR MILES Cash section.

Alternative method

If there is no way to do either of the above, have the cashier click an on-screen button to activate the AIR MILES Cash section.

Displaying on a text-based POS

Similar to the GUI-based screens shown above, a text-based terminal should display the minimum and increment values together with the maximum allowed (based on the qualifying amount). The Collector at this point has the option to either enter an amount or cancel and proceed with the remaining purchase flow.

Here’s an example of what a text-based display would look like.

Displaying the Redemption

After the redemption request is sent and a response is received by the POS terminal, the redemption information can be shown as follows.

The POS terminal should display the following:

Transaction confirmation number

txnConfirmationNumber

Number of reward Miles redeemed

unitValueAMCash * unitsredeemed

Remaining reward Miles for redemption

cashBalance / unitValueAMCash

Displaying on a text-based POS

A text-based POS terminal could display the redemption information as follows.

Following this screen, the rest of the payment flow continues normally.

Printing the receipt

This section provides a mockup of what a receipt could look like.

The receipt shown above follows the examples that has been used so far and shows the following:

Common basket details

1. Partner details (business name, address, phone # etc.).
2. Purchase details (item/basket info - includes a negative balance if returning a product).
3. Sub-total, added sales tax, and total.
4. Transaction confirmation number together with the dollar/monetary amount of the redemption.

AIR MILES specific basket details

1. Masked Collector number (at least 3-digits in the middle must be masked, and the last four digits visible).
2. Base and bonus AIR MILES reward Miles redeemed.
3. Available “AIR MILES Cash” Rewards Miles balance.
4. Available “AIR MILES Dream” Rewards Miles balance.

Processing a Reversal

In order to reverse a redemption all that is needed is the original redemption confirmation number, as the redemption is fully reversed (no partial reversals are done).

This is demonstrated in figure 7 below:

The AM Cash reversal function should be made available to the cashier by way of a button or on-screen-display. Once this screen is displayed the cashier will need to enter the transaction confirmation number (txnConfirmationNumber) and press a key to process the reversal (such as the Void button shown in the figure above).

Displaying the reversal

After a reversal request has been processed, a response containing a new transaction confirmation number should be received.

This is demonstrated in figure 8 below.

The POS terminal should display the total Miles refunded (milesReversed), the available reward Miles (cashBalance) and the new reversal confirmation number (txnConfirmationNumber).

Printing the receipt

This section provides a mockup of how a receipt showing balances and redemption information could be organized.

See figure 9 below for more details:

The receipt shown above follows the examples that has been used so far and shows the following:

Common basket details

1. Partner details (business name, address, phone # etc.).
2. Purchase details (item/basket info - includes a negative balance if returning a product).
3. Sub-total, added sales tax, and total.
4. Transaction confirmation number together with the dollar/monetary amount of the redemption.

AIR MILES specific basket details

1. Masked Collector number (at least 3-digits in the middle must be masked, and the last four digits visible).
2. Base and bonus AIR MILES reward Miles voided/reversed (calculated by the partner).
3. Available “AIR MILES Cash” Rewards Miles balance.
4. Available “AIR MILES Dream” Rewards Miles balance.

1.5 - File Reconciliation

A Reconciliation process has been established to ensure that successful “Redemption” and “Reverse” transactions match in both the partner’s systems and AIR MILES systems. This matching ensures that the number of transactions in both systems and the transaction values (e.g., amounts, dates) are identical.

What are reconciliation files

The Reconciliation files are sent to the Partner at regular intervals, and contain all successful Redemptions and Reversals that were reconciled on a given day.

The following sections describe the Reconciliation process, files, formats, and file transfer methods.

File formats and schedules

Each Reconciliation file contains the following:

• Header Records x2
• Trailer Records x2
• Detailed Records 0 or more

Reconciliation files are text-based and have a specific format (described below), use delimiters to separate fields, and are uncompressed & un-encrypted. Records within the reconciliation file use the standard ASCII character set, where fields within a record are separated by double percent characters (%%), and records are separated by a new line character at the end of each line.

Since fields in the file records are delimited with percentage characters (%%) there is no need for fillers or padding. As an example, the “amount” field is defined as Numeric and 4 characters in length, so in order to send 190 Miles, it is enough to send just those three digits (i.e., there is no need to send 0190). Similarly, the “Card Terminal ID” is defined as Alphanumeric and 16 characters in length, so in order to send the characters SPON000101 there is no need to append filler spaces at the end of those characters.

During normal processing times, reconciliation files will be created at regular intervals. For resubmissions, the files may contain more (or less) than 24-hours of transactions, and may include a different time range. However, in all instances the “Local Transaction Date/Time” of all records within the file must be between the BeginExtractDate and EndExtractDate values in the “Header” and “Trailer” records (see an example of the file format below).

Files sent to the partner

The naming of the reconciliation file uses the following format:

RECON_LMG_YYYYMMDD.txt

As an example, a reconciliation file created on July 19, 2020 would be named RECON_LMG_20200719.txt.

Sample file contents

H%%20100718070925%%20100718221523
S%%95001%%20100718070925%%20100718221523
D%%2210%%80000000001%%190%%358%%162824%%20100718%%39000000883%%SPON000101%%20.00
D%%2210%%80000000001%%190%%344%%070925%%20100718%%39000000842%%SPON001101%%20.00
D%%2210%%80000000001%%190%%355%%221523%%20100718%%39000000750%%SPON000121%%20.00
D%%2430%%80000000001%%190%%359%%162940%%20100718%%39000000883%%SPON000105%%20.00
D%%2210%%80000000001%%190%%2909%%083455%%20100718%%39000000644%%SPON000106%%20.00
D%%2430%%80000000001%%190%%2912%%143448%%20100718%%39000000636%%SPON000106%%20.00
D%%2210%%80000000001%%190%%341%%090658%%20100718%%39000000693%%SPON000101%%20.00
D%%2430%%80000000001%%190%%345%%151102%%20100718%%39000000842%%SPON000101%%20.00
D%%2430%%80000000001%%190%%2911%%143455%%20100718%%39000000644%%SPON000101%%20.00
D%%2210%%80000000001%%95%%327%%074551%%20100718%%39000000677%%SPON000111%%10.00
F%%95001%%20100718070925%%20100718221523%%10
T%%20100718070925%%20100718221523%%12

Header and trailer record templates

As mentioned above, the reconciliation files contain two (2) header records, two (2) trailer records, and zero (0) or more detailed records.

Header 1

H%%BeginExtractDate%%EndExtractDate

Header 2

S%%CardAcceptorId%%BeginExtractDate%%EndExtractDate

Trailer 1

F%%CardAcceptorId%%BeginExtractDate%%EndExtractDate%%NumOfDetailRowsInFile

Trailer 2

T%%BeginExtractDate%%EndExtractDate%%NumOfDetailRowsInFile+2

Reconciliation file fields

File transmission method

The accepted transmission method for receiving the Reconciliation file is via SFTP (Simple File-Transfer-Protocol).

Contact us for more details at partnersupport@loyalty.com.

1.6 - OpenAPI (Swagger-Spec)

2 - AIR MILES Issuance

Target audience

This material is intended to be used by a Partner wishing to integrate with the AM Issuance API.

What is real-time Issuance

The AIR MILES “Real-Time Checkout” platform provides Partners with a streamlined method for instantly awarding their customers with AIR MILES Reward Miles, online or in-store. “Real-Time Issuance” ensures your customers will be able to see their updated balances immediately following checkout.

Service level objective

Please contact our Partner support team for details on our Service Level Agreement (SLA). Refer to our “Escalation Guide” for contact details.

Integration environments

There are two sets of environments used by partners to integrate with the real-time checkout platform. These environments are configured similarly for consistent production-level quality, whether the partner has deployed to production or is still performing non-production testing.

Your AMRP project team

In preparation for launch, an AIR MILES team is pulled together to assist Partners with integration and setup. This team will provide the following services:

• Consulting Partners on the best technical solution to support AIR MILES Issuance based on system compatibility.
• Providing guidance for assessing Partner requirements, data exchange methods, and reconciliation.
• As well as overseeing a broad range of activities to meet the requirements of launch, including:
  • Planning
  • Communications
  • Delivery
  • Execution
  • Monitoring

Commonly used acronyms

2.1 - Authentication & Authorization

For more information on “Auth0” and the various authentication flows, click the button below.

Which Authentication Flow Should I Use?

2.2 - API Library

This section describes the AIR MILES Issuance API endpoints. The endpoints are grouped into 2 categories; AMRP Calculated and Partner Calculated. Each API 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

AMRP Calculated Endpoints

Includes the API endpoints CALCULATE, ISSUE, RETURN, and RECORD.

Partner Calculated Endpoints

Includes the API endpoints POST, POST/EVENT, REVERSE, REVERSE/EVENT, and RECORD.

Idempotent requests

All the API calls (except RECORD) 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 issue miles to 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 extra miles aren’t accidentally deposited into the Collector’s account.

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.

Sample header with Idempotency

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/post \
    -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.

Response code descriptions

Error code descriptions

2.2.1 - AMRP Calculated Endpoints

The APIs in this section handle all the calculations and logging themselves, which makes things easier for most businesses looking to integrate with the AIR MILES rewards program. Using the “AMRP Calculated” method means AIR MILES handles all the logging and billing aspects of the service.

2.2.1.1 - CALCULATE

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

The CALCULATE endpoint is used to calculate how many Miles to issue for all eligible items in the basket. This API call DOES NOT issue actual Miles to the Collector.

API call validation process

After making a call to CALCULATE, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/calculate \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "items": [{
            "baseAmount": 9.99,
            "categoryId" : "11101",
            "departmentId":"10001",
            "finalAmount": 19.98,
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2
        },
        {
            "baseAmount": 4.99,
            "categoryId" : "CAT2",
            "departmentId":"DEPT2",
            "finalAmount": 4.99,
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1
        }
    ],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "TEST",
    "tender": ["CASH", "CREDIT"],
    "transactionType": "RETURN"
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber":"81111111111",
  "context": {"key1": "value1","key2": "value2"},
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454"
    }],
    "items": [{
            "baseAmount": 9.99,
            "categoryId" : "11101",
            "departmentId":"10001",
            "finalAmount": 19.98,
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2
        },
              {
            "baseAmount": 4.99,
            "categoryId" : "CAT2",
            "departmentId":"DEPT2",
            "finalAmount": 4.99,
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "TEST",
  "tender": ["CASH","CREDIT"],
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3",
  "transactionType": "RETURN"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.1.2 - ISSUE

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

The ISSUE endpoint is used to both calculate how many Miles will be issued for all eligible items in the basket, and deposit those Miles to the Collector’s account.

API call validation process

After making a call to ISSUE, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction.

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/issue \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "items": [{
            "baseAmount": 9.99,
            "categoryId" : "11101",
            "departmentId":"10001",
            "finalAmount": 19.98,
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2
        },
        {
            "baseAmount": 4.99,
            "categoryId" : "CAT2",
            "departmentId":"DEPT2",
            "finalAmount": 4.99,
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1
        }
    ],
    "locationCode": "1137",
    "sponsorCode": "TEST",
    "tender": ["CASH", "CREDIT"]
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber": "81111111111",
  "context": {"key1": "value1","key2": "value2"},
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "confirmationNumber": "0ed100a4-fc9a-41bb-a747-942c2593b683",
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454",
      "processedDateTime": "2019-05-30T14:12:59.479Z",
      "status": "CONFIRMED"
    }],
    "items": [{
            "baseAmount": 9.99,
            "categoryId" : "11101",
            "departmentId":"10001",
            "finalAmount": 19.98,
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2
        },
        {
            "baseAmount": 4.99,
            "categoryId" : "CAT2",
            "departmentId":"DEPT2",
            "finalAmount": 4.99,
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1
        }
    ],
  "locationCode": "1137",
  "sponsorCode": "TEST",
  "tender": ["CASH","CREDIT"],
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.1.3 - RETURN

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

The RETURN endpoint is used to recalculate the Miles earned for each item in the basket, then withdraws the Miles for the item(s) being returned.

API call validation process

After making a call to RETURN, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction.

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/return \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
        {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"DEPT2",
            "categoryId" : "CAT2"
        }
    ],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "TEST",
    "tender": ["CASH", "CREDIT"]
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber":"81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "confirmationNumber": "0ed100a4-fc9a-41bb-a747-942c2593b683",
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454",
      "processedDateTime": "2019-05-30T14:12:59.479Z",
      "status": "CONFIRMED"
    }],
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"DEPT2",
            "categoryId" : "CAT2"
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "TEST",
  "tender": ["CASH","CREDIT"],
  "context": {"key1": "value1","key2": "value2"},
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.1.4 - RECORD

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

The RECORD endpoint is used to test and verify the transmission of transactions to AIR MILES - this includes both Collector and non-Collector transactions. This endpoint can be used initially to test and verify that the API integration is working as expected.

API call validation process

After making a call to RECORD, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/calculate \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
        {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"DEPT2",
            "categoryId" : "CAT2"
        }
    ],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "TEST",
    "tender": ["CASH", "CREDIT"],
    "transactionType": "RETURN"
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber": "81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"10001",
            "categoryId" : "11101"
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "KELL",
  "tender": ["CASH","CREDIT"],
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3",
  "context": {"key1": "value1","key2": "value2"},
  "transactionType": "RETURN"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.2 - Partner Calculated Endpoints

The APIs in this section require the Partner to keep a detailed log of all their transactions, calculate Miles to be issued for each transaction, which must be sent to AIR MILES on a regular basis (i.e., daily, weekly, bi-weekly or monthly) to facilitate issuing these Miles to AIR MILES Collectors. This method is primarily used by businesses that wish to keep their own detailed record of every transaction and remit those records on their own schedule.

2.2.2.1 - POST

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

The POST endpoint is used to issue Miles to a Collector’s account in real-time for a basket transaction at checkout. With this method selected The total Miles to be issued are calculated by the Partner.

API call validation process

After making a call to POST, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/post \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "issuances": [{
        "contributingItemIds": ["SKU1234","SKU1252"],
        "issuanceOfferCode": "STANDARD",
        "locationCode": "1100",
        "milesAmount": 5,
        "offerDescription": "Bonus Miles for Groceries.",
        "offerId": "123454"
      }],
      "items": [{
              "id": "SKU1234",
              "name": "Dog Food",
              "number": 1,
              "quantity": 2,
              "baseAmount": 9.99,
              "finalAmount": 19.98,
              "departmentId":"10001",
              "categoryId" : "11101"
          },
                {
              "id": "SKU1252",
              "name": "Potato Chips",
              "number": 2,
              "quantity": 1,
              "baseAmount": 4.99,
              "finalAmount": 4.99,
              "departmentId":"10001",
              "categoryId" : "11101"
          }],
    "locationCode": "1137",
    "sponsorCode": "KELL",
    "tender": ["CASH","CREDIT"]
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber": "81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "confirmationNumber": "0ed100a4-fc9a-41bb-a747-942c2593b683",
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454",
      "processedDateTime": "2019-05-30T14:12:59.479Z",
      "status": "CONFIRMED"
    }],
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"10001",
            "categoryId" : "11101"
        }],
  "locationCode": "1137",
  "sponsorCode": "KELL",
  "tender": ["CASH","CREDIT"],
  "context": {"key1": "value1","key2": "value2"},
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.2.2 - POST/EVENT

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

The POST/EVENT endpoint is used to issue Miles to a Collector’s account in real-time for a non-transactional reason (e.g., issuing Miles for desired activity or issuing a manual correction to a Collector’s account). With this method selected the total Miles to be issued are calculated by the partner.

API call validation process

After making a call to POST/EVENT, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/post/event \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "clientTransactionId": "111112314",
    "collectorNumber": "80085102028",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": [
        "coupon"
    ],
    "deviceId": "string",
    "issuances": [
        {
            "issuanceOfferCode": "STANDARD",
            "locationCode": "0037",
            "milesAmount": 8,
            "offerDescription": "offer",
            "offerId": 22
        }
    ],
    "sponsorCode": "KENY",
    "transactionDateTime": "2021-11-09T21:04:45.930Z"
}

Request parameters

* required field

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
{
    "clientTransactionId": "111112314",
    "collectorNumber": "80085102028",
    "coupon": [
        "coupon"
    ],
    "deviceId": "string",
    "issuances": [
        {
            "issuanceOfferCode": "STANDARD",
            "locationCode": "0037",
            "milesAmount": 8,
            "offerDescription": "offer",
            "offerId": "22",
            "status": "PENDING"
        }
    ],
    "sponsorCode": "KENY",
    "transactionDateTime": "2021-11-11T12:54:31.780-05:00",
    "transactionId": "93a1237c-545c-4f16-96e5-4d890c903bd9"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.2.3 - REVERSE

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

The REVERSE endpoint is used to reverse Miles from a Collector’s account for returns or corrections.

API call validation process

After making a call to REVERSE, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction.

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/reverse \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "issuances": [{
        "contributingItemIds": ["SKU1234","SKU1252"],
        "issuanceOfferCode": "STANDARD",
        "locationCode": "1100",
        "milesAmount": 5,
        "offerDescription": "Bonus Miles for Groceries.",
        "offerId": "123454"
      }],
      "items": [{
            "baseAmount": 9.99,
            "categoryId" : "11101",
            "departmentId":"10001",
            "finalAmount": 19.98,
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2
          },
          {
            "baseAmount": 4.99,
            "categoryId" : "CAT2",
            "departmentId":"DEPT2",
            "finalAmount": 4.99,
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1
          }],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "KELL",
    "tender": ["CASH","CREDIT"]
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber": "81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "confirmationNumber": "0ed100a4-fc9a-41bb-a747-942c2593b683",
      "contributingItemIds": ["SKU1234","SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454",
      "processedDateTime": "2019-05-30T14:12:59.479Z",
      "status": "CONFIRMED"
    }],
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"10001",
            "categoryId" : "11101"
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "KELL",
  "tender": ["CASH","CREDIT"],
  "context": {"key1": "value1","key2": "value2"},
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.2.4 - REVERSE/EVENT

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

The REVERSE/EVENT endpoint is used to reverse Miles from a Collector’s account in real-time for a non-transactional reason (e.g., issuing a manual correction to a Collector’s account). With this method selected the total Miles to be reversed are calculated by the Partner.

API call validation process

After making a call to REVERSE/EVENT, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is SUCCESSFUL but issuances are pending and causing a delay

• You will receive a response code of 202
• No further action is required
• Resubmitting the same request will have no effect on the transaction

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/reverse/event \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000" \
-d {
    "clientTransactionId": "111112314",
    "collectorNumber": "80085102028",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": [
        "coupon"
    ],
    "deviceId": "string",
    "issuances": [
        {
            "issuanceOfferCode": "STANDARD",
            "locationCode": "0037",
            "milesAmount": 8,
            "offerDescription": "offer",
            "offerId": 22
        }
    ],
    "originalClientTransactionId": "12340001111",
    "sponsorCode": "KENY",
    "transactionDateTime": "2021-11-09T21:04:45.930Z"
}

Request parameters

* required field

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
{
    "clientTransactionId": "111112314",
    "collectorNumber": "80085102028",
    "coupon": [
        "coupon"
    ],
    "deviceId": "string",
    "issuances": [
        {
            "issuanceOfferCode": "STANDARD",
            "locationCode": "0037",
            "milesAmount": 8,
            "offerDescription": "offer",
            "offerId": "22",
            "status": "PENDING"
        }
    ],
    "originalClientTransactionId": "12340001111",
    "sponsorCode": "KENY",
    "transactionDateTime": "2021-11-11T12:54:31.780-05:00",
    "transactionId": "93a1237c-545c-4f16-96e5-4d890c903bd9"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.2.2.5 - RECORD

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

The RECORD endpoint is used to test and verify the transmission of transactions to AIR MILES - this includes both Collector and non-Collector transactions. This endpoint can be used initially to test and verify that the API integration is working as expected.

API call validation process

After making a call to RECORD, you will receive one of the following responses:

If the call is SUCCESSFUL

• You will receive a response code of 200
• No further action is required

If the call is REJECTED due to incorrect or invalid details

• You will receive a response code of 400
• You must retry the request with a valid transaction record and/or the corrected details

If the call FAILS due to an error or other issue

• You will receive a response code of 500
• It’s recommended you retry the request at least 2 additional times

Sample request

curl -X POST https://cert.airmilesapis.ca/checkout/issuance/record \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ..." \
-H "Content-Type: application/json" \
-d {
    "basketGSTAmount": 0,
    "basketPSTAmount": 0,
    "basketHSTAmount": 3.25,
    "basketQSTAmount": 0,
    "basketPreTaxAmount": 24.97,
    "basketPostTaxAmount": 28.22,
    "checkoutDateTime": "2019-05-30T14:12:59.479Z",
    "checkoutTransactionId": "12340001111",
    "collectorNumber": "81111111111",
    "context": {"key1": "value1","key2": "value2"},
    "coupon": ["57841","57862"],
    "deviceId": "POS1",
    "issuances": [{
        "contributingItemIds": ["SKU1234","SKU1252"],
        "issuanceOfferCode": "STANDARD",
        "locationCode": "1100",
        "milesAmount": 5,
        "offerDescription": "Bonus Miles for Groceries.",
        "offerId": "123454"
      }],
      "items": [{
              "id": "SKU1234",
              "name": "Dog Food",
              "number": 1,
              "quantity": 2,
              "baseAmount": 9.99,
              "finalAmount": 19.98,
              "departmentId":"10001",
              "categoryId" : "11101"
          },
                {
              "id": "SKU1252",
              "name": "Potato Chips",
              "number": 2,
              "quantity": 1,
              "baseAmount": 4.99,
              "finalAmount": 4.99,
              "departmentId":"10001",
              "categoryId" : "11101"
          }],
    "locationCode": "1137",
    "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
    "sponsorCode": "KELL",
    "tender": ["CASH","CREDIT"],
    "transactionType": "RETURN"
}

Request parameters

* required field

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
{
  "basketGSTAmount": 0,
  "basketPSTAmount": 0,
  "basketHSTAmount": 3.25,
  "basketQSTAmount": 0,
  "basketPreTaxAmount": 24.97,
  "basketPostTaxAmount": 28.22,
  "checkoutDateTime": "2019-05-30T14:12:59.479Z",
  "checkoutTransactionId": "12340001111",
  "collectorNumber": "81111111111",
  "coupon": ["57841","57862"],
  "deviceId": "POS1",
  "issuances": [{
      "contributingItemIds": ["SKU1234", "SKU1252"],
      "issuanceOfferCode": "STANDARD",
      "locationCode": "1100",
      "milesAmount": 5,
      "offerDescription": "Bonus Miles for Groceries.",
      "offerId": "123454"
    }],
    "items": [{
            "id": "SKU1234",
            "name": "Dog Food",
            "number": 1,
            "quantity": 2,
            "baseAmount": 9.99,
            "finalAmount": 19.98,
            "departmentId":"10001",
            "categoryId" : "11101"
        },
              {
            "id": "SKU1252",
            "name": "Potato Chips",
            "number": 2,
            "quantity": 1,
            "baseAmount": 4.99,
            "finalAmount": 4.99,
            "departmentId":"10001",
            "categoryId" : "11101"
        }],
  "locationCode": "1137",
  "originalTransactionId": "d445b671-7a7f-490f-a3f8-adfc443408a5",
  "sponsorCode": "KELL",
  "tender": ["CASH","CREDIT"],
  "context": {"key1": "value1","key2": "value2"},
  "transactionId": "c4f6cd00-dd00-4aaf-9099-b0685ab710b3",
  "transactionType": "RETURN"
}

Response parameters

Only parameters unique to the Sample Response are listed below. For all other parameters, refer to the table above.

Status codes

Refer to our Audit report errors table for more information.

2.3 - AIR MILES Issuance API Docs

2.4 - OpenAPI (Swagger-Spec)

3 - Member Banner

Allows your customers to check their AIR MILES account balances and details right from your mobile application or website.

Generating an Authorization Code

Generate an Authorization Code by redirecting your customer to our universal login page.

Sample Authorization Request

<a href="https://oauth-cert.airmiles.ca/authorize?
    client_id=knPJldKv8ygPn56gZhdFEIZV27QevLkx&
    response_type=code&
    connection=member-pin-idp-recaptcha&
    redirect_uri=https://your_redirect_uri/callback&
    scope=memberbanner%20offline_access&
    audience=https://members.loyalty.com">
  Sign In
</a>

Sample Authorization Response

Once your customer authenticates themselves, a response will be sent to the redirect URI that includes an Authorization Code.

HTTP/1.1 302 Found
Location: https://your_redirect_uri/callback?code=6hgDftTGH656HEDLdfOPA43nmsR5GuqG

Generating an Access Token

An Access Token is required to communicate with the Member Banner API. To generate an Access Token (aka JSON Web Token), make an API request like the one shown below.

Sample Token Request

curl --request POST \
  --url 'https://oauth-cert.airmiles.ca/oauth/token' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=knPJldKv8ygPn56gZhdFEIZV27QevLkx' \
  --data-urlencode 'client_secret=lfgdFGDF456fFDFV4FdDFffdl7h8J43s' \
  --data-urlencode 'code=6hgDftTGH656HEDLdfOPA43nmsR5GuqG' \
  --data-urlencode 'redirect_uri=https://your_redirect_uri/callback'

Sample Token Response

If all goes well, you’ll receive a (HTTP 200) JSON response with a payload containing an access_token, refresh_token, id_token, and token_type.

{
  "access_token": "eyJz93a409sSwFG8kkIL2qsGHk4laUWw",
  "refresh_token": "GE5g5HJdbYb47HN358polTHdf3tHf3ra",
  "id_token": "eyKMD32ldkgfkDYKL4h6hf33edHGSDKk",
  "token_type": "Bearer"
}

JSON Web Token (JWT) structure

The JWT consists of three concatenated Base64url-encoded strings, separated by dots “.”.

Calling the Member Banner API

Finally, to display the Collector’s account details, make an API request using the Access Token received in the previous step.

Sample API Request

curl -X GET \
  `https://cert.airmilesapis.ca/member-profile/banner` \
  -H 'Authorization: Bearer eyJz93a409sSwFG8kkIL2qsGHk4laUWw' \

Sample API Response

If everything went as expected you should receive a JSON response that includes the Collector’s account details, as shown in the example below.

{
    "cardNumber": "84151103449",
    "memberId": "fbd651ea-af99-3a71-b0db-83d4feae087f",
    "firstName": "JIMMY",
    "tier": "Blue",
    "cashBalance": 10901,
    "dreamBalance": 849
}

Using a Refresh Token

Typically, a user needs a new access token when gaining access to a resource for the first time, or after the previous access token granted to them expires. A refresh token is a special kind of token used to obtain a renewed access token. You can request new access tokens until the refresh token is blacklisted. Applications must store refresh tokens securely because they essentially allow a user to remain authenticated forever.

To exchange the Refresh Token you received during authorization for a new Access Token, make a POST request to https://oauth-cert.airmiles.ca/oauth/token, using grant_type=refresh_token as seen in the example below.

Sample ‘Refresh Token’ Request

curl --request POST \
  --url 'https://oauth-cert.airmiles.ca/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data-urlencode 'client_id=knPJldKv8ygPn56gZhdFEIZV27QevLkx' \
  --data-urlencode client_secret=lfgdFGDF456fFDFV4FdDFffdl7h8J43s \
  --data refresh_token=YOUR_REFRESH_TOKEN

Sample ‘Refresh Token’ Response

If all goes well, you’ll receive an HTTP 200 response with a payload containing a new access_token, its lifetime in seconds (expires_in), granted scope values, and token_type. If the scope of the initial token included openid, then the response will also include a new id_token:

The response will include a new Access Token, its type, its lifetime (in seconds), and the granted scopes. The memberbanner scope should also be included in the response as well.

{
  "access_token": "eyJz93a409sSwFG8kkIL2qsGHk4laUWw",
  "scope": "memberbanner offline_access",
  "id_token": "eyKMD32ldkgfkDYKL4h6hf33edHGSDKk",
  "token_type": "Bearer"
}

AIR MILES Brand Guidelines

Our Brand Guidelines site is currently offline for ongoing updates and maintenance. In the meantime, please reach out to our ‘Brand Approvals’ team in the ‘Rewards & Marketing’ department, to request more information on website and application integration.

Contact information

• Email for Brand Approvals

  brandapprovals@loyalty.com

4 - Offer State

Target audience

This material is intended to be used by a Partner wishing to integrate with the AIR MILES Offer State API.

What is “Offer State”

Collectors can either load (i.e., opt-in to) offers through the AIR MILES mobile app/website (www.airmiles.ca), OR YOUR mobile app/website.

The Offer State API enables you to retrieve the Collector’s opt-in status for offers displayed within your mobile app or website, as well as update the opt-in status for an individual offer.

Service level objective

Please contact our Partner Support team for details on our Service Level Agreement (SLA).

Integration environments

There are two sets of environments used by partners to integrate with the AIR MILES API library. These environments are configured similarly for consistent production-level quality, whether the partner has deployed to production or is still performing non-production testing.

Your AMRP project team

In preparation for launch, an AIR MILES team is pulled together to assist Partners with integration and setup. This team will provide the following services:

• Consulting Partners on the best technical solution to support AIR MILES Issuance based on system compatibility.
• Providing guidance for assessing Partner requirements, data exchange methods, and reconciliation.
• As well as overseeing a broad range of activities to meet the requirements of launch, including:
  • Planning
  • Communications
  • Delivery
  • Execution
  • Monitoring

Commonly used acronyms

4.1 - Authentication & Authorization

For more information on “Auth0” and the various authentication flows, click the button below.

Which Authentication Flow Should I Use?

4.2 - API Library

This section includes the four (4) Offer State API endpoints listed below. Each page includes a brief description and suggested use-case, as well as request and response body code samples.

API endpoints

Health Check

Test and confirm that the Offer State API is up and ready to process requests.

state-reader/FIND

Used to return all offers that a Collector has opted-into/saved.

state-reader/GET

Used to return only the opted-in/saved offers from a list of submitted offers.

state-reader/COUNT

Used to return the total number of offers a Collector has opted-into/saved.

state-writer/PUT

Used to update the Collector’s opt-in status for an AIR MILES offer.

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.

Response codes

4.2.1 - Health Check

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

This test endpoint ensures there are no known connectivity issues between AIR MILES and our partners. The HEALTH call functions similarly to a standard “ping” request, determining if a client or host is online and accessible.

Sample request

curl -X GET \
  https://cert.airmilesapis.ca/offers/state-reader/health \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCI...' \
  --header 'Channel-Code: MOBAPP' \
  --header 'Accept-Language: EN'

Header parameters

Sample response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 29 Oct 2019 15:27:34 GMT
[
  {
    "healthy": true,
    "timestamp": "2022-08-18T19:00:53.151Z"
  }
]

4.2.2 - state-reader/FIND

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

Used to return all offers that a Collector has opted-into/saved, for display within a “My Saved Offers” section of your mobile app or website.