Retrieve Transactions API Documentation

v1Showing ATRP specific information

The Retrieve Transactions endpoint provides a partner with the ability to retrieve Avios transactions (credits and debits) for an identified member’s account. A partner consuming this service will be able to return either the most recent transactions, or a subset of any of the transactions for the account in question.

The Retrieve Transactions API requires the Partner to have generated an access token for the member prior to invocation. This access token must be included in any request message along with other data elements relating to the partner’s configuration. The remainder of this document describes the request and response messages, the correct use of the service and possible exceptions and error states that may present in the response.

Business Context

Here’s the process flow:

Retrieve Transactions Flow

  • An identified member, for whom the partner has a valid access token, initiates a journey in the partner application that requires the member’s Avios transaction data.
  • The partner receives the member’s request and invokes the Retrieve Transactions endpoint, providing a request that contains the member’s access token, membership number and data elements that identify the partner.
  • The Retrieve Transactions endpoint receives and processes the request, returning an appropriate response or error.
  • Partner finalises processing of transactions, presenting these in an appropriate manner to the member.
  • Member continues their journey in the partner application.

Technical Context

Important Technical Notes

  • Request elements are not stored.
  • All enumerated values must be upper case.
  • Elements in the response message will always be returned in upper case ASCII.
  • All query parameters must be supplied in lower case.

Pre-conditions

  • An Access Token, generated at the point of Member login via Create Token endpoint must be supplied in the request when invoking this service.
  • Partner needs a valid API key to access this endpoint.

Post-conditions

Success outcome: Transaction details are returned in the endpoint response message.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

'GET https://api.avios.com/{version}/programmes/{programme-identifier}/accounts/{account-identifier}/transactions?api_key={api_key}'

Example URI

https://api.avios.com/v1/programmes/ATRP/accounts/3081470000000000/transactions?api_key=abcdef
NameTypeDescriptionExample
version
Required
StringThe version of the API which will be confirmed during the on-boarding process.
Format: Alphanumeric. v
v1
programme-identifier
Required
StringThe identifier for the loyalty programme to which the member belongs. This will have been provided to the member as part of the Loyalty Programme API partner on-boarding process along with your API key and Mashery credentials.
Format: Currently restricted to ATRP.
ATRP
account-identifier
Required
NumericUnique Identifier of the member of the loyalty programme. Example: membership number
Format: Min length = 1.Max Length = 24. Numeric only.
3081470000000000
api_key
Required
StringThe partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process.
Format: Alphanumeric. Min length = 24. Max Length = 24.
abcdef

Request Headers

NameTypeDescriptionExample
Accept
Optional
StringThe Accept request-header field specifies certain media types, which are acceptable for the response.
Format: Currently restricted to application/json
application/json
Authorization
Required
StringThe Access Token returned from a successful Create Token API call. The Access Token is issued on a per Partner, per Member basis at the point of successful Member Identification.
Format: JWT Token
X-Forwarded- For
Optional
StringIdentifies the originating IP address of a consumer.
Format: IP address
172.128.25.24

Request Elements

The following shows examples of request calls to the Retrieve Transactions endpoint:

Without Query Parameters:

https://api.avios.com/test/v1/programmes/ATRP/accounts/3081471017300186/transactions?api_key=xxx

With Range Filter:

https://api.avios.com/test/v1/programmes/ATRP/accounts/3081471017300186/transactions?api_key=xxx&start-record=1&end-record=10&date-made-from=2016-01-01&date-made-to=2016-09-01

With Range and match Filter:

