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

Offer State

Update a Collector’s opt-in status for a given AIR MILES offer from within your mobile app or website.

Table of contents

1. Authentication & Authorization
2. API Library

2.1. Health Check
2.2. state-reader/FIND
2.3. state-reader/GET
2.4. state-reader/COUNT
2.5. state-writer/PUT

3. Offer State API Docs
4. OpenAPI (Swagger-Spec)

The purpose of this documentation is to provide a guide on how to integrate with the AIR MILES Offer State API. As part of this documentation, we also include information on RESTful HTTPS requests/responses, error codes, integration environments, and support contact information.

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.

Important

The most important parameter in this API call is the offerId. It must match an existing offerId in our system to successfully retrieve or update the opt-in status. This ensures everything stays synchronized between our system and yours.

Service level objective

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

Email Partner Support

Did you know

Our “Transaction Day” for real-time Issuance runs from 12:00AM to 11:59PM EST daily.

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.

Environment	Domain	Description
Test	https://uat.airmilesapis.ca	Contains production quality code and test data used for developing and testing 3rd party integrations.
Production	https://airmilesapis.ca	Contains production code and live user data for real-world 3rd party integrations.

Tip

ALL integration environments must be accessed via HTTPS only.

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

Name	Definition
L1	LoyaltyOne: Is the name of the parent organization that operates the AMRP.
AMRP	AIR MILES Rewards Program: The loyalty program itself consisting both AIR MILES issuance an redemption processes.
AMRM	AIR MILES Rewards Miles: The loyalty program currency that Collectors earn and redeem for travel, merchandise and cash rewards.
RTC	Real-Time Checkout: An AIR MILES API platform specifically tailored for “Real-Time Issuance” & redemption of AIR MILES “Reward Miles”.
M2M	Machine-to-Machine: Refers to direct communication between devices using any communications channel, including wired and wireless. This includes CLIs, daemons, or services running on your back-end that self-authenticates and/or authorizes an application without collector interaction.
POS	Point-of-Sale: Refers to the software/hardware component that handles transactional messages, as well as processing AIR MILES issuances and reversals (return transactions).

1 - Authentication & Authorization

The AIR MILES security layer granting access to member APIs and associated services.

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

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.

Note

Mandatory parameters/properties 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 codes

Code	Description
`200`/`204`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

2.1 - Health Check

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

GET /offers/state-reader/health

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.

Tip

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

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

Parameter	Description
Content-Type	Default value: `application/json`
Authorization	Token from authentication. Example: `Bearer <access_token>`
Channel-Code	Channel by which the transaction is called. The response will differ for different channels. Example: `MOBAPP`
Accept-Language	Language parameters, either “EN” for English or “FR” for French. Example: `EN`

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"
  }
]

2.2 - state-reader/FIND

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

GET /offers/state-reader/v1/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.

Sample request

curl -X GET 
  https://uat.airmilesapis.ca/offers/state-reader/v1/find?state=SAVE:SAVED \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2021-07-07T16:59:00' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Query parameters

Parameter	Description
`state`	The state types you want to retrieve. Example: `OPT_IN:OPTED_IN`
`partnerId`	The unique ID of the partner.
`region`	The Collector region.
`firstSortBy`	Level one, sort by type. Options: `displayPriority` `endDate` `mechanismPriority` (default)
`firstSortByDescending`	Level one, sort direction. Options: `true` (default) `false`
`secondSortBy`	Level two, sort type. Options: `displayPriority` `endDate` (default) `mechanismPriority`
`secondSortByDescending`	Level two, sort direction. Options: `true` (default) `false`
`pageNumber`	Page number of the results. Default: `1`
`pageSize`	How many offers listed on each page. Default: `20`

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
{
    "offers": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276917Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276825Z"
                }
            ]
        },
        {
            "offerId": "e32f35ad-3d32-439d-94db-8c36a40ddbd1",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201783Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201759Z"
                }
            ]
        },
        {
            "offerId": "0095056b-b931-4431-8292-cd54f4986445",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-21T14:53:47.293585Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-21T14:53:47.293537Z"
                }
            ]
        }
    ],
    "returnedCount": 3
}

Response properties

