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

Or, return to the page.

Transaction History

Allows you to obtain the transaction history for a specific Collector.
Table of contents

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

Target audience

This material is intended to be used by a partner wishing to integrate with the Transaction History API.

Service level objective

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

Integration environments

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

Environment Domain Description
Certification https://cert.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.

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 AirMilesLoyaltyInc: 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.

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 three (3) Transaction History API endpoints listed below. Each page offers a brief summary of the API endpoint in question, common use-case scenarios, and sample request/response messages with response codes.

API endpoints

    Health Check

    Test and confirm that the Transaction History API is up and ready to process requests.

    Collector Request

    Retrieve the transaction history for a logged in Collector.

    Sponsor Request

    Retrieve the transaction history for a specified Collector number and filter by sponsor.

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.

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.
  • Status codes

    Status Code Description
    200 The transaction was successful.
    401 The Collector account is not active.
    408 The transaction timed out.
    401 The Collector number is invalid.
    400 A mistake was made when submitting the request. Please correct the error and try again.
    503 The system is unavailable due to scheduled maintenance. No requests can be sent.
    500 An unknown error occurred
    none No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

    2.1 - Health Check

    Test and confirm that the Transaction History API is up and ready to process requests.
    GET /transaction-history/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.

    Sample request

    curl -X GET 
      https://cert.airmilesapis.ca/transaction-history/health \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsI...' \
      --header 'Channel-Code: MOBAPP' \
      --header 'Accept-Language: EN'
    

    Header parameters

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

    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
    {
        "status": "up"
    }
    

    Status codes

    Status Code Description
    200 The transaction was successful.
    408 The transaction timed out.
    400 A mistake was made when submitting the request. Please correct the error and try again.
    503 The system is unavailable due to scheduled maintenance. No requests can be sent.
    500 An unknown error occurred.
    none No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

    2.2 - Collector Request

    Retrieve the transaction history for a logged in Collector.
    GET /transaction-history/cards

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

    This endpoint is used to retrieve the transaction history for a Collector who is logged in to the website or the mobile application. A date range must be provided (with a start and end-date), and this will return results for all sponsors the Collector has transacted with during this time period.

    Sample request

    curl -X GET \
      https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc \
      --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.
    Channel-Code Channel by which the transaction is called. The response will differ for different channels.
    Accept-Language Language parameters, either “EN” for English or “FR” for French.

    Query parameters

    Parameter Description
    from The start of the search date range. (The date range is limited to 2 years)
    to The end of the search date range. (The date range is limited to 2 years)
    page The results page to start with.
    size The number of transactions per page.
    sort Sort by field, ascending or descending. You can include up to 3 sequential sort parameters.

    Sample response

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8
    Transfer-Encoding: chunked
    Date: Mon, 29 Oct 2019 15:27:34 GMT
    {
      "_embedded": {
        "genericActivityDtoList": [
          {
            "transactionId": "bfc52daa-b1ec-44fb-b8e2-babc6f93395e",
            "memberId": 80000000001,
            "cardNumber": "80000000001",
            "activityType": "ISSUANCE",
            "transactionDate": "2019-01-20T13:15:57.000Z",
            "postingDate": "2019-03-20T13:15:57.000Z",
            "transactionDescription": "P&S Goodwill",
            "transactionValue": 50,
            "cashMiles": 44,
            "dreamMiles": 6,
            "cashRatio": 0.88,
            "dreamRatio": 0.12,
            "externalReferenceNumber": "07753481468",
            "externalReferenceType": null,
            "channel": "ETS",
            "initiatorId": "ETSets_user",
            "sponsorCode": "AIRI",
            "sponsorDescriptionEnglish": "AIR MILE TRAVEL INSURANCE",
            "sponsorDescriptionFrench": "ASSURANCE VOYAGE AIR MILES",
            "offerClass": "BONUS",
            "offerCode": "GOODWILL",
            "offerDescriptionEnglish": "P&S Goodwill",
            "offerDescriptionFrench": "AJUSTEMENT",
            "locationCode": "",
            "locationDescription": "",
            "redemptionStatus": null
          },
          {
            "transactionId": "a27c7827-a865-4425-a407-d1969b3ddfc5",
            "memberId": 80000000001,
            "cardNumber": "80000000001",
            "activityType": "ISSUANCE",
            "transactionDate": "2019-01-07T17:03:49.000Z",
            "postingDate": "2019-03-01T17:03:49.000Z",
            "transactionDescription": "AIR MILES Travel Insurance",
            "transactionValue": 50,
            "cashMiles": 14,
            "dreamMiles": 36,
            "cashRatio": 0.29,
            "dreamRatio": 0.71,
            "externalReferenceNumber": "96561512670",
            "externalReferenceType": null,
            "channel": "ETS",
            "initiatorId": "ETSets_user",
            "sponsorCode": "AIRI",
            "sponsorDescriptionEnglish": "AIR MILE TRAVEL INSURANCE",
            "sponsorDescriptionFrench": "ASSURANCE VOYAGE AIR MILES",
            "offerClass": "BONUS",
            "offerCode": "TSRTRIPC",
            "offerDescriptionEnglish": "AIR MILES Travel Insurance",
            "offerDescriptionFrench": "RECLAMATION D'ASSURANCE",
            "locationCode": "",
            "locationDescription": "",
            "redemptionStatus": null
          }
        ]
      },
      "_links": {
        "first": {
          "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
        },
        "self": {
          "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
        },
        "next": {
          "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=1&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
        },
        "last": {
          "href": "https://cert.airmilesapis.ca/transaction-history/cards?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=22&size=2&sort=transactionDate,desc&sort=sponsorCode,asc"
        }
      },
      "page": {
        "size": 2,
        "totalElements": 45,
        "totalPages": 23,
        "number": 0
      }
    }
    

    Status codes

    Status Code Description
    200 The transaction was successful.
    401 The Collector account is not active.
    408 The transaction timed out.
    401 The Collector number is invalid.
    400 A mistake was made when submitting the request. Please correct the error and try again.
    503 The system is unavailable due to scheduled maintenance. No requests can be sent.
    500 An unknown error occurred.
    none No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

    2.3 - Sponsor Request

    Retrieve the transaction history for a specified Collector number and filter by sponsor.
    GET /transaction-history/sponsors

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

    This endpoint is used to retrieve the transaction history for a specified Collector and filtered by sponsor. A date range must be provided (with a start and end-date), and at least one sponsor and a single Collector number. This will return the Collector’s transaction history at the sponsor, for the time period specified above.

    Sample request

    curl -X GET \
      https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001 \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCI...' \
      --header 'Channel-Code: MOBAPP' \
      --header 'Accept-Language: EN'
    

    Header parameters

    Parameter Description
    Content-Type
    Authorization Token from authentication.
    Channel-Code Channel by which the transaction is called. The response will differ for different channels.
    Accept-Language Language parameters, either “EN” for English or “FR” for French.

    Query parameters

    Parameter Description
    from The start of the search date range. (The date range is limited to 2 years)
    to The end of the search date range. (The date range is limited to 2 years)
    page The results page to start with.
    size The number of transactions per page.
    sort Sort by field, ascending or descending. You can include up to 3 sequential sort parameters.
    sponsorList The ID(s) of the sponsor(s) you wish to search by. (You may include multiple sponsors, comma delineated)
    collectorNumber The Collector number you wish to search for.

    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
    {
      "_embedded": {
        "genericActivityDtoList": [
          {
            "transactionId": "a8354c14-6533-4550-b25d-b3e8c07340e3",
            "memberId": 80000000001,
            "cardNumber": "80000000001",
            "activityType": "ISSUANCE",
            "transactionDate": "2018-11-21T21:55:07",
            "postingDate": "2018-12-08T21:55:07",
            "transactionDescription": "MILLES DE RECOMPENSE EN PRIME",
            "transactionValue": 6,
            "cashMiles": 3,
            "dreamMiles": 3,
            "cashRatio": 0.56,
            "dreamRatio": 0.44,
            "externalReferenceNumber": "66367295746",
            "externalReferenceType": null,
            "channel": "WEB",
            "initiatorId": "WEB423672",
            "sponsorCode": "AMXJ",
            "sponsorDescriptionEnglish": "AMEX AIR MILES BUSINESS",
            "sponsorDescriptionFrench": "CARTE POUR ENTREPRISE AMEX",
            "offerClass": "BONUS",
            "offerCode": "MPOOL",
            "offerDescriptionEnglish": "WELCOME BONUS",
            "offerDescriptionFrench": "MILLES DE RECOMPENSE EN PRIME",
            "locationCode": "",
            "locationDescription": null,
            "redemptionStatus": null
          },
          {
            "transactionId": "2cd4b826-6f7a-4e93-87ac-82c215bd8fe5",
            "memberId": 80000000001,
            "cardNumber": "80000000001",
            "activityType": "ISSUANCE",
            "transactionDate": "2018-11-06T20:33:54",
            "postingDate": "2018-11-26T20:33:54",
            "transactionDescription": "GAGNANT(E) DU CONCOURS",
            "transactionValue": 6,
            "cashMiles": 2,
            "dreamMiles": 4,
            "cashRatio": 0.37,
            "dreamRatio": 0.63,
            "externalReferenceNumber": "14493747740",
            "externalReferenceType": null,
            "channel": "BATCH",
            "initiatorId": "BATCH707530",
            "sponsorCode": "AMRP",
            "sponsorDescriptionEnglish": "AIR MILES REWARD PROGRAM",
            "sponsorDescriptionFrench": "PROGRAMME DE RECOMPENSE AIR MILES",
            "offerClass": "BONUS",
            "offerCode": "4352932T",
            "offerDescriptionEnglish": "Contest Winner",
            "offerDescriptionFrench": "GAGNANT(E) DU CONCOURS",
            "locationCode": "0705",
            "locationDescription": "TRANSAT",
            "redemptionStatus": null
          }
        ]
      },
        "_links": {
        "first": {
          "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
        },
        "self": {
          "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=0&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
        },
        "next": {
          "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=1&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
        },
        "last": {
          "href": "https://cert.airmilesapis.ca/transaction-history/sponsors?from=2018-01-01T00:16:45.052035Z&to=2019-10-01T00:16:45.052035Z&page=9&size=2&sort=transactionDate,desc&sort=sponsorCode,asc&sponsorList=ABC,CBA&collectorNumber=80000000001"
        }
      },
      "page": {
        "size": 2,
        "totalElements": 19,
        "totalPages": 10,
        "number": 0
      }
    }
    

    Status codes

    Status Code Description
    200 The transaction was successful.
    401 The Collector account is not active.
    408 The transaction timed out.
    401 The Collector number is invalid.
    400 A mistake was made when submitting the request. Please correct the error and try again.
    503 The system is unavailable due to scheduled maintenance. No requests can be sent.
    500 An unknown error occurred.
    none No valid Bearer token present. Please generate a valid Bearer token and submit to continue.

    3 - OpenAPI (Swagger-Spec)