https://api.avios.com/test/v1/programmes/ATRP/accounts/3081471017300186/transactions?api_key=xxx&start-record=1&end-record=10&date-made-from=2016-01-01&date-made-to=2016-09-02&external-source=Lloy
NameTypeDescription
start-record
Optional
IntegerIndex of the first item in the range of transactions returned in the service response. Filters from the latest transaction. Example: 1
Format: Numeric only. Max numeric value = 99999, min numeric value = 1.
end-record
Optional
IntegerIndex of the last item in the range of transactions returned in the service response. Filters from the latest transaction. Example: 6
Format: Numeric only. Max numeric value = 99999, min numeric value = 1.
date-made-from
Optional
DateThe date of the first item in the range of transactions returned in the service response. Example: 2016-01-04
Format: format (YYYY-MM-DD)
date-made-to
Optional
DateThe date of the last item in the range of transactions returned in the service response. Won't include last day transactions. Example: 2016-02-02, transactions only till period 2016-02-01 23:59:59 will be returned.
Format: format (YYYY-MM-DD)
external-source
Optional
StringThe partner name related to the transaction. This is case insensitive. Currently doesn't filter by partner name. API returns all transactions and ignores value supplied.
Format: String of max length 10

Response Elements

Example Response:

Without Query Parameters:

