Retrieve Transactions API Documentation

v1Showing BAEC 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 endpoint 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 Account endpoint, providing a request that contains the member’s access token.
  • 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.
  • All query parameters must be supplied in lower case.

Pre-conditions

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/transactions?api_key={api_key}'

Example URI

https://api.avios.com/v1/programmes/BAEC/accounts/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 BAEC.
BAEC
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 OAUTH Access Token returned from a successful Authentication API call. The Access Token is issued on a per Partner, per Member basis at the point of successful Member Identification.
Format: Alphanumeric
Bearer 50663dcb
ba_client_applicationName
Required
StringName of the client application connecting to the BAEC members database. This name is the same for all partners.
Format: For all partners, the value should be AviosAPIPartners
AviosAPIPartners
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/BAEC/accounts/transactions?api_key=xxx

With Range Filter:

https://api.avios.com/test/v1/programmes/BAEC/accounts/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/BAEC/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. (Must be less than end-record) Example: 1
Format: Numeric only. Max numeric value = 20, 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 = 20, 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": {
        "dateMade": "2016-09-02",

With Range Filter:

{
  "transaction": [
    {
      "debitTransaction": {
        "identifier": "395079D03F46027BE050A8C0020A62BD",
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
Conditional
StringThe unique identifier of the debit transaction within Avios systems.
Format: Alphanumeric. Max length: 32
Transaction.debitTransaction.dateMade
Present
DateThe date when the Avios was added to the account – postedDate. Example: 2016-10-20
Format: YYYY-MM-DD
transaction.debitTransaction.description
Present
StringA description of the debit transaction. Example: DESC ERI
Format: Alphanumeric with special characters~!@#\$%^&
transaction.debitTransaction.externalReferenceIdentifier
Conditional
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
Conditional
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
Conditional
StringThe unique identifier of the credit transaction within Avios systems.
Format: Alpha numeric. Max length: 32
Transaction.creditTransaction.dateMade
Present
DateThis is the date when the Avios was added to the account – postedDate. Example: 2016-10-20
Format: YYYY-MM-DD
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
Conditional
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
Conditional
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.