API Library
Table of contents
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
Includes the API endpoints CALCULATE, ISSUE, RETURN, and RECORD.
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.
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.
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.
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. |
Response code descriptions
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request succeeded, but still processing… |
| 400 |
Request failed, bad request. |
| 500 |
Request failed, internal error. |
Error code descriptions
| Error Code |
Status Code |
Display Message |
Description |
| 202 |
202 |
Location Code Not Provided |
The request is missing a location code. |
| 203 |
202 |
Offer Code Not Found |
The Issuance offer code does not exist. |
| 204 |
202 |
Offer Code Expired |
The Issuance offer code has expired. |
| 205 |
202 |
Location Code Inactive |
The location code is not currently active. |
| 207 |
202 |
Invalid Unit Miles |
Miles do not match the allowable ‘Unit Mileage’. |
| 208 |
202 |
Invalid Variable Miles |
Miles exceed the allowable ‘Variable Mileage’. |
| 221 |
400 |
Sponsor Code Not Found |
The Sponsor code you entered does not exist. |
| 224 |
400 |
Collector Account Closed |
The requested Collector account has been closed. |
| 225 |
202 |
Sponsor Code Expired |
The requested Sponsor code has expired. |
| 230 |
202 |
Location Code Not Found |
The location code does not exist. |
| 232 |
400 |
Collector Account Deleted |
The requested Collector has been deleted from the system. |
| 234 |
400 |
Collector Account Not Found |
The requested Collector does not exist. |
| 000 |
202 |
Unknown |
The Issuance is pending due to unknown error. |
1 - AMRP Calculated Endpoints
Includes the API endpoints CALCULATE, ISSUE, RETURN, and RECORD.
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.
1.1 - CALCULATE
Used to calculate how many Miles to issue for all eligible items in the basket.
POST
/checkout/issuance/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.
Important
You do not need to make a
CALCULATE call prior to making an
ISSUE call. The
CALCULATE call is only required if you want to see how many Miles would be issued for an item (or items), but don’t want to issue those Miles.
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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
Example:
[{"id": "SKU1234","name": "Dog Food","number": "1"}]
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
originalTransactionId |
This value represents the transactionId returned in the ISSUE transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the Partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
transactionType* |
Transaction Type can be PURCHASE (ISSUE) or RETURN.
|
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.
| Parameter |
Description |
issuances |
This optional object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- issuanceOfferCode
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
1.2 - ISSUE
Used to calculate and issue Miles to a Collector for all eligible items in the basket.
POST
/checkout/issuance/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.
Important
You do not need to make a
CALCULATE call prior to making an
ISSUE call. The
CALCULATE call is only required if you want to see how many Miles would be issued for an item (or items), but don’t want to issue those Miles.
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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
WARNING
While a transaction is being processed for a Collector, DO NOT attempt to process an additional transaction in parallel for the same Collector. This will result in an error.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", status: "confirmed"}]
- confirmationNumber
- The UUID generated after processing an issuance request.
- Example:
"0ed100a4-fc9a-41bb-a747-942c2593b683"
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- errors
- Errors that occur during an issuance transaction.
- Example -
errorCode): "CollectorNotFound"
- Example -
errorReason): "The requested collector does not exist."
- Click here to view the "Error Codes" table
- issuanceOfferCode
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
- processedDateTime
- The date/time (see ISO-8601) that Miles were issued to the Collector.
- Example:
"2019-05-30T14:12:59.479Z"
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
1.3 - RETURN
Used to recalculate the Miles earned for each item in the basket, then withdraws the Miles for the returned items.
POST
/checkout/issuance/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.
Important
You do not need to make a
CALCULATE call prior to making an
ISSUE call. The
CALCULATE call is only required if you want to see how many Miles would be issued for an item (or items), but don’t want to issue those Miles.
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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
WARNING
While a transaction is being processed for a Collector, DO NOT attempt to process an additional transaction in parallel for the same Collector. This will result in an error.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
originalTransactionId* |
This value represents the transactionId returned in the ISSUE transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the Partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
|
sponsorCode* |
Alpha-numeric value used to identify the partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", status: "confirmed"}]
- confirmationNumber
- The UUID generated after processing an issuance request.
- Example:
"0ed100a4-fc9a-41bb-a747-942c2593b683"
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- errors
- Errors that occur during an issuance transaction.
- Example -
errorCode): "CollectorNotFound"
- Example -
errorReason): "The requested collector does not exist."
- Click here to view the "Error Codes" table
- issuanceOfferCode
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
- processedDateTime
- The date/time (see ISO-8601) that miles were issued to the Collector.
- Example:
"2019-05-30T14:12:59.479Z"
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
1.4 - RECORD
Used to test and verify the transmission of transactions to AIR MILES.
POST
/checkout/issuance/record
Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.
Note
This API call DOES NOT issue Miles to Collectors.
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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
originalTransactionId |
This value represents the transactionId returned in the ISSUE transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the partner in an ISSUE transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
transactionType* |
Transaction Type can be PURCHASE or RETURN.
|
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.
| Parameter |
Description |
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
2 - Partner Calculated Endpoints
Includes the API endpoints POST, POST/EVENT, REVERSE, REVERSE/EVENT, and RECORD.
Important
The APIs listed here require the partner to calculate and process the transactions themselves. If you are a smaller business who either doesn’t have the infrastructure or doesn’t wish to send us a monthly detailed transaction log, you may be better suited for our
AMRP calculated APIs.
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.1 - POST
Used to issue Miles to a Collector’s account in real-time for a basket transaction at checkout.
POST
/checkout/issuance/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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
issuances* |
This mandatory object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- issuanceOfferCode*
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount*
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId*
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", "status": "confirmed"}]
- confirmationNumber
- The UUID generated after processing an issuance request.
- Example:
"0ed100a4-fc9a-41bb-a747-942c2593b683"
- errors
- Errors that occur during an issuance transaction.
- Example -
errorCode): "CollectorNotFound"
- Example -
errorReason): "The requested collector does not exist."
- Click here to view the "Error Codes" table
- processedDateTime
- The date/time (see ISO-8601) that miles were issued to the Collector.
- Example:
"2019-05-30T14:12:59.479Z"
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
2.2 - POST/EVENT
Used to issue Miles to a Collector’s account in real-time for a non-transactional reason.
POST
/checkout/issuance/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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
clientTransactionId* |
Unique identifier generated by the Partner for the event transaction.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
issuances* |
This mandatory object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- issuanceOfferCode*
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount*
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId*
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
transactionDateTime* |
The date and time the request was sent.
Example: "2021-11-09T21:04:45.930Z"
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"status": "PENDING"}]
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
2.3 - REVERSE
Used to reverse Miles from a Collector’s account for returns or corrections.
POST
/checkout/issuance/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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the Partner for the transaction at checkout.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
issuances* |
This mandatory object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- issuanceOfferCode*
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount*
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId*
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax). Click below to see additional details on the data object’s elements, including their descriptions and examples.
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
originalTransactionId |
This value represents the transactionId returned in the POST/EVENT transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"confirmationNumber: 0ed100a4-fc9a-41bb-a747-942c2593b683", "status": "confirmed"}]
- confirmationNumber
- The UUID generated after processing an issuance request.
- Example:
"0ed100a4-fc9a-41bb-a747-942c2593b683"
- errors
- Errors that occur during an issuance transaction.
- Example -
errorCode): "CollectorNotFound"
- Example -
errorReason): "The requested collector does not exist."
- Click here to view the "Error Codes" table
- processedDateTime
- The date/time (see ISO-8601) that miles were issued to the Collector.
- Example:
"2019-05-30T14:12:59.479Z"
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
2.4 - REVERSE/EVENT
Used to reverse Miles from a Collector’s account in real-time for a non-transactional reason.
POST
/checkout/issuance/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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
clientTransactionId* |
Unique identifier generated by the Partner for the event transaction.
|
collectorNumber* |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
issuances* |
This mandatory object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- issuanceOfferCode*
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount*
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId*
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
originalClientTransactionId |
This value represents the clientTransactionId returned in the POST/EVENT transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
transactionDateTime* |
The date and time the request was sent.
Example: "2021-11-09T21:04:45.930Z"
|
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.
| Parameter |
Description |
issuances |
Array value describing the issuance offers redeemed by the Collector.
Example:
[{"status": "PENDING"}]
- status
- The status of the transaction. (Statuses include:
PENDING, CONFIRMED, REJECTED)
- Example:
"CONFIRMED"
|
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 202 |
Request still processing, please wait. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |
2.5 - RECORD
Used to test and verify the transmission of transactions to AIR MILES.
POST
/checkout/issuance/record
Take a look at our OpenAPI (Swagger-Spec) schema to learn more about the API calls.
Note
This API call DOES NOT issue Miles to Collectors.
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
Note
The “FAIL” response above could indicate a system error on our end. If this happens, please contact our
Support Desk for assistance.
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
| Parameter |
Description |
basketGSTAmount |
The dollar amount of GST (Government Sales Tax) to be added.
|
basketHSTAmount |
The dollar amount of HST (Harmonized Sales Tax) to be added.
|
basketPSTAmount |
The dollar amount of PST (Provincial Sales Tax) to be added.
|
basketQSTAmount |
The dollar amount of QST (Quebec Sales Tax) to be added.
|
basketPostTaxAmount* |
The total dollar amount of the basket, POST-TAX (i.e., what the Collector spent at checkout).
|
basketPreTaxAmount* |
The total dollar amount of the basket, PRE-TAX (i.e., before taxes are calculated and added to the total).
|
checkoutDateTime* |
Standard date/time format for the transaction at checkout. (see ISO-8601)
Examples: "2019-05-30T14:12:59.479Z""1972-07-16T13:32:05.234+04:00"
|
checkoutTransactionId* |
Unique identifier generated by the partner for the transaction at checkout.
|
collectorNumber |
The customer’s AIR MILES account number.
Must be 11 digits in length and must start with an 8 |
context |
Notes or additional information that is desired on each request as a key value pair.
Example: {"key1": "value1","key2": "value2"}
|
coupon |
A list of all coupon codes applied to the bill at checkout.
Example: ["57841","57862"]
|
deviceId |
ID number used to identify the POS terminal currently in use.
|
issuances |
This optional object contains data elements related to issuance data.
Example:
[{"issuanceOfferCode": "STANDARD","locationCode": "1100"}]
- contributingItemIds
- Basket item SKUs that contributed for the Issuance.
- Example:
"SKU123"
- issuanceOfferCode*
- The offer code that miles are issued against. This is the offer code that is setup by the Partner and AIR MILES for the
sponsorCode in the transaction.
- Example:
"STANDARD"
- locationCode
- A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
- Example:
ST90
- milesAmount*
- The number of miles to be issued to the Collector.
- Example:
2
- offerDescription
- The description of the offer that the issuance is based on.
- Example:
"This is a sample description."
- offerId*
- The identifier for an offer in the Partner's system. This can be the same value as your
issuanceOfferCode OR an internal marketing code shared with AIR MILES.
- Example:
"11234"
|
items |
This optional object contains data elements related to purchase details, including the list of item(s) purchased, their quantity, individual price, and total amount paid (pre-tax).
Example:
[{"id": "SKU1234","name": "Dog Food"}]
- id*
- The basket item's SKU.
- Example:
"1234"
- name*
- The name of the item.
- Example:
"Dog food"
- number*
- The order in which items were added to the basket.
- Example:
2
- quantity*
- The quantity of an item in the basket.
- Example:
3
- baseAmount*
- The pre-tax dollar amount for a single quantity of an item in the basket.
- Example:
9.99
- finalAmount*
- The pre-tax dollar amount for all identical items in the basket (i.e.,
baseAmount x quantity).
- Example:
29.97
- departmentId
- This field is mapped to a department value you would use to issue bonus miles at a department level
- Example:
10001
- categoryId
- This field is mapped to a category value you would use to issue bonus miles at a category level
- Example:
CAT2
|
locationCode |
A maximum of four alpha-numeric characters created by the Partner and used to identify the Partner’s location.
|
originalTransactionId |
This value represents the transactionId returned in the POST/EVENT transaction response from AIR MILES. Alternatively the checkoutTransactionId supplied by the Partner in an POST transaction can be sent in this field.
Example: "d445b671-7a7f-490f-a3f8-adfc443408a5"
|
sponsorCode* |
Alpha-numeric value used to identify the Partner.
To be provided by AIR MILES |
tender |
The method of payment used to pay for the transaction at checkout.
Example: ["CASH","CREDIT"]
|
transactionType* |
Transaction Type can be PURCHASE or RETURN.
|
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.
| Parameter |
Description |
transactionId |
A unique ID created for the particular transaction.
Example: "c4f6cd00-dd00-4aaf-9099-b0685ab710b3"
To be provided by AIR MILES |
Status codes
Refer to our Audit report errors table for more information.
| Status Code |
Description |
| 200 |
Request processed successfully. |
| 400 |
Bad request, failed to process. |
| 500 |
Request failed due to internal error. |