{
  "transaction": [
    {
      "creditTransaction": {
        "identifier": "6965162461003",

With Range Filter:

{
  "transaction": [
    {
      "debitTransaction": {
        "identifier": "395079D03F46027BE050A8C0020A62BD",

With range and match filter:

{
  "transaction": [
    {
      "creditTransaction": {
        "identifier": "6965162461003",
NameTypeDescription
transaction
Conditional
Array of Complex type 0..1A complex type that acts as a container for a number of credit transactions and debit transactions, which in turn express the results of the request including the applied filter parameters. Will not be present if member won’t contain any transactions or transactions are filtered out by the request elements.
Transaction.debitTransaction
Conditional
Array of Complex type 0..nA complex type that represents a member’s debit transaction, there may be many of these returned within a single response. Will not be present if member won’t contain any debit transactions or transactions are filtered out by the request elements. API won’t return debit transaction details which debit amount exceeds value of 6 digits. E.g. if debit transaction amount is 1000000 it will not be returned.
Transaction.debitTransaction.identifier
Present
StringThe unique identifier of the debit transaction within Avios systems.
Format: Alphanumeric. Max length: 32
Transaction.debitTransaction.dateMade
Present
DateThe date that has been stored against the transaction. Example: 2016-10-20T10:23:23.000Z
Format: YYYY-MM-DDThh:mm:ss.sTZD
transaction.debitTransaction.description
Present
StringA description of the debit transaction. Example: DESC ERI
Format: Alphanumeric with special characters~!@#\$%^&
transaction.debitTransaction.externalReferenceIdentifier
Present
StringThe Avios internal transaction reference related to this debit transaction. It is randomly generated by AVIOS system. Example: 14426D
Format: Alphanumeric only. Max length: 10
transaction.debitTransaction.amount
Present
Complex type 1..1A Complex Type, which represents the transaction amount.
Transaction.debitTransaction.amount.amount
Present
Big decimalThe transaction amount, in Avios, expressed as a numeric. Example: 1
Format: Numeric. Max length: 6
transaction.debitTransaction.amount.formattedAmount
Present
StringThe transaction amount formatted as specified by the currency code as a String value. Will contain only numbers.
Format: Alphanumeric. Max length: 6
Transaction.debitTransaction.amount.currency
Present
Complex type 1..1A complex type, which represents the specific currency of a transaction.
Transaction.debitTransaction.amount.currency.currencyCode
Present
StringLoyalty programme currency identifier. At present only ‘AVIOS’ is supported. Example: AVIOS
Format: Enumeration
transaction.creditTransaction
Conditional
Array of Complex type 0..nA complex type that represents a member’s credit transaction, there may be many of these returned within a single response. Will be present if member contains credit transactions or transactions are filtered out by the request elements.
Transaction.creditTransaction.identifier
Present
StringThe unique identifier of the credit transaction within Avios systems.
Format: Alpha numeric. Max length: 32
Transaction.creditTransaction.dateMade
Present
DateThis is the date that has been stored against the transaction. Example: 2016-10-20T10:23:23.000Z
Format: YYYY-MM-DDThh:mm:ss.sTZD
transaction.creditTransaction.description
Present
StringA description of the credit transaction. Example: JKL
Format: Alphanumeric with special characters. Min length: 1 Max length: 51 & . -
transaction.creditTransaction.externalSource
Present
StringThe partner name related to the transaction.
Format: Alphanumeric with special characters. Max length: 10 & . -
Transaction.creditTransaction.externalReferenceIdentifier
Present
StringThe partner’s reference for the credit transaction. Example: 14426D
Format: Alphanumeric with special characters. Max length: 10 & . -
transaction.creditTransaction.amount
Present
Complex type 1..1A Complex Type, which represents the transaction amount.
Transaction.creditTransaction.amount.amount
Present
Big decimalThe transaction amount, in Avios, expressed as a numeric. Example: 999999
Format: Max length: 6 Numeric
transaction.creditTransaction.amount.formattedAmount
Present
StringThe transaction amount formatted as specified by the currency code as a String value. Contains only numeric values.
Format: Max length: 6 Alphanumeric
Transaction.creditTransaction.amount.currency
Present
Complex type 1..1A complex type, which represents the specific currency of a transaction.
Transaction.creditTransaction.amount.currency.currencyCode
Present
StringLoyalty programme currency identifier. At present only ‘AVIOS’ is supported. Example: AVIOS
Format: Enumeration

Exception Message Elements

Error Response:

{
  "error": {
    "code": "REQUEST_INVALID",
    "businessMessage": "Request	Invalid",
    "developerLink": "https://developer.iagloyalty.com/docs",
NameTypeDescription
error
Conditional
Complex Type 0..1Will only be present if an error has been detected and reported by the API.
error.code
Present
StringError code. Example: REQUEST_INVALID
Format: Alphabetic plus under- score (
error.businessMessage
Present
StringA business level message describing the error, which has occurred. Example: Request invalid
Format: Alphabetic
error.developerMessage
Conditional
StringDeveloper message will be present when detailed technical description is required for the error, which has occurred by the API. If no specific developer message is required, developer message will be as business message.
Format: Alphabetic
error.developerLink
Present
StringA URL link to a web page containing more detailed information about the error code. Example: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (☺, oblique (.), dash (-), underscore (
error.childError
Conditional
Array of complex type 0..nPresent for certain errors (e.g. validation) where one or more child error may have occurred.
error.childError.code
Present
StringThe unique code for this error, described in section 5.3 of this document. Example: DATA_INVALID
Format: Alphabetic plus under- score (
error.childError.path
Conditional
StringPath of the node on which error occurred. This will not come in case of any of the authorisation header elements are invalid or missing. Example: member.person.name.firstName
Format: Alphabetic plus period (.), oblique (/), open bracket (
error.childError.businessMessage
Present
StringA business level message describing the error, which has occurred. Example: Data invalid
Format: Alphabetic
error.childError.developerMessage
Conditional
StringDeveloper message will be present when detailed technical description is required for the child error, which has occurred, by the API. E.g. in case of REQUEST_INVALID DATA_INVALID, it is required which data is invalid and what is invalid in the data.If no specific developer message is required, developer message will be as business message.
Format: Alphabetic
error.childError.developerLink
Present
StringA URL link to a web page containing more detailed information about the error code. Example: https://developer.iagloyalty.com/docs
Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (

Error Codes

The elements that make up the error messages are detailed in the following table:

HTTP Status CodeDescription
400
REQUEST_INVALID
DATA_INVALID
Request element doesn’t follow the request contract. For example the end-date is provided in bad format.
400
REQUEST_INVALID
DATE_RANGE_INVALID
When from date is greater than to date.
400
REQUEST_INVALID
RECORD_RANGE_INVALID
End record should be greater than start record.