Property	Description
`offerId`	The unique ID for the returned offers. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`collectorId`	The Collector’s AIR MILES account number. Example: `"80000000110"`
`states`	The opt-in/saved status of the offers found for an individual Collector. Usually offers will show both the “Saved” and “Opt-in” statuses, but in certain scenarios, the Collector may have unsaved an offer they opted-into earlier. Example: `[{"name": "SAVE","value": "SAVED"}]` name The name of the state being returned. e.g., `"SAVE"` value The current state value. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}` updatedAt The date/time the offer state was last updated. (ISO-8601) e.g., `"2021-07-07T20:55:26.276825Z"`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

2.3 - state-reader/GET

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

GET /offers/state-reader/v1/get

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

Used to return only the opted-in/saved offers from a list of submitted offers. This is used to label which offers a Collector has opted-into/saved when displaying a full page of offers (which would includes both opted-in and non opted-in offers).

Sample request

curl -X GET 
  https://uat.airmilesapis.ca/offers/state-reader/v1/get?offerId=951d9a70-4cf8-41b1-a01e-7953f069f527&offerId=e32f35ad-3d32-439d-94db-8c36a40ddbd1&offerId=ebaa71b8-40d4-48dc-95e6-824dfffa1c4c \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2020-05-30T23:59:59' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Query parameters

Parameter	Description
`offerId`	The unique offer ID’s for all offers submitted. Example: `?offerId={OFFER_ID_1}&offerId={OFFER_ID_2}…`

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
{
    "offers": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276917Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-07-07T20:55:26.276825Z"
                }
            ]
        },
        {
            "offerId": "e32f35ad-3d32-439d-94db-8c36a40ddbd1",
            "collectorId": "80000000110",
            "states": [
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201783Z"
                },
                {
                    "name": "SAVE",
                    "value": "SAVED",
                    "properties": {},
                    "updatedAt": "2021-05-31T16:33:26.201759Z"
                }
            ]
        }
    ],
    "requestedCount": 3,
    "returnedCount": 2
}

Response properties

Parameter	Description
`offerId`	The unique ID for the offers returned by the `find` call. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`collectorId`	The Collector’s AIR MILES account number. Example: `"80000000110"` (Must be 11 digits in length and must start with an 8)
`states`	The opt-in/saved status of the offers found for an individual Collector. Example: `[{"name": "SAVE","value": "SAVED"}]` name The name of the state being returned. e.g., `"SAVE"` value The current state value. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}` updatedAt The date/time the offer state was last updated. (ISO-8601) e.g., `"2021-07-07T20:55:26.276825Z"`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

2.4 - state-reader/COUNT

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

GET /offers/state-reader/v1/count

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

Used to return the total number of offers a Collector has opted-into/saved. This is used for displaying a small numerical icon on a label or button within your website or mobile app.

Sample request

curl -X GET 
  https://cert.airmilesapis.ca/offers/state-reader/v1/count \
  --header 'Content-Type: application/json' \
  --header 'x-correlation-id: acd31d3c-f486-4092-9c07-1b82632829ed' \
  --header 'x-origin-client: external:partner:web' \
  --header 'x-local-time: 2021-07-07T23:59:59' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw ''

Query parameters

Parameter	Description
`state`	The state types you want to retrieve. Example: `OPT_IN:OPTED_IN`
`partnerId`	The unique ID of the partner.
`region`	The Collector region.

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
{
    "count": 3
}

Response properties

Property	Description
`count`	The total number of offers a Collector has opted-into/saved. Example: `3`

Response codes

Code	Description
`200`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

2.5 - state-writer/PUT

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

PUT /offers/state-reader/v1/put

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

Used to update the Collector’s opt-in status for an AIR MILES offer selected within your website or mobile app. This ensures that the Collector’s opt-in status is synchronized between your list of offers and the AIR MILES system.

Sample request

curl -X PUT 
  https://uat.airmilesapis.ca/offers/state-writer/v1/put \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'x-correlation-id: bcf529ae-0de0-4ded-90f5-e050ce2df0e3' \
  --header 'x-origin-client: external:partner:web' \
  --header 'Authorization: Bearer LQoD0gWJK7l9znrmsGksWxbvIEx9a8zXkw...' \
  --data-raw '{
    "stateChanges": [
        {
            "offerId": "951d9a70-4cf8-41b1-a01e-7953f069f527",
            "states": [
                {
                    "name": "SAVE",
                    "value": "SAVED"
                },
                {
                    "name": "OPT_IN",
                    "value": "OPTED_IN"
                }
            ]
        }
    ]
}'

Request headers

Header	Description
`Content-Type`	Indicates the media type of the resource.
`x-correlation-id`	The unique ID for tracing the request across the system.
`x-origin-client`	Name of the Client and Channel. Example: `external:shell:web`
`x-local-time`	Local time of the client, excluding the timezone. Example: `2021-01-07T16.59:00`

Request properties

* Required field

Property Description

Property	Description
`offerId`*	The unique ID for the offer being updated. Example: `"951d9a70-4cf8-41b1-a01e-7953f069f527"`
`states`*	The states being updated in the API `PUT` request. Example: `[{"name": "SAVE","value": "SAVED"}]` name* The name of the state being updated. e.g., `"SAVE"` value* The new state value being applied. e.g., `"SAVED"` properties An optional field which can be defined by the partner. (Note: This field is a string-to-any map which can map any string field to any value.) e.g., `{"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}`

offerId*

The unique ID for the offer being updated.

Example: "951d9a70-4cf8-41b1-a01e-7953f069f527"

states*

The states being updated in the API PUT request.

Example:

[{"name": "SAVE","value": "SAVED"}]

name*: The name of the state being updated.; e.g., "SAVE"
value*: The new state value being applied.; e.g., "SAVED"
properties: An optional field which can be defined by the partner.
(Note: This field is a string-to-any map which can map any string field to any value.); e.g., {"timesUsedOffer":5,"savedOnChannel":"internal:amrp:mobile"}

Sample response

HTTP/1.1 200 OK

Response codes

Code	Description
`204`	Request Successful
`400`	Bad Request
`401`	Unauthorized
`404`	Record Not Found
`500`	Internal Server Error

3 - Offer State API Docs

4 - OpenAPI (Swagger-Spec)