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.

Note

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

What is an “Idempotency Key”

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

WARNING

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

Sample header with Idempotency

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

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.