NAV Navbar

Introduction

Welcome to Avios’ APIs. You can use this site to view details about all of our live APIs.

Avios’ APIs are RESTful with standard HTTP methods and status codes. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON. To use Avios APIs, all partners will need to obtain an API key by registering.

To use Avios APIs:

Run in Postman

Authentication

v1

To use Avios APIs, partners need to register and ​obtain an API key​ for our staging environment. A different key will be provided when the partner application is deployed to live.

The AGLs APIs offer loyalty services across 3 programmes:

Member authentication is mandatory for most of Avios APIs and achieved through an ​Oauth2 Authorization Code flow​:

  1. When a member attempts authentication, the partner application will present a third-party login form according to their programme.
  2. After the Authentication system validates the partner and lets the member enter their credentials.
  3. The Authentication system validates the member and returns an auth_code to the partner application.
  4. The partner sends a request to the Authentication system with the auth_code and the authorisation code grant_type.
  5. The Authentication system generates and returns a token to the partner, which can be passed into subsequent requests to call other Avios APIs.

Client credentials authentication is applicable to some Avios APIs through an ​Oauth2 Client Credentials flow​:

  1. The partner sends a request to the Authentication system with its client identifier and secret and the client credentials grant_type.
  2. The Authentication system generates and returns a token to the partner, which can be passed into subsequent requests to call other Avios APIs.

The token issued depends on the programme.

Programme Grant Authorization Token
British Airways Executive Club client_id (Confidential) Oauth2 Bearer token Or JWT
Aer Lingus AerClub Basic Auth JWT
Vueling Club Basic Auth JWT

Avios Authentication

This authentication applies to Aer Lingus AerClub and Vueling Club.

Usage of the Authentication API follows successful calls to both the Join Programme and Register Account APIs. The Authentication API must be called prior to, Retrieve Membership, Update Membership, Retrieve Transaction, Debit Currency or Reverse Transaction (and to execute Debit Currency a pricing request must have been performed).

The following steps are performed by the Authentication service:

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: An access token is returned in the API response message.

Error outcome: Service error is returned.

Auth code for Partner Login Page

Partner Login Page Endpoint:

'POST https://partnerservices.avios.com/secure/code?response_type={response_type}&client_id={client_id}&scope={scope}&state={state}&brandName={brandName}&programme-identifier={programme-identifier}&business-context-identifier={business-context-identifier}'

Example:

https://partnerservices.avios.com/secure/code?response_type=code&client_id=TESTA00001&scope=READ&state=Sogo2&brandName=TESTA&programme-identifier=ATRP&business-context-identifier=BCI
Name Required Data type Format Description
response_type Required String String Value must be set to 'code' always. This signifies that the partner is attempting to initiate the token process using OAuth's authorization_code grant type Format: String
redirect_uri Optional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). Representing the endpoint to which the authorization server sends the auth code as query parameter. The redirect uri should match with configured uri. Different redirect uris are configured for different partners. Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
client_id Required String Alphanumeric Client Id specific to each partner. This will have been provided during the partner on-boarding process. Format: Alphanumeric
scope Optional String Enumeration The scope of the access request. Must be set to ‘READ’. Currently this element doesn’t perform any functionality. Format: Enumeration
state Optional String Alphanumeric To maintain state between the request and call-back to avoid the CSRF (Cross-Site Request Forgery) attacks. Format: Alphanumeric
brandName Optional String Alphabetic only To display the partner logo in the login pages Format: Alphabetic only
Programme-Identifier Required String Alphabetic only. Max length: 20 The identifier for the loyalty programme to which the member belongs. This will have been provided during the partner on-boarding process. Format: Alphabetic only. Max length: 20
Business-Context-Identifier Required String Alphabetic only. Max length: 50 Context through which the information is coming. The value assigned to the partner. Once the value was passed it should be used when calling all other APIs which required business- context-identifier. Currently not in use, business-context- identifier value will have been provided during the partner on-boarding process which should be used for other APIs to call. Format: Alphabetic only. Max length: 50

Authentication Grant Type: Authorization_code

Authorization_code Grant Type Endpoint:

https://partnerservices.avios.com/secure/key?grant_type={grant_type}&code={code}&client_id={client_id}

Example:

https://partnerservices.avios.com/secure/key?grant_type=authorization_code&code=oIjPSa&client_id=TESTA00001
Name Required Data type Format Description
grant_type Required String Enumeration This grant type allows partner to use their credentials to retrieve an access token directly, which allows access to resource under partner’s control. Must be set to ‘authorization_code’. Format: Enumeration
code Required String Alpha numeric This is the authorization code previously retrieved from OAuth authorization server in auth code for partner login page scenario. Authorization code can only be used once to authenticate a member. Format: Alpha numeric
client_id Optional String Alphanumeric Client Id specific to each partner. This will have been provided during the partner on-boarding process. Format: Alphanumeric
scope Optional String Enumeration The scope of the access request. Must be set to ‘read’. Currently this element doesn’t perform any functionality. Format: Enumeration

Authentication Headers for grant Type: Authorization_code

Name Required Data type Format Description
business-context-identifier Required String Alphabetic only. Min length: 1, Max length: 50 Channel through which the information is coming. The value assigned to the partner. Format: Alphabetic only. Min length: 1, Max length: 50
programme-identifier Required String Alphabetic only The identifier for the loyalty programme to which the member belongs. Format: Alphabetic only
authorization Required String Base 64 encoded This is base64 encoded combination of client Identifier and Partner Secret. This information is shared as part of partner on-boarding. Format: Base 64 encoded
accept Optional String application/json The Accept request-header field is used to specify certain media types which are acceptable for the response. Only supported value is “application/json” Format: application/json
x-forwarded-for Optional String Valid IP address The IP address of the end customer. Format: Valid IP address

Request Elements

There is no separate request payload. The details required for token are available in request headers and query parameters.

Response Elements

The following is an example of a response generated by the Authentication API. Token response for grant type ‘authorization_code‘:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjM0NzU2MTcxNTYsInVzZXJfbmFtZSI6InVzZXJuYW1lX0plZXQiLCJzY29wZSI6WyJ3cml0ZSJdLCJqdGkiOiI5NzNkMDEyYi04NDVhLTQzMjEtYjJmNC0yNTdlMDFkZTcxZDQiLCJjbGllbnRfaWQiOiJ0ZXN0ciIsIlRva2VuX0luZm9ybWF0aW9uIjp7ImRhdGVUaW1lSXNzdWVkIjoiMjAxNi0xMC0wNCIsImF1dGhlbnRpY2F0aW9uTGV2ZWwiOiJBVVRIRU5USUNBVEVEIiwibWVtYmVyc2hpcE51bWJlciI6IjMwODE0NzEwMTA5OTM2MzEiLCJyZXF1ZXN0QXBwbGljYXRpb24iOiJBUEkiLCJyZXF1ZXN0ZWRQYXJ0bmVySWQiOiJ0ZXN0ciIsInByb2dyYW1tZUlkZW50aWZpZXIiOiJBVFJQIn19.rciZVcZGdRmPA66FGIDZzAeeHfSuxJ0n1Nac",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzU3ODUzNjcsInVzZXJfbmFtZSI6InVzZXJuYW1lX0plZXQiLCJzY29wZSI6WyJ3cml0ZSJdLCJqdGkiOiJi ZDdjM2I1OC04N2IxLTRmYzctYTJhOC0zZTU3OTQ4MjQ3NWMiLCJjbGllbnRfaWQiOiJ0ZXN0ciIsImF0aSI6Ijk3M2QwMTJiLTg0NWEtNDMyMS1iMmY0LTI1N2UwMWRlNzFkNCJ9.KZnyldWK7yhE-vZaoYfD_r31qIdFK55C_eTE2bAArnA",
  "expires_in": 2000031788,
  "scope": "write",
  "jti": "973d012b-845a-4321-b2f4-257e01de71d4",
  "Token_Information": {
    "dateTimeIssued": "2016-10-04",
    "authenticationLevel": "AUTHENTICATED",
    "membershipNumber": "3081471010993631",
    "requestApplication": "API",
    "requestedPartnerId": "testr",
    "programmeIdentifier": "ATRP"
  }
}

The elements that make up the response message are detailed in the following table. The API returns the response attributes in uppercase or lowercase ASCII characters as appropriate.

Name Presence Data Type Format Description
token Present Complex type [1..1] Token represents credentials used to access protected resources.
token.
access_token
Present String JWT Token An access token is a string representing an authorization issued to the client. This token must be provided to secured API calls like update security profile, retrieve member etc. Format: JWT Token
token.
token_type
Present String Enumeration Type of the token generated for the partner Format: Enumeration
token.
refresh_token
Conditional String JWT Token A refresh token is a string representing an authorization issued to the client for obtaining a new access token. Because refresh tokens are typically long-lasting credentials used to request additional access tokens, the refresh token is bound to the client to which it was issued. Format: JWT Token
token.
expires_in
Present Number Numeric The time interval after which the token will expire. The unit in seconds Format: Numeric
token.
scope
Present String Enumeration This element denotes the scope of the token. Values like {RESET_PASSWORD, RETRIEVE_USERNAME} Format: Enumeration
token.
jti
Present Number Numeric This represents jwt token identifier Format: Numeric
token.
Token Information
Present Complex type [1..1] Additional information provided along with the token.
token.
token_Information.
dateTimeIssued
Present Date yyyy-mm-dd The date when the token was issued to the partner. Format: yyyy-mm-dd
token.
token_Information.
authenticationLevel
Present String Enumeration This describes the authentication status. Will always be ‘AUTHENTICATED’ Format: Enumeration
token.
token_Information.
requestApplication
Present String Alphabets only The application which requested the token. Business-Context- Identifier header is set as requestApplication. Format: Alphabets only
token.
token_Information.
membershipNumber
Conditional String Min length = 16. Max Length = 24. Numeric only Membership number is the member identifier who’s credentials are authorized for obtaining the access token. This is only applicable for password grant type. Format: Min length = 16. Max Length = 24. Numeric only
token.
token_Information.
requestedPartnerId
Present String Min length: 8. Max length: 20. Alphanumeric This represents partner identifier who requested the token Format: Min length: 8. Max length: 20. Alphanumeric
token.
token_Information.
programmeIdentifier
Present String Alphabets only Identifier specifying the loyalty programme the member belongs to. Value will be the same which were provided in the request header. Format: Alphabets only

Exception Message Elements

Error message 1:

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant type: passwordw"
}

Error message 2:

{
  "error": "server_error",
  "error_description": "Request UnAuthorized"
}

This service returns standard OAuth 2.0 error messages. The exception message responses may be formatted in either upper or lower case.

Name Required Data type Format Description
error Required String Alphabetic plus under-score (_) Error code. Example: server_error Format: Alphabetic plus under-score (_)
description Conditional String Alphanumeric with special characters colon (:), space ( ). Description of the error. Example: Request UnAuthorized Format: Alphanumeric with special characters colon (:), space ( ).
scope Conditional String Alphanumeric Describes possible scopes of grant type client credentials. Will be present when the requested scope is invalid, unknown, or malformed. Example: read Format: Alphanumeric

Error Codes

All the errors from the Authentication service are returned in the standard OAuth 2.0 format shown above. This reports errors as a combination of parent error code and child error code.

The error codes for Authentication are shown in the following table:

HTTP code Parent Error Code Description
400 Invalid_request The request is missing a required parameter, includes an invalid parameter value
401 unauthorized The client is not authorized to request an access token using this method
401 access_denied The resource owner or authorization server denied the request
400 invalid_scope The requested scope is invalid, unknown, or malformed
500 server_error The authorization server encountered an unexpected condition which prevented it from fulfilling the request
500 temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server
400 unsupported_grant_type Provided grant_type is invalid
400 Invalid_grant Provided Auth code is already used or incorrect
401 Invalid_client Provided client id doesn’t match to the authentication information specified in headers.

User Friendly Error Codes

The following table describes the list of user friendly error message when the member tries to login using login page.

Error Scenario Error Message
Multiple attempts for a username Your details have not been recognized, please try again or update them at avios.com.
Invalid username.password Your details have not been recognized, please try again or update them at avios.com.
System Unavailable.Invalid security test We seem to be experiencing some difficulties. Please try again later.
Username field is blank Please enter your username.
Password field is blank Please enter your password.
Password and Username fields are blank Please enter your username. Please enter your password.
Invalid format of Username.Password Your details have not been recognized, please try again or update them at avios.com.
Invalid format of IP Address We seem to be experiencing some difficulties. Please try again later.

BAEC Authentication

Authentication Service Registration

Each API may require one or more of these authentication types:

Please consult the documentation of each API to see what type of authentication to use.

You will be provided, for each environment (see ​BAEC Environments and Authentication Endpoints​), with:

These credentials are to be kept secret.

In order to use of the BAEC Member Authentication Service you will be asked to provide for each environment (see ​BAEC Environments and Authentication Endpoints​):

Member and client authentication are described below.

Member Authentication

Step 1. Obtain an Authorization Code

Your application direct the member to the member login form:

URI Parameters

Authorization Code Endpoint

'GET https://{ENV-DOMAIN-NAME}/auth/login?client_id=aviosapipartners-{CLIENT-ID}&response_type=code&redirect_uri={URI-FOR-CALLBACK-WITH-CODE}'

Example:

GET https://ecp-prelive.baplc.com/auth/login?client_id=aviosapipartners-00000&response_type=code&redirect_uri=http://localhost:8080/auth
Name Required Data type Format Description Example
client_id Required String aviosapipartners-xxxxx where ​xxxxx​ is your 5-digit id Client identifier unique for your application. Format: aviosapipartners-xxxxx where ​xxxxx​ is your 5-digit id aviosapipartners-00000
response_type Required String code Response type indicating the OAuth 2 flow requested. Value must be set to 'code' always. Format: code code
redirect_uri Optional URI String your valid URI must have been configured during registration. URI of your application endpoint called by the Authentication Service with a code. The parameter is optional if your client identifier is configured with a single redirect URI. Format: your valid URI must have been configured during registration. http://localhost:8080/auth
Response

The response is a 302 redirect to the specified URI.

https://{REDIRECT_URI}?code={CODE_FOR_TOKEN_REQUEST}
Name Required Data type Format Description Example
code Required String alphanumeric Alphanumeric code to be used by your service to request a grant. This code expires within 2 minutes. Format: alphanumeric ad2b204bb782e873fda7 0ee8d0ec96a6
Main Error Cases

The error responses are also 302 redirect to the specified URI.

http://{REDIRECT_URI}?error={ERROR_CODE}
Name Required Data type Description Example
errors Required string Error code to be handled by your service. unsupported_response_type

Most error cases are displayed to the user:

Step 2. Obtain a Member Token

Once you have received the user’s Authorization Code (from Step 1. above) a request must be made for a Token using the Grant service.

Your service will then form a request to obtain a token, using the with:

Request Headers

Example request

'POST https://{ENV-DOMAIN-NAME}/api/grant'
Name Required Data type Format Description Example
Authorization Required String Basic {BASE64_ENCODED_CREDENTIALS} The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS} Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type Required String application/< content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type> application/x-www-form-urlencoded
Request Elements

Example request body

{
  "grant_type": "authorization_code",
  "code": "1eebd3387c26f94539e8bd288f68cbcb"
}
Name Required Data type Format Description Example
grant_type Required String authorization_code The grant type for the token. Format: authorization_code authorization_code
code Required String 256-bit key, lowercase hexadecimal The code provided by the auth server. Format: 256-bit key, lowercase hexadecimal 1eebd3387c26f94539e8 bd288f68cbcb

Example response

{
  "access_token": "17507d48f57cf8183da266141ed65b6d",
  "refresh_token": "a34879d0a9b61e9ab9e16ef1b689158d",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 600,
  "token_type": "bearer",
  "expires_in": 300
}

Step 3. Refresh a Member Token

Your service can request a new token, using the refresh_token grant of the Grant service with:

Request Headers

Example request

' POST https://{ENV-DOMAIN-NAME}/api/grant'
Name Required Data type Format Description Example
Authorization Required String Basic {BASE64_ENCODED_CREDENTIALS} The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS} Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type Required String application/< content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type> application/x-www-form-urlencoded
Request Elements

Example request

{
  "grant_type": "authorization_code",
  "code": "1eebd3387c26f94539e8bd288f68cbcb"
}
Name Required Data type Format Description Example
grant_type Required String authorization_code for member token; client_credentials for partner tokens The grant type for the token. Format: authorization_code for member token; client_credentials for partner tokens authorization_code
refresh_token Required String The code returned with the member token ad2b204bb782e873fda7 0ee8d0ec96a6

Example responses

{
  "access_token": "5c977c8c48fe225845919a9494d53127",
  "refresh_token": "74edddd818b301101841ade2e483cd2f",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 2592000,
  "token_type": "bearer",
  "expires_in": 86400
}

Client authentication

Obtain a client token

Your service will obtain a member token using the Grant service with:

Request Headers

Example request

'POST https://ecp-prelive.baplc.com/api/grant'
Name Required Data type Format Description Example
Authorization Required String Basic {BASE64_ENCODED_CREDENTIALS} The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS} Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type Required String application/< content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type> application/x-www-form-urlencoded
Request Elements
Name Required Data type Format Description Example
grant_type Required String client_credentials The grant type for the token. Format: client_credentials client_credentials

Example response

{
  "access_token": "324d27b0dc5cdae6019c8c601ac5392b",
  "scope": "AUTHN-LEVEL-15",
  "token_type": "bearer",
  "expires_in": 3600
}

Grant Service

Request Headers

Example request

'POST https://{ENV-DOMAIN-NAME}/api/grant'
Name Required Data type Format Description Example
Authorization Required String Basic {BASE64_ENCODED_CREDENTIALS} The BASE64_ENCODED_CREDENTIALS is encoded as such: base64( client_id + “:” + password ) Format: Basic {BASE64_ENCODED_CREDENTIALS} Basic YXZpb3NhcGlwYXJ0bmVycy0wMDAwMDpYWFhYWFhYWA==
Content-Type Required String application/< content-type> The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/x-www-form-urlencoded is accepted. Format: application/< content-type> application/x-www-form-urlencoded

Request Elements

Name Required Data type Format Description Example
grant_type Required String authorization_code for member token; client_credentials for partner tokens; refresh_token for requesting a new member token The grant type for the token. Format: authorization_code for member token; client_credentials for partner tokens; refresh_token for requesting a new member token authorization_code
code Optional String The code provided by the auth server. This code is required for authorization_code grant types and expires within 2 minutes. 1eebd3387c26f94539e8b d288f68cbcb
refresh_token Optional String The refresh token is required for refresh_token grant. 324d27b0dc5cdae6019c8 c601ac5392b

Response Elements

Example response

{
  "access_token": "17507d48f57cf8183da266141ed65b6d",
  "refresh_token": "a34879d0a9b61e9ab9e16ef1b689158d",
  "scope": "AUTHN-LEVEL-12",
  "ba_refresh_expires_in": 36000,
  "token_type": "bearer",
  "expires_in": 3600
}

A success will return the HTTP code 200 with the following JSON payload.

Name Required Data type Format Description Example
access_token Required String The access token. Expires as indicated in expires_in 324d27b0dc5cdae6019c8 c601ac5392b
refresh_token Optional String The refresh token. Provided in the case of a grant of types authorisation_code and refresh_token. Expires as indicated in ba_refresh_expires_in. 324d27b0dc5cdae6019c8 c601ac5392b
scope Required String AUTHN-LEVEL-10, AUTHN-LEVEL-12, AUTHN-LEVEL-15 (highest) Authorisation level. May have a different number at the end (representing how securely the user is considered to have authenticated) Format: AUTHN-LEVEL-10, AUTHN-LEVEL-12, AUTHN-LEVEL-15 (highest) AUTHN-LEVEL-15
token_type Required String bearer Token type. Indicates how the token should be used. Format: bearer bearer
expires_in Required Integer Token lifetime in seconds. 84600
ba_refresh_expires_in Optional Integer Refresh token lifetime in seconds. Only present for grants of type authorization_code. 259200

Main Error Cases

Error HTTP code Body
Invalid / Expired Token 401
Invalid Grant Type 400 {"error": "unsupported_grant_type"}
Missing Required Param 400 {"error": "invalid_request", "error_description": "Required field [XXX] was not present in the request"}
Invalid Client (no/bad auth method used) 400 {"error": "invalid_client"}
Invalid Client (doesn’t exist / bad credentials) 401 {"error": "invalid_client"}
Token Generation Refused (throttle) 429 {"error": "too_many_tokens"}
Invalid Token (Refresh) 400 {"error": "invalid_grant", "error_description": "invalid_token"}
No Access (No Roles Setup) 400 {"error": "invalid_grant", "error_description": "access_denied"}
Generic Error 400 {"error": "invalid_grant"}

BAEC Environments and Authentication Endpoints

The BAEC Authentication Service is available in 2 environments. Their domain name and endpoints are as following:

Environment Web service Endpoint
Pre-live Login page https://ecp-prelive.baplc.com/auth/login
Grant https://ecp-prelive.baplc.com/api/grant
Live Login page https://www.britishairways.com/auth/login
Grant https://www.britishairways.com/api/grant

Join Programme

v3

The Join Programme API creates a new account within a loyalty programme, registers the member’s security credentials (if provided) and associates the member with the partner or partner programme.

Firstly, the member details and username are checked to ascertain if they are pre-existing within the Loyalty platform. Processing of the request will occur if the member and username do not exist. Successful processing of a request will create a loyalty account and associate the security profile with this new account, if it has been provided.

The member details along with membership number are returned to the consumer as a successful response, however if the request fails an appropriate error message is returned.

Business Context

The process relating to the consumption of the Join Programme API is illustrated in the following swim-lanes diagram:

Join Programme API Flow

Technical Context

The Join Programme API is an independent service and does not rely on any other service having been called. To invoke the Join Programme API the partner must have previously been issued with a valid API key. The following steps are performed by the Join Programme API:

Important Technical Notes

This API can receive upper or lower case ASCII or accented data but this will be converted to upper case ASCII on receipt by the Join Programme API. The response message will contain only upper case ASCII characters.

This API provides functionality to create a new account with the minimal dataset of First Name, Last Name and Email Address of a member.

This API supports accented characters as input in First Name, Middle Initial, Last Name, Address Lines and Security Question Responses but converts them into equivalent uppercase ASCII character before validating the data and persisting data into the systems. Please refer to Appendix G for further details.

Telephone numbers are supplied as separate area code and number fields in the request but are returned as a single combined field in the response.

Pre-conditions

Post-conditions

Success outcome: Member information along with account details are returned.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

POST https://api.avios.com/{version}/memberships?api_key={api_key}

Example

https://api.avios.com/v3/memberships?api_key=abcdef
Name Required Type Format Description Example
version Required String Alpha numeric v[0-9] The version of the API which will be confirmed during the on-boarding process. Format: Alpha numeric v[0-9] v3
api_key Required String Alpha-numeric only Min Length: 24 Max Length: 24 The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: Alpha-numeric only Min Length: 24 Max Length: 24 abcdefabcdefabcdefabcdef

Request Headers

Name Required Type Format Description Example
Accept Optional String ication/< content-type > The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted currently. Format: ication/< content-type > application/JSON
content-type Required String application/< content-type > The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted currently. Format: application/< content-type > application/JSON
X-Forwarded-For Optional String Comma seperated valid IP address Identifies the originating IP address of a consumer. Second and following IP addresses aren’t validated. Format: Comma seperated valid IP address 172.128.25.24, 172.128.25.24

Request Elements

The elements that make up the request message are detailed in the following table. These elements represent the data required to describe a new member within the loyalty programme. The following rules apply to request elements:

Example Requests:

{
  "member": {
    "person": {
      "name": {
        "firstName": "MARK",
        "familyName": "HARE"
      },
      "emailAddresses": {
        "preferredEmailAddress": {
          "email": "oscar.k@avios.com"
        }
      }
    }
  }
}
Name Required Data type Format Description
campaign Optional Complex type [0..1] A campaign allows a partner to associate the joining of the programme to marketing activity, for example, to associate a bonus award.
campaign.
identifier
Required String Max length: 8 Alphabetic A value that represents the partner’s campaign. Case sensitive. This value must be agreed in advance with Avios and configured within the partner’s and Avios’ systems. It is possible to configure a single campaign for a partner used in all Join Programme API requests; this ensures any member account created is appropriately associated with the Partner in Avios systems. In the case where the provided campaign identifier is not valid for the requesting partner an Invalid Campaign Identifier error will be returned. Format: Max length: 8 Alphabetic
member Required Complex type [1..1] A complex type that represents the member within Avios systems. This type contains a person and an optional security profile, which represent the member’s descriptive information and their security credentials and associated data elements.
member.
person
Required Complex type [1..1] Represents the person details within Avios systems.
member.
person.
name
Required Complex type [1..1] Contains the name of the member, split into various fields that represent a name in a recognised format. Salutation, forename, middle initial (if present), family name.
member.
person.
name.
title
Optional String Min Length: 1, Max length: 30, Alphabetic. Title (Salutation) of the member. API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided the Gender of the member will be set to NOT_KNOWN. Format: Min Length: 1, Max length: 30, Alphabetic.
member.
person.
name.
firstName
Required String Min Length: 1, Max Length: 25, Alphabetic plus some special characters. First name (forename) of the Loyalty Programme member. Allowable special characters: apostrophe (‘), hyphen (-), spaces and accent characters. First Name must begin with a letter. Hyphen, apostrophe and space are not accepted as the first character for this field.Please refer to Appendix G for accented character conversion rules. Format: Min Length: 1, Max Length: 25, Alphabetic plus some special characters.
member.
person.
name.
middleInitial
Optional String Max Length: 1, Alphabetic and accented characters. Middle initial of the Loyalty Programme member.If this value is not supplied a default will not be assigned.Please refer to Appendix G for accented character conversion rules. Format: Max Length: 1, Alphabetic and accented characters.
member.
person.
name.
familyName
Required String Max Length: 40, Alphabetic plus some special characters. Surname (or last name) of the Loyalty Programme member.Allowable special characters: apostrophe (‘), hyphen (-), spaces and accent characters. Family Name must begin with a letter.Hyphen, space and apostrophe are not accepted as the first character for this field.Please refer to Appendix G for accented character conversion rules. Format: Max Length: 40, Alphabetic plus some special characters.
member.
person.
dateOfBirth
Optional Date YYYY-MM-DD The member’s Date of Birth in ISO-8601 Calendar date format.Member must be at least 18 years old (adult) and future dates are not permitted. Format: YYYY-MM-DD
Member.
person.
gender
Optional String Enumeration. Gender identification of Loyalty Programme member. Case Sensitive and must be set to: MALE FEMALE NOT_SPECIFIED NOT_KNOWN API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided the Gender of the member will be set to NOT_KNOWN. Format: Enumeration.
member.
person.
registeredIdentifier
Conditional Complex type [0..1] This complex type represents the Identification document provided by the member. In some countries, for example South Africa, there is a requirement to collect recognised Identification when joining. This is typically the passport but could be another government issued Identification document. This element is mandatory in the request if the country of residence is South Africa.
Member.
person.
registeredIdentifier.
token
Required String Max length: 24. Alphanumeric The passport number or other Identification Card issue number for the Identification provided by the member as part of the Join process. Format: Max length: 24. Alphanumeric
Member.
person.
registeredIdentifier.
placeOfIssue
Required Complex type [1..1] Place of issue of the identity document related to the token provided above.
Member.
person.
registeredIdentifier.
placeOfIssue.
identifier
Required String Max length: 2, Min length: 2, ISO 3166-1, Two character alphabetic Country code. Location identifier of the place where identification document has been issued. Only length of provided value is validated. Format: Max length: 2, Min length: 2, ISO 3166-1, Two character alphabetic Country code.
member.
person.
registeredIdentifier.
placeOfIssue.
type
Required String Enumeration. The type of location for place of issue. Case sensitive and must be “COUNTRY”. Format: Enumeration.
member.
person.
registeredIdentifier.
type
Required String Enumeration. Type of identification document. Case sensitive and must be one of the following: PASSPORT NATIONAL_IDENTITY_CARD Format: Enumeration.
member.
person.
locale
Optional Complex type [1..1] Contains information about preferred locale for member.
member.
person.
locale.
languageCode
Required String Max length: 2, Min length: 2, ISO 639-1, Alphabetic 2 character language code. Preferred language of the member for use within Avios systems and channels. Supported values are: EN ES CA FR IT Format: Max length: 2, Min length: 2, ISO 639-1, Alphabetic 2 character language code.
member.
person.
postalAddresses
Optional Complex type [1..1] A complex type representing the Member’s postal addresses.
Member.
person.
postalAddresses.
preferredPostalAddress
Required Complex type [1..1] A complex type representing the preferred postal address of the member.
Member.
person.
postalAddresses.
preferredPostalAddress.
type
Required String Enumeration. Type of postal address. Case sensitive and must be one of the following: PERSONAL BUSINESS Preferred and other Postal Address types must have different values. If type PERSONAL will be provided in request address will be saved under preferred postal address details if type will be BUSINESS, address details will be saved under other Postal Address Format: Enumeration.
member.
person.
postalAddresses.
preferredPostalAddress.
addressLine
Required Array of string [1..4] Max length: 30, Alphanumeric plus period (.), comma (,), dash (-), space ( ), ampersand (&), ‘ and accented characters. An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country.For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesThe field can also have accented characters, which will be converted to equivalent ASCII before any validations. Refer Appendix G for details.Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30, Alphanumeric plus period (.), comma (,), dash (-), space ( ), ampersand (&), ‘ and accented characters.
member.
person.
postalAddresses.
preferredPostalAddress.
country
Required String Max length: 2, Min length:2, ISO 3166-1, Alphabetic 2 character country code. The country of the member’s preferred address.This field will determine the member’s Market within Avios systems, which will not have an impact on the Partner’s interactions with the customer. If a value is not supplied the member will be assumed to be within a country with code XX, in Europe. Format: Max length: 2, Min length:2, ISO 3166-1, Alphabetic 2 character country code.
member.
person.
postalAddresses.
preferredPostalAddress.
postCode
Conditional String Max length: 8. Alphanumeric Postal code of member’s preferred address.Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Must not contain spaces. Format: Max length: 8. Alphanumeric
Member.
person.
postalAddresses.
preferredPostalAddress.
validationSource
Optional String Enumeration. This specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (No System validation required) SYSTEM (System Validation required) Providing a value of EXPLICIT will bypass address validation within Avios systems. Omitting this field in the request has the same effect as providing a value of SYSTEM Format: Enumeration.
member.
person.
postalAddresses.
otherPostalAddress
Optional Complex type [0..1] Optional postal address in addition to the preferred postal address.
member.
person.
postalAddresses.
otherPostalAddress.
type
Required String Enumeration. Type of postal address. Case sensitive and must be one of the following: PERSONAL BUSINESS Preferred and other Postal Address types must have different values. If type PERSONAL will be provided in request address details will be saved under preferred postal address details if type will be BUSINESS, address details will be saved under other Postal Address Format: Enumeration.
member.
person.
postalAddresses.
otherPostalAddress.
addressLine
Required Array of string [1..4] Max length: 30. Alphanumeric plus period (.), comma (,),dash (-), space ( ), ampersand (&), ‘ and accented characters. An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country.For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesThe field can also have accented characters, which will be converted to equivalent ASCII before any validations. Refer Appendix G for details.Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30. Alphanumeric plus period (.), comma (,),dash (-), space ( ), ampersand (&), ‘ and accented characters.
member.
person.
postalAddresses.
otherPostalAddress.
country
Required String Max length: 2 Min length:2ISO 3166-1 Alphabetic 2 character country code. The country of the member’s preferred address.This field will determine the member’s Market within Avios systems, which will not have an impact on the Partner’s interactions with the customer. If a value is not supplied the member will be assumed to be within a country with code XX, in Europe. Format: Max length: 2 Min length:2ISO 3166-1 Alphabetic 2 character country code.
member.
person.
postalAddresses.
otherPostalAddress.
postCode
Conditional String Max length: 8. Alphanumeric Postal code of member’s preferred address.Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Must not contain spaces. Format: Max length: 8. Alphanumeric
member.
person.
postalAddresses.
otherPostalAddress.
validationSource
Optional String Enumeration. This specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (No System validation required) SYSTEM (System Validation required) Providing a value of EXPLICIT will bypass address validation within Avios systems. Omitting this field in the request has the same effect as providing a value of SYSTEM Format: Enumeration.
member.
person.
emailAddresses
Required Complex type [1..1] A complex type representing the Member’s email addresses.
member.
person.
emailAddresses.
preferredEmailAddress
Required Complex type [1..1] A complex type representing the Member’s preferred email address.
member.
person.
emailAddresses.
preferredEmailAddress.
email
Required String AlphanumericMax length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%). Email address of the member. There may be only a single at-sign present. Also, all special characters can be specified before the at-sign and just minus (-) and period (.) after at-sign. Period (.) can’t be before at(@). Format: AlphanumericMax length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%).
member.
person.
telecomAddresses
Optional Complex type [1..1] A complex type that represents a collection of Member’s fully elaborated telephone numbers, which include country and area codes.
member.
person.
telecomAddresses.
preferredTelecomAddress
Required Complex type [1..1] A complex type that represents a Member’s preferred telephone number.
member.
person.
telecomAddresses.
preferredTelecomAddress.
countryCode
Optional String Max length: 5 Numeric. The direct dialling code required to call the preferred telecom address from another country. Also referred to as the International Subscriber Dialling (ISD) code.This value will not be prefixed with leading zeros or a plus (+), r example UK telephone numbers will have a country code value of 44. Format: Max length: 5 Numeric.
Member.
person.
telecomAddresses.
preferredTelecomAddress.
areaCode
Optional String Max length: 5 Numeric. The area code element of the Member’s preferred telecom address.The total length of combination of the area code and the number cannot exceed 15 characters. Area code can be included in number element. Format: Max length: 5 Numeric.
Member.
person.
telecomAddresses.
preferredTelecomAddress.
number
Required String Max length: 15. Numeric. The body of the Member’s preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. Format: Max length: 15. Numeric.
Member.
person.
telecomAddresses.
preferredTelecomAddress.
type
Required String Enumeration. Telecom addresses type. Case sensitive and must be one of the following:BUSINESS PERSONALThe following combinations of deviceType and type are accepted by the application: If device Type = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone number is saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. Format: Enumeration.
Member.
person.
telecomAddresses.
preferredTelecomAddress.
deviceType
Required String Enumeration. Telecom addresses device type. Case sensitive and must be one of the following: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. Format: Enumeration.
member.
person.
telecomAddresses.
otherTelecomAddress
Optional Array of complex type [0..2] Other telecom address in addition to the preferred telecom address. A member could have more than one telephone number. Avios can store up to 3 telephone numbers for each member, including the preferred telecom address. Will not be visible in response even if provided in request.
member.
person.
telecomAddresses.
otherTelecomAddress.
countryCode
Optional String Numeric characters Telecom addresses country code. The total string length of the countryCode, areaCode and the telephone number cannot exceed 15 characters. Will not be visible in response even if provided in request. Format: Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
areaCode
Optional String Max length: 15 Numeric characters Telecom address area code. The total string length of the areaCode and the telephone number cannot exceed 15 characters. Will not be visible in response even if provided in request. Format: Max length: 15 Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
number
Required String Max length: 15 Numeric characters The body of the Member’s preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. Will not be visible in response even if provided in request. Format: Max length: 15 Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
type
Required String Enumeration Telecom addresses type. Case sensitive and must be one of the following: BUSINESS PERSONAL The following combinations of deviceType and type are accepted by the application: If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone number is saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. Will not be visible in response even if provided in request. Format: Enumeration
member.
person.
telecomAddresses.
otherTelecomAddress.
deviceType
Required String Enumeration Telecom address device type. Must be one of the following: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. Will not be visible in response even if provided in request. Format: Enumeration
member.
person.
marketingPreference
Optional Array of complex type [0..2] Member’s preference for receiving marketing communications from Loyalty Programme in relation to products offering. There may be multiple instances of this element. There can only be passed two marketing preference objects with different campaign type channels. If there are passed few marketing preference objects with same campaign types error will be returned.
member.
person.
marketingPreference.
campaignType
Required String Enumeration Promotion activity of a product conducted by the Partner. Must be one of the following: TRAVEL_OFFERS PARTNER the following combinations are allowed: communicationChannel = POSTAL and campaignType = PARTNER for third party marketing communications by Post. communicationChannel = POSTAL and campaignType = TRAVEL_OFFERS for Avios marketing communications by Post.Any other combination will result in error. Format: Enumeration
member.
person.
marketingPreference.
communicationChannel
Required String Enumeration Channel of communication preferred by the member to receive partner’s marketing information. Must be “POSTAL”.This field and Type, described above, are interrelated as per the Description for the campaignType field above. Format: Enumeration
member.
person.
marketingPreference.
selected
Required String Enumeration Indicator if selection is Yes (Y) or No (N). Decides if marketing preference details will be visible in response. Format: Enumeration
member.
person.
contactPreference
Optional Array of complex type [0..3] Member’s preference of being contacted by Partner/Loyalty Programme. There may be multiple instances of this element. There can only be passed three contact preference objects with different communication channels. If there are passed few contact preference objects with same communication channel error will be returned.
member.
person.
contactPreference.
communicationChannel
Required String Enumeration Channel of communication preferred by the member to receive partner’s marketing information. The following combinations are allowed: communicationChannel = EMAIL for communications via email. communicationChannel = SMS for communications via SMS. communicationChannel = PHONE for communications via phone. Any other combination will result in error. Format: Enumeration
member.
person.
contactPreference.
selected
Required String Enumeration Indicator if selection is Yes (Y) or No (N). Decides if contact preference details will be visible in response. Format: Enumeration
Member.
securityProfile
Optional Complex type [0..1] A complex type representing the member’s security profile, which contains the security credentials and responses to the chosen security questions
member.
securityProfile.
credentials
Required Complex type [1..1] A complex type that represents the member’s security credentials (username and password) to register against the member’s account within the Avios ecosystem
Member.
securityProfile.
credentials.
identifier
Required String Min length: 6, Max length: 50. Alphanumeric plus some other characters, refer to description for details. The username field. Characters may be alphanumeric and may also include the following: period (.) at (@) hyphen (-) underscore (_) Format: Min length: 6, Max length: 50. Alphanumeric plus some other characters, refer to description for details.
Member.
securityProfile.
credentials.
token
Required String MinLength: 8, Maxlength: 20, Alphanumeric plus special characters [£!\”#$%&’()*+,-./:;⬄?@^_`{}~]. A string containing the Password of the member, this value is hashed and the hash stored in Avios systems. The original Password is discarded.A valid Password must include at least 3 of below rules:At least one number appearing in the string At least one lowercase letter appearing in the string At least one upper case letter appearing in the string At least one special character appearing in the string Format: MinLength: 8, Maxlength: 20, Alphanumeric plus special characters [£!\”#$%&’()*+,-./:;⬄?@^_`{}~].
member.
securityProfile.
securityChallenge.
Required Complex type [2..2] An array of 2 elements that represent the responses to the security questions to be used when a member attempts to recover forgotten credentials.Two security responses must be specified and each must have a unique Id within the request (they must have different Ids).
Member.
securityProfile.
securityChallenge.
identifier
Required String Min length: 1, Max length: 2, Numeric only A numeric value that represents the Identifier of the Security Question the response (in the following field) relates to. Maximum value of this element is 12. Format: Min length: 1, Max length: 2, Numeric only
Member.
securityProfile.
securityChallenge.
response
Required String Min length: 2, Maxlength: 50, Alphanumeric, special characters and accented characters. The member’s response to the security challenge (The answer to the security question). This field must start with an alphanumeric character. Accented characters with be converted to respective ASCII character before persisting the value in the system. This conversion is one way process, converted ASCII character cannot be translated back to original accented character. The list of accented characters and appropriate ASCII characters is shown in AppendixG. Other characters may be alphanumeric and may also include any of the following:ampersand (&) period (.) comma (,) apostrophe (‘) special quote (`) hyphen (-) space ( ) Format: Min length: 2, Maxlength: 50, Alphanumeric, special characters and accented characters.

Response Elements

The elements that make up the response message are detailed in the following table. The following rules apply to response elements:

{
  "membershipIdentifier": "3081471024602111",
  "membershipStatus": "ACTIVE",
  "member": {
    "person": {
      "name": {
        "firstName": "MARKA",
        "familyName": "HAREA"
      },
      "gender": "NOT_KNOWN",
      "locale": {
        "languageCode": "EN"
      },
      "emailAddresses": {
        "preferredEmailAddress": {
          "email": "OSCAR.K@AVIOS.COM"
        }
      }
    }
  }
}

Example response from the Join Programme API with security profile

{
  "person": {
    "name": {
      "title": "MR",
      "firstName": "WERTYHAA",
      "middleInitial": "L",
      "familyName": "SURNAMES"
    },
    "dateOfBirth": "1950-01-01",
    "membershipIdentifier": "3081471024602137",
    "membershipStatus": "ACTIVE",
    "member": {
      "gender": "MALE",
      "countryOfResidence": "GB",
      "locale": {
        "languageCode": "EN"
      },
      "postalAddresses": {
        "preferredPostalAddress": {
          "type": "PERSONAL",
          "addressLine": [
            "14 WHEATLEY DRIVE", "MIRFIELD",
            "WEST YORKSHIRE"
          ],
          "country": "UNITED KINGDOM",
          "postCode": "WF148NW"
        }
      },
      "emailAddresses": {
        "preferredEmailAddress": {
          "email": "MY.EMAIL@AVIOS.COM"
        }
      },
      "telecomAddresses": {
        "preferredTelecomAddress": {
          "countryCode": "44",
          "number": "01179404032",
          "type": "PERSONAL",
          "deviceType": "PHONE"
        }
      }
    }
  }
}
Name Required Data type Format Description
membershipIdentifier Required String Max length: 24. Numeric. A string containing the membership number generated when the Member’s account was created during the processing of the request message.Example: 3081471018350495The membership number format is similar to a credit card number and a LUHN check will return a successful result. The first 6 digits of 308147 represent an Avios related membership number. Format: Max length: 24. Numeric.
membershipStatus Required String Enumeration Membership Status. Possible value is “ACTIVE” Format: Enumeration
member Required Complex type [1..1] A complex type that represents the member within Avios systems. This type contains a person.
member.
person
Required Complex type [1..1] A complex type that represents a member within Avios systems.
member.
person.
name
Required Complex type [1..1] Contains the name of the member, split into various fields that represent a name in a recognised format. Salutation, forename, middle initial (if present), family name.
member.
person.
name.
title
Conditional String Max Length: 30 Alphabetic. Title (Salutation) of the member. API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided the Gender of the member will be set to NOT_SPECIFIED.The value provided in the request will be returned in response. Format: Max Length: 30 Alphabetic.
Member.
person.
name.
firstName
Required String Max Length: 25. Alphabetic Plus quote (‘), space ( ) and hyphen (-). First name (forename) of the Loyalty Programme member.May contain the following special characters: apostrophe (‘), hyphen (-), spaces. First Name will always begin with a letter.Hyphen, apostrophe and space will never be present as the first character for this field.Please refer to Appendix G for accented character conversion rules. Format: Max Length: 25. Alphabetic Plus quote (‘), space ( ) and hyphen (-).
Member.
person.
name.
middleInitial
Conditional String Max Length: 1. Alphabetic. Middle initial of the Loyalty Programme member. Will be present if passed in the originating request message. Format: Max Length: 1. Alphabetic.
Member.
person.
name.
familyName
Required String Max Length: 40.Alphabeticplus quote (‘) hyphen (-) and spaces. Surname (or last name) of the Loyalty Programme member.May contain the following special characters: apostrophe (‘), hyphen (-), spaces.Family Name will always begin with a letter.Hyphen, space and apostrophe will never be present as the first character for this field.Please refer to Appendix G for accented character conversion rules. Format: Max Length: 40.Alphabeticplus quote (‘) hyphen (-) and spaces.
member.
person.
dateOfBirth
Conditional Date YYYY-MM-DD ISO-8601.Calendar date format. The member’s Date of Birth in ISO-8601 Calendar date format. It will be present in response when same given in request. It won’t be present in response if passed date in request message will be earlier than 1800-01-02 or date of birth wasn’t passed in request message. Format: YYYY-MM-DD ISO-8601.Calendar date format.
member.
person.
gender
Required String Enumeration. An indicator of the gender of a member. API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided the Gender of the member will be set to NOT_KNOWN. Will be one of the following:MALE FEMALE NOT_KNOWN Format: Enumeration.
member.
person.
countryOfResidence
Conditional String Max length: 2Min length: 2ISO 3166-1 Alphabetic 2 character country code. The country code denotes the country of residence of the member. Within Avios systems this will be used to associate the member to the Avios notion of a Market. This concept of Market has no impact on partner systems.Country of residence, if present, will match the country provided in the member’s Preferred Postal Address.If Country of residence is not present then member profile is associated to a default country – “XX”. Format: Max length: 2Min length: 2ISO 3166-1 Alphabetic 2 character country code.
member.
person.
locale
Conditional Complex type [1..1] A complex type that represents the chosen locale of the Member.It will present in response when same given in request.
member.
person.
locale.
languageCode
Required String ISO 639-1 Alphabetic 2 character language code Preferred language of the member for use within Avios systems and channels. Will be one of the following values: EN ES CA FR IT Format: ISO 639-1 Alphabetic 2 character language code
member.
person.
postalAddresses
Conditional Complex type [1..1] A complex type that represents the Member’s postal addresses. The Join Programme API may validate the address supplied in the request message and depending on the outcome may provide an alternative format, which is retained with Avios systems and returned within the response message.
Member.
person.
postalAddresses.
preferredPostalAddress
Conditional Complex type [0..1] A complex type representing the preferred postal address of the member. Will not be visible if preferredPostalAddress type will contain value BUSINESS and there will be no otherPostalAddress details specified in request message. Will contain address details which will have type PERSONAL.
Member.
person.
postalAddresses.
preferredPostalAddress.
type
Required String Enumeration. A string representing the type of the Member’s preferred postal address. Will be one of the following: PERSONAL Format: Enumeration.
member.
person.
postalAddresses.
preferredPostalAddress.
addressLine
Required Array of string [1..4] Max length: 30.Alphanumeric plus period (.) and comma (,). An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesPlease refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30.Alphanumeric plus period (.) and comma (,).
member.
person.
postalAddresses.
preferredPostalAddress.
country
Required String Alphabetic with space. Postal address country name. Example: UNITED KINGDOM Format: Alphabetic with space.
member.
person.
postalAddresses.
preferredPostalAddress.
postcode
Conditional String Max length: 8. Alphanumeric The Postal code of address for the Member’s preferred postal address, if the address contains one this value will be present in the response. The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8. Alphanumeric
member.
person.
postalAddresses.
otherPostalAddress
Conditional Complex type [0..1] Other postal address details. Optional postal address in addition to the preferred postal address. Will be visible if preferred postal address or other postal address will contain type with value BUSINESS.
member.
person.
postalAddresses.
otherPostalAddress.
type
Required String Enumeration Type of postal address. Will be one of the following: BUSINESS Format: Enumeration
member.
person.
postalAddresses.
otherPostalAddress.
addressLine
Required Array of string [1..5] Max length: 30. Alphanumeric plus period (.) and comma (,). If preferred and other postal address details were sent in request, address line will contain the same address line details as provided under preferredPostalAddress object. Response will contain 5 address lines and API will return null value for each address line which was not provided in request message. An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line *The request should follow JSON format for providing multiple address lines Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30. Alphanumeric plus period (.) and comma (,).
member.
person.
postalAddresses.
otherPostalAddress.
country
Required String Alphabetic with space. Postal address country name.Example: UNITED KINGDOM Format: Alphabetic with space.
member.
person.
postalAddresses.
otherPostalAddress.
postcode
Conditional String Max length: 8 Alphanumeric The Postal code of address for the Member’s preferred postal address, if the address contains one this value will be present in the response. Please refer to the Country Address Rules document, which identifies the mandatory elements for each country.The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8 Alphanumeric
member.
person.
emailAddresses
Required Complex type [1..1] A complex type representing the Member’s email addresses.
Member.
person.
emailAddresses.
preferredEmailAddress
Required Complex type [1..1] A complex type representing the Member’s preferred email address.
member.
person.
emailAddresses.
preferredEmailAddress.
email
Required String Alphanumeric Max length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%). Email address of the member. There may be only a single at-sign present. Also, all special characters can be visible before the at-sign and just minus (-) and period (.) after at-sign. Period (.) can’t be before at(@). Format: Alphanumeric Max length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%).
member.
person.
telecomAddresses
Conditional Complex type [1..1] A complex type that represents a collection of Member’s fully elaborated telephone numbers, which include country and area codes. Area code and number will be combined in the response in a single field.
member.
person.
telecomAddresses.
preferredTelecomAddress
Required Complex type [1..1] A complex type that represents a Member’s preferred telephone number.
member.
person.
telecomAddresses.
preferredTelecomAddress.
countryCode
Required String NumericInternational dialling code The direct dialling code required to call the preferred telecom address from another country. Also referred to as the International Subscriber Dialling (ISD) code. It will present in response when same given in request. This value will not be prefixed with leading zeros or a plus (+), for example UK telephone numbers will have a country code value of 44. Format: NumericInternational dialling code
member.
person.
telecomAddresses.
preferredTelecomAddress.
number
Required String Max length: 15 Numeric. The member’s preferred telephone number (telecom address). This will include the area code but not the country code. Example: 01924311750 Format: Max length: 15 Numeric.
member.
person.
telecomAddresses.
preferredTelecomAddress.
type
Required String Enumeration Telecom addresses type. Will be one of the following: BUSINESS PERSONAL Format: Enumeration
member.
person.
telecomAddresses.
preferredTelecomAddress.
deviceType
Required String Enumeration Telecom addresses device type. Will be one of the following: PHONE MOBILE Format: Enumeration
member.
person.
marketingPreference
Conditional Array of complex type [0..2] Member’s preference for receiving Avios marketing communications. This element can occur multiple times. If marketing preference details weren’t passed in request message default communication channel with value TRAVEL_OFFERS along with communication channel with value POSTAL will be returned in response. This element can occur multiple times.Marketing Preference details will be seen if ‘selected’ element under marketingPreference object has been set to ‘Y’. If ‘selected’ element is set to ‘N’ marketing preference will not be returned. For internal Avios use only.
member.
person.
marketingPreference.
campaignType
Required String Enumeration Promotion activity of a product conducted by the Partner. Will be one of the following: TRAVEL_OFFERS PARTNER For internal Avios use only. Format: Enumeration
member.
person.
marketingPreference.
communicationChannel
Required String Enumeration Channel of communication preferred by the member to receive marketing information. Will always be “POSTAL”.For internal Avios use only. Format: Enumeration
member.
person.
contactPreference
Conditional Array of complex type [0..3] Member’s preference of being contacted by Partner/Loyalty Programme. If contact preference details weren’t passed in request message default will not be returned in response. This element can occur multiple times.Contact Preference details will be returned if ‘selected’ element under contactPreference object has been set to ‘Y’. If ‘selected’ element is set to ‘N’ contact preference details will not be returned.For internal Avios use only.
member.
person.
contactPreference.
communicationChannel
Required String Enumeration. Channel of communication preferred by the member to receive partner’s marketing information. Will be one of the following: EMAIL PHONE SMS For internal Avios use only. Format: Enumeration.
member.
person
Required String Enumeration Profile status. Possible values: FULL PARTIAL Format: Enumeration

Exception Message Elements

The exception message responses may be formatted in either upper or lower case.

Example of an error response

{
  "code": "LOYALTY_MEMBER_ALREADY_EXISTS",
  "businessMessage": "Loyalty member already exists",
  "developerMessage": "Loyalty member already exists",
  "developerLink": "https://developer.avios.com/docs",
  "childError": [
    {
      "code": "ACCOUNT_ACTIVE",
      "businessMessage": "Account Active",
      "developerMessage": "Account Active",
      "developerLink": https://developer.avios.com/docs
    }
  ]
}
Name Required Data type Format Description
code Required String Alphabetic plus under- score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under- score (_).
businessMessage Conditional String Alphabetic A business level message describing the error which has occurred. Example: Request Invalid Format: Alphabetic
developerMessage Conditional String Alphabetic Developer 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
developerLink Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
childError Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
childError.
code
Required String Alphabetic plus under- score (_). The error code for the child error (if returned) Example: DATA_INVALID Format: Alphabetic plus under- score (_).
hildError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Identifies the element in the request which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
childError.
businessMessage
Conditional String Alphabetic A business level message describing the error which has occurred, Example: Programme not supported Format: Alphabetic
childError.
developerMessage
Conditional String Alphabetic Developer 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
childError.
developerLink
Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

The table below shows a full list of error codes. If an error is received, then no account will have been created.

Http Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract.
400 REQUEST_INVALID MANDATORY_DATA_MISSING A mandatory element is missing from the request or JSON provided in request doesn’t follow its contract.
415 REQUEST_INVALID HEADER_INVALID The provided Content-Type header is invalid.
400 REQUEST_INVALID POSTAL_ADDRESS_INVALID Incorrect postal address or the postal address provided in the request could not be processed. Invalid PostCode supplied in request message.
400 REQUEST_INVALID PHONE_NUMBER_INVALID The Phone number provided as a telecom address in the request message is not a valid number for the country of residence provided in postal address.
400 REQUEST_INVALID PROFANITY_FIRST_NAME_INVALID The first name of the member provided appears to be profane or contain offensive/profane language and therefore cannot be used.
400 REQUEST_INVALID PROFANITY_LAST_NAME_INVALID The family name of the member provided appears to be profane or contain offensive/profane language and therefore cannot be used.
400 REQUEST_INVALID CUSTOMER_AGE_INVALID Member isn’t an adult (doesn’t has 18 years).
400 REQUEST_INVALID CAMPAIGN_IDENTIFIER_INVALID The campaign identifier provided in the request was not recognised as an agreed and preconfigured campaign identifier in Avios systems. Either an incorrect value was provided or the required campaign identifier needs to be configured.
400 REQUEST_INVALID REGISTERED_IDENTIFIER_INVALID The passport number or other Identification Card issue number is invalid which was specified in registeredIdentifier/token element.
400 REQUEST_INVALID ADDRESS_NOT_SUPPORTED Within telecomAddresses/preferredTelecomAddress/ the following combinations of deviceType and type are accepted by the application: If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone number is saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Another combination will result in an error.
400 USERNAME_ALREADY_EXISTS The username provided as part of the request already exists and an alternative will be required. No account will be created if the username is not available. An alternative username must be provided and the request resubmitted.
400 ACCOUNT_COULD_NOT_BE_ REGISTERED Payload provided in request has the same identifiers for security questions.
503 SYSTEM_UNAVAILABLE Unable to fulfil the request due to unavailability of one or more of downstream systems. This error will be returned In case if at least two marketing preference or contact preference elements were passed in request with same details.
403 DEVELOPER_NOT_AUTHORIZED The provided API key does not allow access to this API.
403 DEVELOPER_INACTIVE The provided API key is no longer active.
403 USAGE_RATE_EXCEEDED The usage rate (calls per second) has been exceeded for the API Key.
403 USAGE_RATE_LIMIT_EXCEED ED The usage rate limit (calls per day) has been exceeded for the API Key.
403 SSL_REQUIRED This API is required to be accessed using SSL via HTTPS.
503 SCHEDULED_MAINTENANCE This API is not available due to scheduled maintenance.
504 GATEWAY_TIMEOUT This API has failed to respond within the expected time and timed out.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_CANCELLED The Member details already exist within the Avios ecosystem and the account has a status of ‘cancelled’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_DEAD The Member details already exist within the Avios ecosystem and the account has a status of ‘dead’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_FRAUD The Member details already exist within the Avios ecosystem and the account has a status of ‘fraud’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_MANUALENQ The Member details already exist within the Avios ecosystem and the account is currently undergoing a fraud enquiry.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_EXPIRED The Member details already exist within the Avios ecosystem and the account has a status of ‘expired’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_LAPSED The Member details already exist within the Avios ecosystem and the account has a status of ‘lapsed’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_SUSPENDED The Member details already exist within the Avios ecosystem and the account as a status of ‘suspended’.
400 LOYALTY_MEMBER_ALREADY_EXISTS ACCOUNT_ACTIVE The Member details already exist within the Avios ecosystem and the account is active.
406 Accept header value is invalid.
596 The provided HTTP method is other than ‘POST‘.

Retrieve Programme

v1

The Retrieve Programme API enables a Partner to retrieve programmes supported by the Avios currency. The API returns programme information as part of successful response.

The objectives of this service are:

For Partners attempting to simply return the details of one programme, the only URI parameter that is required is the programme-identifier.

For Partners that want all programmes associated with a certain area code, they can include the specific area code in the endpoint.

Partners that want to return a list of programmes associated with a certain member, they simply include the membership-identifier in the endpoint.

Business Context

A summary of the process flow is as follows:

Retrieve Programme API Flow

Retrieve Programmes API Flow

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: HTTP status code 200 is returned along with details of the programme.

Error outcome: An error is returned.

Service Details

URI Parameters

Production Endpoints:

Making a call to the API using lonly programme-identifier:

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

Example

https://api.avios.com/v1/programmes/ATRP?api_key=abcdefabcdefabcdefabcdef

Making a call to the API using location-identifier to narrow the search:

'GET https://api.avios.com/{version}/programmes?location-identifier={location-identifier}&api_key={api_key}'

Example

https://api.avios.com/test/v1/programmes?location-identifier=GB&api_key=Abcdefabcdefabcdefabcdef

Making a call to the API using only the membership-identifier:

'GET https://api.avios.com/{version}/programmes?membership-identifier={membership-identifier}&api_key={api_key}'

Example

https://api.avios.com/v1/programmes?membership-identifier=3081470000000000&api_key=Abcdefabcdefabcdefabcdef
Name Required Data type Format Description Example
version Required String Alphanumeric v[0-9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric v[0-9] v1
programme-identifier Optional String Alphabetic with max length: 20 The identifier for the loyalty programme for which detailed information needs to be fetched. Format: Alphabetic with max length: 20 ATRP, BAEC, IBP, PUNTO, AERCLUB
location-identifier Optional String Min length = 2 Max length = 2 ISO 3166 Country code Represents the location (Country), the programmes for which have to be retrieved. API doesn’t validate if country code conforms with ISO 3166 standard. Format: Min length = 2 Max length = 2 ISO 3166 Country code GB
membership-identifier Optional String Numeric only. Min length = 16 Max Length = 24 The 16-digit membership number starting with 308147. Format: Numeric only. Min length = 16 Max Length = 24 3081471234550241
api_key Required String Alphanumeric only. Min length= 24, Max length= 24 The API key provided during the partner configuration which takes place as part of the partner on-boarding process. Format: Alphanumeric only. Min length= 24, Max length= 24 abcdefabcdefabcdefabcdef

Request Headers

Name Required Data type Format Description Example
Accept Optional String application/json The Accept request header is used to specify media types which are acceptable for the response. Currently this API only supports application/json Format: application/json application/json
X-Forwarded-For Optional String Comma separated Valid IP addresses The IP address of the end customer. Format: Comma separated Valid IP addresses 172.17.1.1, 172.17.1.2

Response Message Elements

The following are examples of successful responses from the Retrieve Programme API:

{
  "name": "AVIOS AGL",
  "_links": {
    "self": {
      "href": "https://api.avios.com/test/v1/programmes/ATRP"
    }
  }
}
{
  "size": "2",
  "programmes": [
    {
      "identifier": "ATRP",
      "name": "Avios Travel Rewards Program",
      "programmePartner": {
        "organisation": {
          "identifier": "AGL",
          "organisationName": "Avios Group Limited"
        }
      },
      "_links": {
        "collectionPartners": {
          "href": "https://api.avios.com/test/mock/collection-partners?membership-identifier=0123456789012345&programme=atrp"
        }
      }
    },
    {
      "identifier": "PUNTO",
      "name": "Punto",
      "programmePartner": {
        "organisation": {
          "identifier": "VY",
          "organisationName": "Vueling"
        }
      },
      "_links": {
        "collectionPartners": {
          "href": "https://api.avios.com/test/mock/collection-partners?membership-identifier=0123456789012345&programme=punto"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.avios.com/test/mock/programmes?membership-identifier=0123456789012345"
    }
  }
}

A response from the API containing only a singular programme will have the following response elements:

Name Presence Data type Format Description
name Present String Alphabets with space Max length: 100 The name of the loyalty programme. This element is present only when the retrieval of programme is based on programme identifier. Format: Alphabets with space Max length: 100
programmePartner Conditional Complex Type [0..1] Represents the partner associated with the programme. This element is present only when the retrieval of programme is based on programme identifier. This element won’t be visible if programme isn’t associated with any partner.
programmePartner.
organisation
Present Complex Type [1..1] Represents the organisation information of the partner. This element is present only when the retrieval of programme is based on programme identifier
programmePartner.
organisation.
identifier
Present String Alphanumeric with max length 20 Partner identifier Format: Alphanumeric with max length 20
programmePartner.
organisation.
organisationName
Present String Alphanumeric with max length 100 Partner organisation name Format: Alphanumeric with max length 100
_links Present Complex Type [1..1] Represents the hateoas link
_links.
self
Present Complex type [1..1] Contains the self-link, the complete request URL
_links.
self.
href
Present String Alphanumeric plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.) and ampersand (&) Contains link to self. Format: Alphanumeric plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.) and ampersand (&)

And for reponses containing multiple programmes:

Name Presence Type Format Description
programmes Present Array of Complex Type [1..n] Represents the programme information. This element is present when all programmes are retrieved or programmes are retrieved based on location identifier and/or membership identifier.
programmes.
identifier
Conditional String Enumeration The identifier of the loyalty programme. Possible values could be: ATRP BAEC IBPL AERCLUB PUNTO ISSLP Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier. Format: Enumeration
programmes.
name
Conditional String Alphabets with space. Max length: 100 The name of the loyalty programme. Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier. Format: Alphabets with space. Max length: 100
programmes.
programmePartner
Conditional Complex Type [0..1] Represents the partner details associated with the programme. Won’t be visible if not existing location identifier was passed in request or there aren’t any programmes associated with that country or programme isn’t associated with membership identifier.
programmes.
programmePartner.
organisation
Present Complex Type [1..1] Represents the organisation information of the partner.
programmes.
programmePartner.
organisation.
identifier
Present String Alphanumeric. Max length: 20 Partner identifier. Format: Alphanumeric. Max length: 20
programmes.
programmePartner.
organisation.
organisationName
Present String Alphanumeric with with special symbol space ( ). Max length: 100 Partner organisation name. Format: Alphanumeric with with special symbol space ( ). Max length: 100
size Present Integer Numeric. Max length: 2 Max value: 99 Present only when the retrieval of programmes is not based on programme identifier. This represents the number of programmes retrieved. Format: Numeric. Max length: 2 Max value: 99
_links Present Complex Type [1..1] Represents the hateoas link.
_links.
self
Present Complex Type [1..1] Contains the self-link, the complete request URL.
_links.
self.
href
Present String Alphanumeric plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.) and ampersand (&) Contains the self-link. Format: Alphanumeric plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.) and ampersand (&)

Exception Message Elements

The following is an example of an unsuccessful response from the Retrieve Programme API:

{
  "code": "PROGRAMME_NOT_FOUND",
  "businessMessage": "Programme Not Found",
  "developerMessage": "Programme Not Found",
  "developerLink": "https://developer.avios.com/docs"
}
Name Presence Data type Format Description
code Present String Alphabetsplus under-score (_). Error code. E.g: PROGRAMME_NOT_FOUND Format: Alphabetsplus under-score (_).
businessMessage Present String Alphabets with space Error message to business. E.g.: Programme Not Found Format: Alphabets with space
developerMessage Conditional String Alphabets with space Error message specific to client developer Format: Alphabets with space
developerLink Present String Alphabets plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.). A URL link to a web page containing more detailed information about the error code.E.g. : https://developer.avios.com/docs Format: Alphabets plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.).
childError Conditional Array of complex type [0..n] Will only be present if an error has been detected and reported by the API.
childError.
code
Present String Alphabetsplus under-score (_). Error code. E.g: DATA_INVALID Format: Alphabetsplus under-score (_).
childError.
path
Conditional String Alphabets plus period (.), oblique (/), open bracket ([) or close bracket (]). Path of the node on which error occurred. Format: Alphabets plus period (.), oblique (/), open bracket ([) or close bracket (]).
childError.
businessMessage
Present String Alphabets with space Error message to business. E.g: Data Invalid Format: Alphabets with space
childError.
developerMessage
Conditional String Alphabets with space Error message specific to client developer. Format: Alphabets with space
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.). A URL link to a web page containing more detailed information about the error code. e.g.: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_), question mark (?) or period (.).

Error Codes

HTTP Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID In case the path and query parameters do not follow the format restriction.
400 REQUEST_INVALID MEMBERSHIP_IDENTIFIER_INVALID The specified membership identifier is not valid.
400 PROGRAMME_NOT_FOUND When there is no record for the provided programme identifier.

Register Account

v2

The Register Account API creates a security profile for an existing member within the Avios loyalty platform. The member may have joined from any partner or Avios channel, including offline channels. Registration stores the security credentials that enable the member to log in , along with other data elements such as security responses that enable the member to recover credentials in the future. Registration will only be successful if the member doesn’t have an existing security profile.

The credentials held within the security profile are used to identify the member when they log in to Avios and partner applications, including when a member pays with Avios . The same credentials are used by the member across the entire Avios ecosystem.

Business Context

Here’s the process flow:

Register Account API Flow

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: HTTP status code 201 is returned with an empty response body.

Error outcome: Refer to error code table for list of possible error responses.

Service Details

URI Parameters

Production Endpoint:

`POST https://api.avios.com/{version}/memberships/{membership-identifier}/registrations?api_key={api_key}`

Example

https://api.avios.com/v2/memberships/3081470000000000/registrations?api_key=abcdefabcdefabcdefabcdef
Name Required Data type Format Description Example
version Required String Alphanumeric v[0..9] The version number of the API being called. The correct version is confirmed during the partner on-boarding process. Format: Alphanumeric v[0..9] v2
membership-identifier Required String Numeric only. Min length = 16, Max Length = 24. The membership number of the loyalty programme member which starts with 30814. Format: Numeric only. Min length = 16, Max Length = 24. 0123456789012345
api_key Required String Alphanumeric only. Min length = 24, Max length = 24. The API key provided during the partner configuration that take place as part of the partner on-boarding process. Format: Alphanumeric only. Min length = 24, Max length = 24. abcdefabcdefabcdefabcdef

Request Headers

Name Required Data type Format Description Example
Accept Optional String application/< content-type > The Accept request header is used to specify certain media types that are acceptable for the response. Restricted to application/json. Format: application/< content-type > application/json
Content-Type Required String application/< content-type > The Content-Type request header indicates the media type of the request body sent to the API. Restricted to application/json. Format: application/< content-type > application/json
X-Forwarded-For Optional String Valid IP address Identifies the originating IP address of a consumer. Format: Valid IP address 172.128.25.24

Request Elements

The following is an example of a valid request body for the Register Account API.

{
  "member": {
    "securityProfile": {
      "credentials": {
        "identifier": "my.name@email.com",
        "token": "Passw0rd"
      },
      "securityChallenge": [
        {
          "identifier": "1",
          "response": "O'Reilly"
        },
        {
          "identifier": "2",
          "response": "Newton Abbott"
        }
      ]
    },
    "postalAddress": {
      "postCode": "TEST123"
    }
  }
}

The elements that make up the request message are detailed in the following table and the following rules apply:

Name Required Data type Format Description
member Required Complex type [1..1] The member element represents the details for this registration request.
member.
securityProfile
Required Complex type [1..1] A complex type representing the member’s security profile, which contains the security credentials and responses to the chosen security questions.
member.
securityProfile.
credentials
Required Complex type [1..1] A complex type that represents the member’s security credentials (username and password) for the member’s account within the Avios ecosystem.
member.
securityProfile.
credentials.
identifier
Required String Alphanumeric and special characters period (.), at (@), hyphen (-), underscore (_). Min length: 6, Max length: 50. The username field. This field should not start and end with special characters. Format: Alphanumeric and special characters period (.), at (@), hyphen (-), underscore (_). Min length: 6, Max length: 50.
member.
securityProfile.
credentials.
token
Required String Alphanumeric, accented and special characters. Min length: 8, Max length: 20. The password associated with the account which member will use to login to system. Accented characters passed will not be converted and password will contain them. This must include at least 3 of below rules: At least one number appearing in the string At least one lowercase letter appearing in the string At least one upper case letter appearing in the string At least one special character appearing in the string Format: Alphanumeric, accented and special characters. Min length: 8, Max length: 20.
member.
securityProfile.
securityChallenge
Required Array of Complex type [2..2] An array of 2 elements that represent the responses to the security questions to be used when a member attempts to recover forgotten credentials. Two security responses must be specified and each must have a unique Id within the request (they must have different Ids).
member.
securityProfile.
securityChallenge.
identifier
Required String Numeric only. Min length: 1, Max length: 2. A numeric value that represents the Identifier of the Security Question the response (in the following field) relates to. Maximum value of this element is 12. Format: Numeric only. Min length: 1, Max length: 2.
member.
securityProfile.
securityChallenge.
response
Required String Alphanumeric, special characters and accented characters. ampersand (&), period (.), comma (,), apostrophe (‘), special quote (`), hyphen (-) and space ( ). Min length: 2, Max length: 50. The member’s response to the security challenge (The answer to the security question). This field must start with an alphanumeric character. Accented characters with be converted to respective ASCII character before persisting the value in the system. This conversion is a one-way process, converted ASCII character cannot be translated back to original accented character. Other characters may be alphanumeric. Format: Alphanumeric, special characters and accented characters. ampersand (&), period (.), comma (,), apostrophe (‘), special quote (`), hyphen (-) and space ( ). Min length: 2, Max length: 50.
member.
postalAddress
Conditional Complex type [0..1] A complex type representing a container for the postal address element required as part of a Register Account API request. The following rules are applicable on this element: The PostalAddress element will contain only a PostCode child. This element is conditional based on the country of residence retained in the member’s account during the joining process. Also, refer to Country address rules document. This element will only be used by the service If member is from UK or ZA (South Africa).
member.
postalAddress.
postCode
Required String Alphanumeric. Min Length: 1, Max length: 8. The postCode of the member as previously stored in the member profile within the Avios platform as part of the joining process. This element is a mandatory child within the PostalAddress parent complex type. PostCode is alphanumeric and does not accept any other characters, including space, case insensitive. Format: Alphanumeric. Min Length: 1, Max length: 8.
member.
registeredIdentifier
Conditional Array of Complex type [0..n] A registered form of identity mandatory for some locations and countries. A registered form of identity may be a passport or national identity card. There may be multiple instances of this element required. This element is mandatory for members with country of residence as South Africa. This element will only be used by the service if member is from ZA country (South Africa).
member.
registeredIdentifier.
token
Required String Alphanumeric accented and special characters. Min Length: 1, Max length: 24. The Identifier of the registered form of identity, mandatory when the parent element has been specified. In the case of a passport, this would be the passport number. All special characters are allowed. Format: Alphanumeric accented and special characters. Min Length: 1, Max length: 24.
member.
registeredIdentifier.
type
Required String Enumeration. Type of identification document. Mandatory when the parent element is specified, and must be one of the following: PASSPORT NATIONAL_IDENTITY_CARD Format: Enumeration.
member.
dateOfBirth
Conditional String YYYY-MM-DD ISO-8601 calendar date format. Date of birth for the member as stored in the member’s account within the Avios loyalty platform as part of the Join Programme process. This element is required if the member resides in countries other than United Kingdom (GB) and South Africa (ZA.). Format: YYYY-MM-DD ISO-8601 calendar date format.

Response Message

The Register Account API response is limited to mitigate any information disclosure vulnerability. A typical response will return success or failure as an HTTP status code, in this case a 201 for success. In the event of an error occurring, an appropriate error message will be returned.

Exception Message Elements

The following is an example of an error response.

{
  "error": {
    "code": "SECURITY_PROFILE_ALREADY_EXISTS",
    "businessMessage": "Security Profile Already Exists",
    "developerLink": "https://developer.avios.com/docs"
  }
}
Name Presence Data type Format Description
error Conditional Complex type [0...1] Will only be present if an error has been detected and reported by the API.
error.
code
Present String Alphabetic plus under-score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_).
error.
businessMessage
Present String Alphabetic A business level message describing the error, which has occurred. Example: Request Invalid Format: Alphabetic
error.
developerMessage
Conditional String Alphabetic Developer 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 String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
error.
childError
Conditional Array of complex type [0...n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
error.
childError.
code
Present String Alphabetic plus under-score (_). The error code for the child error (if returned). Example: DATA_INVALID Format: Alphabetic plus under-score (_).
error.
childError.
path
Conditional String Alphabetic plus period (.), oblique (.), open bracket ([) or close bracket (]). Identifies the element in the request, which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing. Format: Alphabetic plus period (.), oblique (.), open bracket ([) or close bracket (]).
error.
childError.
businessMessage
Present String Alphabetic A business level message describing the error, which has occurred. Example: Programme not supported Format: Alphabetic

Error Codes

HTTP Status Code Parent Error Code Child Error Code Description
400 REQUEST_INVALID MANDATORY_DATA_MISSING A mandatory element is missing from the request and must be provided.
400 REQUEST_INVALID DATA_INVALID An element has been specified, but fails to meet the defined validation rules.
400 REQUEST_INVALID CUSTOMER_AGE_INVALID Date of birth cannot be under 18 years.
415 REQUEST_INVALID HEADER_INVALID The provided Content-Type header is invalid.
400 AUTHENTICATION_FAILED The member could not be identified successfully based upon the post code or date of birth or registerIdentifier. This error also will be returned if member which resides in ZA wants to create a security profile but security profile already exists.
400 USERNAME_ALREADY_EXISTS The specified username already exists.
400 SECURITY_PROFILE_ALREADY_EXISTS A security profile already exists for the specified member, i.e. the member must have successfully registered previously.
400 REGISTRATION_FAILED Registration could fail as a result of: The member could not be found The account is disabled or locked Security question identifiers have the same IDs.

Retrieve Account

v2

The Retrieve Account API enables a member to retrieve their account details. The API also allows a partner (the caller of the service) to filter information based on what has been requested. If nothing is explicitly specified then the entire response is returned as per the service response contract.

Business Context

Here’s the process flow:

Retrieve Account API Flow

Important Technical Notes

In order to call Retrieve Account, a token must have been obtained via the Create Token API. The following steps are performed by the Retrieve Account application:

Pre-Conditions

Post Conditions

Success outcome: Account details are returned in the API 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}?api_key={api_key}'

Example

https://api.avios.com/v2/programmes/ATRP/accounts/3081470000000000?api_key=abcdefabcdefabcdefabcdef
Name Required Type Format Description Example
version Required String Alphanumeric v[0..9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric v[0..9] V2
Programme-identifier Required String Alphabetic only. Min length = 1, Max Length = 20. The loyalty programme that holds an account. This would have been provided to the partner as part of the Avios API partner on-boarding process along with the API key and Mashery credentials. Format: Alphabetic only. Min length = 1, Max Length = 20. ATRP
Account-identifier Required Numeric Numeric only. Min length = 16, Max Length = 24. Membership number starting with 308147. Format: Numeric only. Min length = 16, Max Length = 24. 3081470000000000
fields Optional String Enumeration Identifies the specific account element which Partner has requested. If nothing is specified the full set of account data is returned. Supported values: Balance, accountStatus, LastActivityDate, AccountType. Format: Enumeration AccountType
api_key Required String alpha-numeric. Min length = 24, Max Length = 24 The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: alpha-numeric. Min length = 24, Max Length = 24 abcdefabcdefabcdefabcdef

Request Header

Name Required Type Format Description Example
Accept Optional String application/< content-type > The Accept request-header field specifies certain media types, which are acceptable for the response. Restricted to application/json. Format: application/< content-type > Application/JSON
Authorization Required String JWT token The 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 String Valid IP address Identifies the originating IP address of the member. Format: Valid IP address 192.168.69.63
X-Agent-Id Optional String Alphanumeric An agent Id represents the agent name/user name/login id for offline channels like call centres. Format: Alphanumeric Masanobu.Fukuoka

Response Elements

The elements that make up the response message are detailed in the following table.

Examples of Responses

The following shows 3 examples ofresponses generated by the Retrieve Account API:

Example 1. Full account data returned:

{
  "accountType": "INDIVIDUAL",
  "accountStatus": "ACTIVE",
  "lastActivityDate": "2016-05-31",
  "balance": {
    "amount": 100000,
    "currency": {
      "currencyCode": "AVIOS"
    }
  }
}

Example 2. Only balance returned from account:

{
  "balance": {
    "amount": 100000,
    "currency": {
      "currencyCode": "AVIOS"
    }
  }
}

Example 3. Last activity date and balance information returned from account:

{
  "lastActivityDate": "2016-05-31",
  "balance": {
    "amount": 100000,
    "currency": {
      "currencyCode": "AVIOS"
    }
  }
}
Name Presence Type Format Description
accountType Optional String Enumeration Represents the type of account.Will be present only when it is requested for. Possible values are: INDIVIDUAL HOUSEHOLD Format: Enumeration
accountStatus Optional String Alphabetic only. Min length: 1, Max length: 10. Represents the account status. Will be present only when it is requested for. Format: Alphabetic only. Min length: 1, Max length: 10.
lastActivityDate Optional Date YYYY-MM-DD ISO-8601 Represents the last transaction date of member. Will be present only when it is requested for. Format: YYYY-MM-DD ISO-8601
balance Optional Complex type [0..1] Encapsulates the balance information for the account. Will be present only when it is requested for.
balance.
amount
Present Integer Numeric Represents the AVIOS amount the account has. Format: Numeric
balance.
currency
Present Complex type [0..1]
balance.
currency.
currencyCode
Present String Enumeration The currency code. Possible value is “AVIOS”. Format: Enumeration

Exception Message Elements

The following shows an example of anerror response generated by the Retrieve Account API:

Example of an Error Response

{
  "code": "REQUEST_INVALID",
  "businessMessage": "Request Invalid",
  "developerMessage": "Request Invalid",
  "developerLink": "https://developer.avios.com/docs",
  "childError": [
    {
      "code": "DATA_INVALID",
      "path": "fields",
      "businessMessage": "Data Invalid",
      "developerMessage": "Value of fields invalid",
      "developerLink": "https://developer.avios.com/docs"
    }
  ]
}

Example 2: Note: below errors will differ from other errors with their structure and will come with “error” element as parent of error response:

  1. SYSTEM_UNAVAILABLE
  2. DEVELOPER_NOT_AUTHORIZED
  3. DEVELOPER_INACTIVE
  4. USAGE_RATE_EXCEEDED
  5. USAGE_RATE_LIMIT_EXCEEDED
  6. SSL_REQUIRED
  7. GATEWAY_TIMEOUT
{
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "businessMessage": "Request Unauthorized",
    "developerMessage": "Request Unauthorized",
    "developerLink": "https://developer.avios.com/docs"
  }
}
Name Presence Type Format Description
code Present String Alphabetic plus under-score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_).
businessMessage Present String Alphabetic A business level message describing the error which has occurred. Example: Request Invalid Format: Alphabetic
developerMessage Conditional String Alphabetic A more technical message describing the error which has occurred. Format: Alphabetic
developerLink Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
childError Conditional Array of complex type [0. .n] Present for certain errors (e.g. validation) where more than error may have occurred.
childError.
code
Present String Alphabetic plus under-score (_). The error code for the child error (if returned). Example: DATA_INVALID Format: Alphabetic plus under-score (_).
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Identifies the element in the request which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing. Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
childError.
businessMessage
Present String Alphabetic A business level message describing the error which has occurred. Example: Programme not supported Format: Alphabetic
childError.
developerMessage
Conditional String Alphabetic A more technical message describing the error which has occurred. Format: Alphabetic
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

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

Http Status Code Parent error code Description
400 ACCOUNT_NOT_FOUND The account status is not valid for retrieval.

Retrieve Membership

v2

The Retrieve Membership API responds to valid requests by providing information related to a membership. The service returns membership details only if a valid Access Token for calling member/partner is provided in the request message. This Access Token can only be created by a member/partner having been authenticated.

The profile data returned by this service will have been previously retained within the Avios platform during either a Join Programme process, or an Update Membership process. The data returned in a successful response will contain Membership status and Member Profile along with account and programme details links.

This service will not return Security Profile or account/transaction data elements.

Business Context

A summary of the process flow is as follows:

Retrieve Membership API Flow

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: Membership details are returned in the API response message.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

'GET https://api.avios.com/{version}/memberships/{account-identifier}?api_key={api_key}'

Example

https://api.avios.com/v2/memberships/3081470000000000?api_key=abcdefabcdefacbdefabcdef

Test Endpoint:

https://api.avios.com/test/{version}/memberships/{account-identifier}?api_key={api_key}
Name Required Data type Format Description
version Required String Alphanumeric V[0-9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric V[0-9]
account-identifier Required String Numeric only. Min length = 16, Max Length = 24. The 16-digit membership number starting with 308147. Format: Numeric only. Min length = 16, Max Length = 24.
api_key Required String As supplied by Avios during partner configuration, alpha-numeric. Min Length = 24, Max Length = 24. The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: As supplied by Avios during partner configuration, alpha-numeric. Min Length = 24, Max Length = 24.

Request Headers

Name Required Data type Format Description Example
Accept Optional String Currently restricted to application/json The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted currently. Format: Currently restricted to application/json application/json
Authorization Required String JWT Token An access token authorizing the partner access to this API. Format: JWT Token Bearer:eyJhbGcI1NiJ9
X-Forwarded-For Optional String Valid IP address The originating IP address of a consumer. Format: Valid IP address 172.17.1.1, 172.17.1.2
X-Agent-ID Optional String Alphanumeric. Min length: 2, Max length: 40. An agent Id represents the agent name/user name/login id for offline channels like call centres. Format: Alphanumeric. Min length: 2, Max length: 40. Masanobu12Fukuoka

Response Elements

The following is an example of a response from the Retieve Membership API.

{
  "membershipStatus": "ACTIVE",
  "member": {
    "person": {
      "name": {
        "title": "MR",
        "firstName": "MADAFPGRK",
        "middleInitial": "L",
        "familyName": "HARE"
      },
      "dateOfBirth": "1990-12-15",
      "gender": "MALE",
      "countryOfResidence": "GB",
      "locale": {
        "languageCode": "EN"
      },
      "postalAddresses": {
        "preferredPostalAddress": {
          "type": "PERSONAL",
          "addressLine": ["!@#!@##$%^&*()_+}{", "ASDASD"],
          "country": "UNITED KINGDOM",
          "postCode": "AA73BB"
        },
        "otherPostalAddress": [
          {
            "type": "BUSINESS",
            "addressLine": ["ASTRAL TOWERS BETTS WAY"],
            "country": "UNITED KINGDOM",
            "postCode": "RH109XA"
          }
        ]
      },
      "emailAddresses": {
        "preferredEmailAddress": {
          "email": "myemail@email.com"
        }
      },
      "telecomAddresses": {
        "preferredTelecomAddress": {
          "countryCode": "44",
          "number": "01922311777",
          "type": "BUSINESS",
          "deviceType": "PHONE"
        },
        "otherTelecomAddress": []
      },
      "marketingPreference": [
        {
          "campaignType": "PARTNER",
          "communicationChannel": "POSTAL"
        }
      ],
      "contactPreference": [
        {
          "communicationChannel": "SMS"
        }
      ],
      "deviceAddress": [],
      "profileStatus": "FULL"
    }
  },
  "_links": {
    "account": {
      "href": "https://api.avios.com/test/v2/memberships/3081471029556585/account"
    },
    "programmes": {
      "href": "https://api.avios.com/test/v1/programmes?membership-identifier=3081471029556585"
    },
    "self": {
      "href": "https://api.avios.com/test/v2/memberships/3081471029556585"
    }
  }
}
Name Presence Data type Format Description
membershipStatus Present String Enumeration Represents the membership status. Possible value is “ACTIVE” Format: Enumeration
member Present Complex type [1..1] A complex type that represents the member within Avios systems. This type contains a person.
member.
person
Present Complex type [1..1] A complex type that contains the member’s personal details within Avios systems.
member.
person.
name
Present Complex type [1..1] Contains the name of the member, split into various fields that represent a name in a recognised format. Title, forename, middle initial (if present), family name.
member.
person.
name.
title
Conditional String Alphabetic Max length: 30 Title (Salutation) of the Loyalty programme member. If Title was provided during Join or update membership, it will be retrieved. Format: Alphabetic Max length: 30
member.
person.
name.
firstName
Present String Min Length:1, max Length: 25. Alphabetic plus apostrophe (‘), hyphen (-) and space. First name (forename) of the Loyalty Programme member. May contain the following special characters: apostrophe (‘), hyphen (-), spaces. Format: Min Length:1, max Length: 25. Alphabetic plus apostrophe (‘), hyphen (-) and space.
member.
person.
name.
middleInitial
Conditional String Max Length: 1. Alphabetic. Middle initial of the Loyalty Programme member. Will be present if previously supplied during a Join Programme API. Format: Max Length: 1. Alphabetic.
member.
person.
name.
familyName
Present String Max Length: 40. Alphabetic plus apostrophe (‘), hyphen (-) and space. Surname (or last name) of the Loyalty Programme member. May contain the following special characters: apostrophe (‘), hyphen (-) and spaces. Format: Max Length: 40. Alphabetic plus apostrophe (‘), hyphen (-) and space.
member.
person.
dateOfBirth
Conditional Date The member’s Date of Birth in ISO-8601 Calendar date format. Members who is older than 18 years old can only join loyalty programmes and this field will be present if a date of birth has been previously provided and is no earlier than 1700-04-01. Dates under 1700-04-01 will not be present even if was previously provided.
member.
person.
gender
Present String Enumeration. An indicator of the gender of a member. API will derive the Gender of the member based on gender specific titles (Mr, Mrs, Ms, Miss, Dr, Lady, Sir, and Lord), if any other value will be provided in title element the Gender of the member will be set to NOT_KNOWN. Will be one of the following: MALE FEMALE NOT_KNOWN NOT_KNOWN Format: Enumeration.
member.
person.
registeredIdentifier
Conditional Complex type [0..1] This complex type represents the Identification document provided by the member. In some countries, for example South Africa, there is a requirement to collect recognised Identification when joining. This is typically the passport but could be another government issued Identification document. This element will be visible in the response if the country of residence is South Africa.
Member.
person.
registeredIdentifier.
token
Present String Max length: 24. Alphanumeric. The passport number or other Identification Card issue number for the Identification provided by the member as part of the Join process. Format: Max length: 24. Alphanumeric.
Member.
person.
registeredIdentifier.
placeOfIssue
Present Complex type [1..1] Place of issue of the identity document related to the token provided above.
Member.
person.
registeredIdentifier.
placeOfIssue.
identifier
Present String Max length: 2, min length: 2. ISO 3166-1 two character alphabetic Country code. Location identifier of the place where identification document has been issued. Format: Max length: 2, min length: 2. ISO 3166-1 two character alphabetic Country code.
member.
person.
registeredIdentifier.
placeOfIssue.
type
Present String Enumeration. The type of location for place of issue. Case sensitive and will be “COUNTRY”. Format: Enumeration.
member.
person.
registeredIdentifier.
type
Present String Enumeration. Type of identification document. Will be one of the following: PASSPORT NATIONAL_IDENTITY_CARD Format: Enumeration.
member.
person.
countryOfResidence
Conditional String ISO 2 digit. Max length :2 The 2-digit ISO code for the country where the member is registered. This will be present in response if supplied during join or update membership details. Example: GB Format: ISO 2 digit. Max length :2
member.
person.
locale
Present Complex type [1..1] A complex type that represents the chosen locale of the Member.
member.
person.
locale.
languageCode
Present String ISO 639-1. Alphabetic 2 character language code. Max Length :2 If language code was not provided in join or update member API default ‘EN’ is assigned. Preferred language of the member for use within Avios systems and channels. Will be one of the following values: EN ES CA FR IT Format: ISO 639-1. Alphabetic 2 character language code. Max Length :2
member.
person.
postalAddresses
Conditional Complex type [1..1] A complex type that represents the Member’s postal addresses. This will be present in response if supplied during join or update membership details
member.
person.
postalAddresses.
preferredPostalAddress
Present Complex type [1..1] A complex type representing the preferred postal address of the member.
member.
person.
postalAddresses.
preferredPostalAddress.
type
Present String Enumeration A string representing the type of the Member’s preferred postal address. Will be one of the following: PERSONAL Format: Enumeration
member.
person.
postalAddresses.
preferredPostalAddress.
addressLine
Present Array of string [1..5] Max length: 30. Alphanumeric plus the following all ASCII printable special characters. An array of string values, each of which represents a line of the member’s preferred postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be present. For countries where postcode is mandatory, at least one line ofaddress should be present. There will not be a comma (,) present at the end of each address line. Format: Max length: 30. Alphanumeric plus the following all ASCII printable special characters.
member.
person.
postalAddresses.
preferredPostalAddress.
country
Present String Alphabetic with special character space ( ) Postal address country name. Example: UNITED KINGDOM Format: Alphabetic with special character space ( )
member.
person.
postalAddresses.
preferredPostalAddress.
postCode
Conditional String Max length: 8. Alphanumeric The Postal code of address for the Member’s preferred postal address, if the address contains one this value will be present in the response. Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8. Alphanumeric
member.
person.
postalAddresses.
otherPostalAddress
Conditional Array of Complex type [0..1] Other postal address details. Optional postal address in addition to the preferred postal address
member.
person.
postalAddresses.
otherPostalAddress.
type
Present String Enumeration Type of postal address. Will be one of the following: BUSINESS Format: Enumeration
member.
person.
postalAddresses.
otherPostalAddress.
addressLine
Present Array of string [1..5] Max length: 30. Alphanumeric plus all ASCII printable special characters An array of string values, each of which represents a line of the member’s other postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided For countries where postcode is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesPlease refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30. Alphanumeric plus all ASCII printable special characters
member.
person.
postalAddresses.
otherPostalAddress.
country
Present String Alphabetic with space. Postal address country name. Example: UNITED KINGDOM Format: Alphabetic with space.
member.
person.
postalAddresses.
otherPostalAddress.
postcode
Conditional String Max length: 8 Alphanumeric The Postal code of address for the Member’s other postal address, if the address contains one this value will be present in the response. The postcode is returned without an embedded space. Example: RH109XA Format: Max length: 8 Alphanumeric
member.
person.
emailAddresses
Present Complex type [1..1] A complex type representing the Member’s email addresses.
member.
person.
emailAddresses.
preferredEmailAddress
Present Complex type [1..1] A complex type representing the Member’s preferred email address.
member.
person.
emailAddresses.
preferredEmailAddress.
email
Present String Alphanumeric Max length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%). Email address of the member. There may be only a single at-sign present. Also, all special characters can be specified before the at-sign and just minus (-) and period (.) after at-sign. Period (.) can’t be before at(@). Format: Alphanumeric Max length: 50 with special characters period (.), underscore (_), plus (+), minus (-) and at-sign (@), percentage (%).
member.
person.
telecomAddresses
Conditional Complex type [1..1] A complex type that represents a collection of Member’s fully elaborated telephone numbers, which include country and area codes. Area code and number will be combined in the response in a single field. This will be present in response if supplied during join or update membership details.
member.
person.
telecomAddresses.
preferredTelecomAddress
Present Complex type [1..1] A complex type that represents a Member’s preferred telephone number.
member.
person.
telecomAddresses.
preferredTelecomAddress.
countryCode
Present String Numeric. Max length: 5. International dialling code. The direct dialling code required to call the preferred telecom address from another country. Also referred to as the International Subscriber Dialling (ISD) code. This value will not be prefixed with leading zeros or a plus (+), for example UK telephone numbers will have a country code value of 44 Format: Numeric. Max length: 5. International dialling code.
member.
person.
telecomAddresses.
preferredTelecomAddress.
number
Present String Max length: 15. Numeric. The member’s preferred telephone number (telecom address). This will include the area code but not the country code. Example.: 01924311750 Format: Max length: 15. Numeric.
member.
person.
telecomAddresses.
preferredTelecomAddress.
type
Present String Enumeration. Telecom address type. Will be one of the following: BUSINESS PERSONAL Format: Enumeration.
member.
person.
telecomAddresses.
preferredTelecomAddress.
deviceType
Present String Enumeration. Telecom address device type. Will be one of the following: PHONE MOBILE Format: Enumeration.
member.
person.
telecomAddresses.
otherTelecomAddress
Conditional Array of complex type [0..2] Other telecom address in addition to the preferred telecom address. Will be visible if member will have more than one type of phone. A member could have more than one telephone number. Avios can store up to 3 telephone numbers for each member, including the preferred telecom address.
member.
person.
telecomAddresses.
otherTelecomAddress.
countryCode
Present String Numeric characters Telecom addresses country code. The total string length of the countryCode, areaCode and the telephone number cannot exceed 15 characters. Format: Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
number
Present String Max length: 15. Numeric characters. The body of the Member’s preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. Format: Max length: 15. Numeric characters.
member.
person.
telecomAddresses.
otherTelecomAddress.
type
Present String Enumeration Telecom addresses type. Case sensitive and must be one of the following: BUSINESS PERSONAL The following combinations of deviceType and type are accepted by the application: If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone numberis saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. Format: Enumeration
member.
person.
telecomAddresses.
otherTelecomAddress.
deviceType
Present String Enumeration Telecom address device type. Must be one of the following: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. Format: Enumeration
member.
person.
marketingPreference
Conditional Array of complex type [0..2] Member’s preference for receiving Avios marketing communications. This element can occur multiple times. API will return this element if it was specified with previously. For internal Avios use only.
member.
person.
marketingPreference.
campaignType
Present String Enumeration Promotion activity of a product conducted by the Partner. Will be one of the following: TRAVEL_OFFERS PARTNER For internal Avios use only. Format: Enumeration
member.
person.
marketingPreference.
communicationChannel
Present String Enumeration Channel of communication preferred by the member to receive marketing information. Will always be “POSTAL”. For internal Avios use only. Format: Enumeration
member.
person.
contactPreference
Conditional Array of complex type [0..3] Member’s preference of being contacted by Partner/Loyalty Programme. This element can occur multiple times. API will return this element if it was specified with previously. For internal Avios use only.
member.
person.
contactPreference.
communicationChannel
Present String Enumeration. Channel of communication preferred by the member to receive partner’s marketing information. Will be one of the following: EMAIL PHONE SMS For internal Avios use only. Format: Enumeration.
member.
person.
deviceAddress
Present Array of complex type [1..n] Specified the device address details. Will not contain child elements.
member.
person.
profileStatus
Present String Enumeration Specifies the profile status: FULL PARTIAL Format: Enumeration
_links Present Complex type [1..1] Contains hypermedia links to represent account and program information
_links.
self
Present Complex type [1..1] A complex type that represents a link to ‘self’.
_links.
self.
href
Present String Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&) A string containing the URI that uniquely defines a link to this resource. Format: Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&)
_links.
account
Present Complex type [1..1] A complex type that represents a link to the associated account.
_links.
account.
href
Present String Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&) A string containing the URI that uniquely defines a link to the Account resource for this Membership. Format: Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&)
_links.
programmes
Present Complex type [1..1] A complex type that represents a link to the programmes associated with this Membership.
_links.
programme.
href
Present String Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&) A string containing the URI that uniquely defines a link to the Account resource for this Membership. Format: Alphanumeric plus colon (:), oblique (/), dash (-), question mark (?), underscore (_), equals (=), period (.) or ampersand (&)

Exception Message Elements

The following is an example of an error response from the Retieve Membership API.

{
  "code": "REQUEST_UNAUTHORIZED",
  "businessMessage": "Request Unauthorized",
  "developerMessage": "Request Unauthorized",
  "developerLink": "https://developer.avios.com/docs",
  "childError": [
    {
      "code": "DATA_INVALID",
      "businessMessage": "Data Invalid",
      "developerMessage": "Data Invalid",
      "developerLink": "https://developer.avios.com/docs"
    }
  ]
}
Name Presence Data type Format Description
code Present String Alphabetic plus under-score (_). Error code. Example: REQUEST_UNAUTHORIZED Format: Alphabetic plus under-score (_).
businessMessage Present String Alphabets with space Error message to business. Example: Request unauthorized Format: Alphabets with space
developerMessage Conditional String Alphabets with space Developer message will be present when detailed technical description is required for the error, which has occurredby the API. If no specific developer message is required, developer message will be as business message. Format: Alphabets with space
developerLink Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
childError Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
childError.
code
Present String Alphabetic plus under-score (_). Error code. Example: DATA_INVALID Format: Alphabetic plus under-score (_).
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Identifies the element in the request, which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
childError.
businessMessage
Present String Alphabets with space Error message to business. Example: Data invalid Format: Alphabets with space
childError.
developerMessage
Present String Alphabets with space Developer 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: Alphabets with space
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

Http Status Code Parent error code Description
400 MEMBERSHIP_NOT_FOUND When an account status associated with the provided membership identifier is in fraud status.

Update Membership

v3

The Update Membership API enables a partner to update personal and programme information for an existing membership. The API updates membership details only when a membership number has been identified and a valid access token has been received.

The Update Membership API accepts partial membership information updates. For example, the address could be passed in the API request in isolation, without other details. In this scenario, only the address will be updated and the other pre-existing data will remain unchanged. The API allows the postal address not to be validated and will allow it to stay in the format provided.

Business Context

Here’s the process flow:

Update Membership API Flow

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: HTTP status code 204 is returned with an empty response body.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

PATCH https://api.avios.com/{version}/memberships/{membership-identifier}?api_key={api_key}

Example

https://api.avios.com/v3/memberships/3081470000000000?api_key=abcdef

Test Endpoint:

https://api.avios.com/test/{version}/memberships/{membership-identifier}?api_key={api_key}
Name Required Type Format Description Example
version Required String Alphanumeric V[0..9] The version of the API, which will be confirmed during the on-boarding process. Format: Alphanumeric V[0..9] v3
membership-identifier Required String Min length = 16 Max Length = 24 Numeric. The membership number of the loyalty programme member. Format: Min length = 16 Max Length = 24 Numeric. 3081470000000000
api_key Required String Alphanumeric only. Min length = 24 Max length = 24 The API key provided during the partner configuration which takes place as part of the partner on-boarding process. Format: Alphanumeric only. Min length = 24 Max length = 24 abcdefabdefabdefabcdef

Request Headers

Name Required Type Format Description Example
Accept Optional String application/json The Accept request-header field is used to specify certain media types, which are acceptable for the response. Only application/json is accepted currently. Format: application/json application/json
Content-Type Required String application/json The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted currently. Format: application/json application/json
X-Forwarded-For Optional String Comma separated valid IP addresses The IP address of the end customer. API will validate only first provided IP address, second and following IP addresses will not be validated. Format: Comma separated valid IP addresses "172.17.1.1", "172.17.1.2"
Authorization Required String JWT Token An access token authorising the partner access to this API. Format: JWT Token Bearer:eyJhbGcI1Ni J9

Request Elements

The following is an example of a request call to the Update Membership API:

{
  "member": {
    "person": {
      "emailAddresses": {
        "preferredEmailAddress": {
          "email": "oskar.k@avios.com"
        }
      }
    }
  }
}
Name Required Type Format Description
member Optional Complex type [0..1] A complex type that represents the member within Avios systems. This type contains a person child element.
member.
person
Required Complex type [1..1] Represents the member within Avios systems.
member.
person.
name
Optional Complex type [0..1] Contains the name of the member, split into various fields that represent a name in a recognised format. As only Title may be updated via the Avios API platform, this is the only field available in the Update Membership API request. All other name fields may only be updated offline.
member.
person.
name.
title
Required String Min Length: 1 Max length: 30 Alphabetic. Title (Salutation) of the member.The title may only be updated for a member via this API if the membership does not already contain title. Format: Min Length: 1 Max length: 30 Alphabetic.
member.
person.
dateOfBirth
Conditional ISO-8601 Date YYYY-MM-DD ISO-8601 The member's Date of Birth in ISO-8601 Calendar date format. The Date of Birth may only be updated for a member via this API if the membership does not already contain a Date of Birth. Error will be returned if DOB of member is less than 18 years old. Date of birth is accepted from 1000-01-01. Future date of birth isn't accepted. Format: YYYY-MM-DD ISO-8601
member.
person.
locale
Optional Complex type [0..1] The local for the member, contains the preferred language as 'languageCode'.
member.
person.
locale.
languageCode
Required ISO 639-1 String Max length: 2 (ISO 639-1 Alphabetic 2 character language code) Preferred language of the member for use within Avios systems and channels. Case insensitive. Supported values are: IT; ES; CA; FR; EN Format: Max length: 2 (ISO 639-1 Alphabetic 2 character language code)
member.
person.
postalAddresses
Optional Complex type [0..1] A complex type representing the Member's postal addresses.
member.
person.
postalAddresses.
preferredPostalAddress
Required Complex type [1..1] A complex type representing the preferred postal address of the member.
member.
person.
postalAddresses.
preferredPostalAddress.
type
Required String Enumeration Type of postal address. Case sensitive and must be one of the following: PERSONAL Format: Enumeration
member.
person.
postalAddresses.
preferredPostalAddress.
addressLine
Required Array of string [1..4] Max length: 30 Alphanumeric plus period (.), comma (,), ampersand (&), dash (-), apostrophe (' `), space ( ) and accented characters. An array of string values, each of which represents a line of the member's preferred postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided. For countries where post code is mandatory, at least one line of address should be provided. There should not be a comma (,) at the end of each address line. The request should follow JSON format for providing multiple address lines Format: Max length: 30 Alphanumeric plus period (.), comma (,), ampersand (&), dash (-), apostrophe (' `), space ( ) and accented characters.
member.
person.
postalAddresses.
preferredPostalAddress.
country
Required ISO 3166-1 String Max length: 2 ISO 3166-1 Alphabetic 2 character country code. The country of the member's preferred address. Case insensitive. This field will determine the member's Market within Avios systems, which will not have an impact on the Partner's interactions with the customer. Format: Max length: 2 ISO 3166-1 Alphabetic 2 character country code.
member.
person.
postalAddresses.
preferredPostalAddress.
postCode
Conditional String Max length: 8 Alphanumeric Postal code of member's preferred address. Must not contain spaces. Format: Max length: 8 Alphanumeric
member.
person.
postalAddresses.
preferredPostalAddress.
validationSource
Optional String Enumeration This specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (System Validation required) SYSTEM (System Validation required) Omitting this field in the request has the same effect as providing a value of SYSTEM. Now EXPLICIT and SYSTEM provides the same functionality. Format: Enumeration
member.
person.
postalAddresses.
otherPostalAddress
Optional Complex type [0..1] Optional postal address in addition to the preferred postal address.
member.
person.
postalAddresses.
otherPostalAddress.
type
Required String Enumeration. Type of postal address. Case sensitive and must be one of the following: BUSINESS Format: Enumeration.
member.
person.
postalAddresses.
otherPostalAddress.
addressLine
Required Array of string [1..4] Max length: 30 Alphanumeric plus period (.), comma (,), ampersand (&), dash (-), apostrophe (' `), space ( ) and accented characters. An array of string values, each of which represents a line of the member's other postal address, excluding postcode and country. For countries where postcode is not mandatory, at least two lines of address should be provided For countries where post code is mandatory, at least one line of address should be provided There should not be a comma (,) at the end of each address line The request should follow JSON format for providing multiple address linesThe field can also have accented characters, which will be converted to equivalent ASCII before any validations. Refer Appendix F for details. Please refer to the Country Address Rules document, which identifies the mandatory elements for each country. Format: Max length: 30 Alphanumeric plus period (.), comma (,), ampersand (&), dash (-), apostrophe (' `), space ( ) and accented characters.
member.
person.
postalAddresses.
otherPostalAddress.
country
Required ISO 3166-1 String Max length: 2 ISO 3166-1 Alphabetic 2 character country code. The country of the member's other address. Case insensitive.This field will determine the member's Market within Avios systems, which will not have an impact on the Partner's interactions with the customer. Format: Max length: 2 ISO 3166-1 Alphabetic 2 character country code.
member.
person.
postalAddresses.
otherPostalAddress.
postCode
Conditional String Max length: 8 Alphanumeric Postal code of member's other address. Must not contain spaces. Format: Max length: 8 Alphanumeric
member.
person.
postalAddresses.
otherPostalAddress.
validationSource
Optional String Enumeration This specifies whether address needs to be validated. Case sensitive and the value provided must be one of the following: EXPLICIT (System Validation required) SYSTEM (System Validation required) Omitting this field in the request has the same effect as providing a value of SYSTEM. Now EXPLICIT and SYSTEM provides the same functionality. Format: Enumeration
member.
person.
emailAddresses
Optional Complex type [0..1] A complex type representing the Member's email addresses.
member.
person.
emailAddresses.
preferredEmailAddress
Required Complex type [1..1] A complex type representing the Member's preferred email address.
member.
person.
emailAddresses.
preferredEmailAddress.
email
Required String Max length: 50 Alphanumeric with special characters. Email address of the member. There will be only a single at-sign present. Also, all special characters can be visible before the at-sign and only minus (-) and period (.) after at-sign. Format: Max length: 50 Alphanumeric with special characters.
member.
person.
telecomAddresses
Optional Complex type [0.1] A complex type that represents a collection of Member's fully elaborated telephone numbers, which include country and area codes.
member.
person.
telecomAddresses.
preferredTele comAddress
Required Complex type [1..1] A complex type that represents a Member's preferred telephone number. This element will update telecomAddress details for member.
member.
person.
telecomAddresses.
preferredTele comAddress.
countryCode
Optional String Max length: 5 Numeric The direct dialling code required to call the preferred telecom address from another country. Also referred to as the International Subscriber Dialling (ISD) code. This value will not be prefixed with leading zeros or a plus (+), for example UK telephone numbers will have a country code value of 44. Format: Max length: 5 Numeric
member.
person.
telecomAddresses.
preferredTele comAddress.
areaCode
Optional String Max length: 5 Numeric The area code element of the Member's preferred telecom address.The total length of combination of the area code and the number cannot exceed 15 characters. Format: Max length: 5 Numeric
member.
person.
telecomAddresses.
preferredTelecomAddress.
number
Required String Max length: 15 Numeric The body of the Member's preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. Format: Max length: 15 Numeric
member.
person.
telecomAddresses.
preferredTelecomAddress.
type
Required String Enumeration Telecom addresses type. Must be one of the following and case sensitive: BUSINESS PERSONAL The following combinations of deviceType and type are accepted by the application: If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone; or If deviceType = phone and type = Business, the telephone number is saved as a work phone; or If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. There are 3 different types of telecom address mobile, work and home phones. If member has one type of telecom address and update membership API gets request with the same type, API updates telecom address details, if update membership gets request with different type of telecom address than member already has, it doesn't update existing phone details but provided details are saved as other telecom address. Member can have 3 different types of telecom address. Format: Enumeration
member.
person.
telecomAddresses.
preferredTelecomAddress.
deviceType
Required String Enumeration Telecom addresses device type. Must be one of the following and case sensitive: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. Format: Enumeration
member.
person.
telecomAddresses.
otherTelecom Address
Optional Array of complex type [0..2] Other telecom address in addition to the preferred telecom address. A member could have more than one telephone number. Avios can store up to 3 telephone numbers for each member, including the preferred telecom address. This element won't update telecom address details even if passed in request message.
member.
person.
telecomAddresses.
otherTelecomAddress.
countryCode
Optional String Numeric characters Telecom addresses country code. The total string length of the countryCode, areaCode and the telephone number cannot exceed 15 characters. This element won't update telecom address details even if passed in request message. Format: Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
areaCode
Optional String Max length: 15 Numeric characters Telecom address area code. The total string length of the areaCode and the telephone number cannot exceed 15 characters. This element won't update telecom address details even if passed in request message. Format: Max length: 15 Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
number
Required String Max length: 15 Numeric characters The body of the Member's preferred phone number (Preferred Telecom Address). The total length of combination of the area code and the number cannot exceed 15 characters. This element won't update telecom address details even if passed in request message. Format: Max length: 15 Numeric characters
member.
person.
telecomAddresses.
otherTelecomAddress.
type
Required String Enumeration Telecom addresses type. Case sensitive and must be one of the following: BUSINESS PERSONAL The following combinations of deviceType and type are accepted by the application:If deviceType = mobile and type = Personal, the telephone number is saved as a mobile phone. If deviceType = phone and type = Business, the telephone number is saved as a work phone. If deviceType = phone and type = Personal, the telephone number is saved as a home phone.Any other combination will result in error. This element won't update telecom address details even if passed in request message. Format: Enumeration
member.
person.
telecomAddresses.
otherTelecomAddress.
deviceType
Required String Enumeration Telecom address device type. Must be one of the following: PHONE MOBILE This field and Type, described above, are interrelated as per the Description for the Type field above. This element won't update telecom address details even if passed in request message. Format: Enumeration
member.
person.
marketingPreference
Optional Array of complex type [0..2] Member's preference for receiving marketing communications from Loyalty Programme in relation to products offering. There may be multiple instances of this element. There can only be passed two marketing preference objects with different campaign type channels. If there are passed few marketing preference objects with same campaign types error will be returned.
member.
person.
marketingPreference.
campaignType
Required String Enumeration Promotion activity of a product conducted by the Partner. Must be one of the following: TRAVEL_OFFERS PARTNER The following combinations are allowed:communicationChannel = POSTAL and campaignType = PARTNER for third party marketing communications by Post. communicationChannel = POSTAL and campaignType = TRAVEL_OFFERS for Avios marketing communications by Post.Any other combination will result in error. Format: Enumeration
member.
person.
marketingPreference.
communicationChannel
Required String Enumeration Channel of communication preferred by the member to receive partner's marketing information. Must be "POSTAL". This field and Type, described above, are interrelated as per the Description for the campaignType field above. Format: Enumeration
member.
person.
marketingPreference.
selected
Required String Enumeration Indicator if selection is Yes (Y) or No (N). Specifies if member wants to be contacted through specified communication channel. Decides if contact preference details will be returned in other APIs Example: retrieve Membership. Format: Enumeration
member.
person.
contactPreference
Optional Array of complex type [0..3] Member's preference of being contacted by Partner/Loyalty Programme. There may be multiple instances of this element. There can only be passed three contact preference objects with different communication channels. If there are passed few contact preference objects with same communication channel error will be returned.
member.
person.
contactPreference.
communicationChannel
Required String Enumeration Channel of communication preferred by the member to receive partner's marketing information. The following combinations are allowed:communicationChannel = EMAIL for communications via email. communicationChannel = SMS for communications via SMS. communicationChannel = PHONE for communications via phone.Any other combination will result in error. Format: Enumeration
member.
person.
contactPreference.
selected
Required String Enumeration Indicator if selection is Yes (Y) or No (N). Specifies if member wants to be contacted through specified communication channel. Decides if contact preference details will be returned in other APIs Example: retrieve Membership. Format: Enumeration
programme Optional Complex type [0..1] The loyalty programme to be associated with the membership.
programme.
identifier
Required String Enumeration The identifier of the loyalty programme. Details of values to be provided will be supplied to the partner. Format: Enumeration

Exception Message Elements

The exception message responses may be formatted in either upper or lower case. An example of an error response is shown:

{
  "code": "REQUEST_UNAUTHORIZED",
  "businessMessage": "Request Unauthorized",
  "developerMessage": "Request Unauthorized",
  "developerLink": "https://developer.avios.com/docs",
  "childError": [
    {
      "code": "TOKEN_EXPIRED",
      "businessMessage": "Token expired",
      "developerMessage": "Token expired",
      "developerLink": "https://developer.avios.com/docs"
    }
  ]
}
Name Presence Type Format Description
code Present String Alphabetic plus under-score (_) Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_)
businessMessage Present String Alphabetic A business level message describing the error, which has occurred. Example: Request Invalid Format: Alphabetic
developerMessage Conditional String Alphabetic Developer 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
developerLink Present String Alphabetic plus colon (:), oblique (.), dash (-), underscore (_) or period (.) A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (.), dash (-), underscore (_) or period (.)
childError Conditional Array of complex [0..n] Present for certain errors (Example: validation) where one or more child error may have occurred.
childError.
code
Present String Alphabetic plus under-score (_) The error code for the child error (if returned) Example: DATA_INVALID Format: Alphabetic plus under-score (_)
childError.
path
Conditional String Alphabetic plus period (.), oblique (.), open bracket ([) or close bracket (]). Identifies the element in the request, which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing. Format: Alphabetic plus period (.), oblique (.), open bracket ([) or close bracket (]).
childError.
businessMessage
Present String Alphabetic A business level message describing the error, which has occurred. Exampl: Programme not supported Format: Alphabetic
childError.
developerMessage
Conditional String Alphabetic Developer message will be present when detailed technical description is required for the child error, which has occurred, by the API. Example: 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
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.) A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.)

Error codes

HTTP Status Code Parent error code Child error code Description
400 REQUEST_INVALID MANDATORY_DATA_MISSING A mandatory element is missing from the request or request details doesn't follow JSON message contact.
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract
400 REQUEST_INVALID PHONE_NUMBER_INVALID The specified phone number is not valid for the member's country of residence.
400 REQUEST_INVALID POSTAL_ADDRESS_INVALID The specified postal address is not valid. Country or postcode is incorrect.
400 REQUEST_INVALID PROGRAMME_INVALID The specified programme is invalid, it either isn't associated with the consumer or the member is already associated with the programme
400 ADDRESS_NOT_SUPPORTED The following combination of Device type and address type are accepted by the application: If device type is mobile & address Type is Personal, it is saved as a mobile phone. If device type is phone & address Type is Business, it is saved as a work phone. If device type is phone & address Type is Personal, it is saved as a home phone. Any other combination will result in an error. This error will be returned also if type element will have value 'BUSINESS' under preferredPostalAddress or preferredPostalAddress and otherPostalAddress type element has the same value.
400 DETAILS_ALREADY_EXIST The provided details cannot be updated in the membership record. Example:, title, DoB already exist or postalAddress contains other country than member was originally registered.
500 Internal server error for provided member who is younger than 18 years old or contactPreference or marketingPreference has multiple communication channels with same values.

Credit Currency

v1

The Credit Currency API allows partners to credit Avios to member accounts. Each credit request will immediately credit an account on successful processing of request.

This service will credit an account with a number of Avios awarded for a range of activities including non-air transactions, transactions for full return flights or a transaction for one leg of a return flight. Credit Currency API will return a unique transaction identifier for each credit transaction.

Business Context

Here’s the process flow:

Credit Currency API Flow

Technical Context

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: The member’s account is credited with the amount as specified in the credit transaction request.

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

'POST https://api.avios.com/{version}/programmes/{programme-identifier}/accounts/{account-identifier}/credit-transaction-requests?api_key={api_key}'

Example URI

https://api.avios.com/v1/programmes/ATRP/accounts/3081470000000000/credit-transaction-requests?api_key=abcdef
Name Required Data type Format Description Example
version Required String Alphanumeric v[0-9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric v[0-9] v1
account-identifier Required Numeric Min length = 1 Max Length = 24 Numeric only Unique Identifier of the member of the loyalty programme, e.g. membership number. Format: Min length = 1 Max Length = 24 Numeric only 3081470000000000
programme-identifier Required String ATRP or BAEC The 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 API key. Format: ATRP or BAEC ATRP
api_key Required String Length = 24 The partner API Key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: Length = 24

Request Headers

Name Required Data type Format Description Example
Accept Optional String application/< content-type > The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted. Format: application/< content-type > application/json
Authorization Required String JWT Token This header contains the Access Token issued by the Authorisation Server. Must have a scope of retrieve_username Format: JWT Token
Content-Type Required String application/< content-type > The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted. Format: application/< content-type > application/json
X-Forwarded-For Optional String Comma separated valid IP addresses Identifies the originating IP address of a consumer. Format: Comma separated valid IP addresses 172.128.25.24, 172.128.25.24

Request Elements

The following shows examples of request calls to the Credit Currency API:

Example 1 – ATRP programme request with MI data

{
  "description": "666 Avios collected",
  "monetaryAmount": {
    "amount": 666,
    "currency": {
      "currencyCode": "AVIOS"
    }
  },
  "externalTransactionIdentifier": "ext",
  "externalTransactionDate": "1998-03-23T00:00:00.000+00:00",
  "externalReferenceIdentifier": "B1X2Za",
  "externalReferenceDescription": "ExternalReferenceDescription",
  "externalPartnerIdentifier": "Ext",
  "externalSource": "000081000",
  "productSummary": [
    {
      "productInstanceIdentifier": "12345",
      "productTypeSummary": "FLIGHT",
      "productFeatureSummary": [
        {
          "code": "PNR",
          "index": 1,
          "value": "PNR001"
        }
      ]
    }
  ],
  "type": "COLLECTION",
  "person": {
    "name": {
      "familyName": "BROWN"
    }
  }
}

Example 2 – ATRP programme request without MI data

{
  "description": "100 Avios collected",
  "monetaryAmount": {
    "amount": 100,
    "currency": {
      "currencyCode": "AVIOS"
    }
  },
  "externalTransactionIdentifier": "ext",
  "externalTransactionDate": "2015-07-10T20:33:43.270+01:00",
  "externalReferenceIdentifier": "B1X2Za",
  "externalReferenceDescription": "ExternalReferenceDescription",
  "externalPartnerIdentifier": "Ext",
  "externalSource": "000081000",
  "type": "COLLECTION",
  "person": {
    "name": {
      "familyName": "BROWN"
    }
  }
}

Example 3 – BAEC programme request

{
  "monetaryAmount": {
    "amount": 100,
    "currency": {
      "currencyCode": "AVIOS"
    }
  },
  "externalTransactionIdentifier": "2648890056",
  "externalTransactionDate": "2015-07-10T20:33:43.270+01:00",
  "externalReferenceIdentifier": "B1X2Za",
  "externalReferenceDescription": "ExternalReferenceDescription",
  "externalPartnerIdentifier": "Ext",
  "externalSource": "000081000",
  "type": "COLLECTION",
  "person": {
    "name": {
      "firstName": "ARTHUR",
      "familyName": "BROWN"
    }
  }
}
Name Required Data Type Format Description
description Conditional String Alphanumeric with special characters. Min length: 1 The description of the transaction which is being submitted. Required for ATRP Optional for BAEC Format: Alphanumeric with special characters. Min length: 1
monetaryAmount Required Complex type [1..1] Credit transaction amount details.
monetaryAmount.
amount
Required String Numeric only. For ATRP: Max value: Set per partner, limit 999,999 For BAEC: Max length: 6 Amount to be credited to the account. Example: 10 Format: Numeric only. For ATRP: Max value: Set per partner, limit 999,999 For BAEC: Max length: 6
monetaryAmount.
currency
Required Complex type [1..1] Credit transaction currency detail.
monetaryAmount.
currency.
currencyCode
Required String Enumeration Loyalty programme currency identifier. Case sensitive. At present only Avios is supported, i.e.: currencyCode = “AVIOS”. Format: Enumeration
externalTransactionIdentifier Required String Alphanumeric with special characters: Max length: 20 & . - _ ' / , % + (and space) *For BAEC: value is numeric and checked to be less or equal to 18446744073709551615 This is the partner’s identifier for the transaction that was previously executed externally within the partner’s system. Example for ATRP programme: ext, Example for BAEC programme: 18446744073709551612 Format: Alphanumeric with special characters: Max length: 20 & . - _ ' / , % + (and space) *For BAEC: value is numeric and checked to be less or equal to 18446744073709551615
externalTransactionDate Required Date ISO-8601 Calendar date format. This is the date that the client requires to be stored against the transaction, and would normally relate to the time of the associated activity such as collection time. API doesn’t accept future dates and API time zone is UTC.For ATRP: API accepts 10 years old transaction dates, For BAEC: API accepts transaction dates only later than member’s join date for which transaction is being executed. Format: ISO-8601 Calendar date format.
externalReferenceIdentifier Optional String Alphanumeric with special characters: Max length: 10 & . - _ ' / , % + (and space) This is the booking reference associated with the collection request. Example: ERI Format: Alphanumeric with special characters: Max length: 10 & . - _ ' / , % + (and space)
externalReferenceDescription Optional String Alphanumeric with special characters: Max length: 62 & . - _ ' / , % + (and space) The description of the transaction executed at partner channel. Example: ERD Format: Alphanumeric with special characters: Max length: 62 & . - _ ' / , % + (and space)
externalPartnerIdentifier Optional String Alphanumeric with special characters: (space). Max length: 3 This is the channel from where the request has been made from. Example: EPI Format: Alphanumeric with special characters: (space). Max length: 3
externalSource Required String Alphanumeric with special characters: Max length: 10 & . - _ ' / , % + (and space) ATRP: The billing code. BAEC: Location code. Format: Alphanumeric with special characters: Max length: 10 & . - _ ' / , % + (and space)
productSummary Optional Array of Complex type [0..n] Details information about the product.
productSummary.
productInstanceIdentifier
Required String Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space) This element describes the identifier of the product which is booked as part of the transaction. Example: 12345 Format: Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space)
productSummary.
productFeatureSummary
Optional Array of Complex type [0..n] Product feature summary. This provides marketing information about the product and its features. There may be multiple instances of this element.
productSummary.
productFeatureSummary.
code
Required String Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space) This element contains the code of the selected product’s feature. Example: PNR Format: Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space)
productSummary.
productFeatureSummary.
value
Required String Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space) This element contains the value of the selected product’s feature. Example: COL222 Format: Alpha numeric with special characters: Max length: 200 & . - _ ' / , % + (and space)
productSummary.
productFeatureSummary.
index
Optional String Numeric: Max numeric value 99999 This element contains the sequence number of the selected product’s feature. Example: 1 Format: Numeric: Max numeric value 99999
productSummary.
productTypeSummary
Required String Enumeration Product type. Must be one of the following: FLIGHT HOTEL CAR HIRE OTHER Format: Enumeration
type Required String Enumeration Credit transaction type. This must be “COLLECTION”. Format: Enumeration
person Required Complex type [1..1] Representation the personal attribute of the member.
person.
name
Required Complex type [1..1] Contains the family name details of the member.
person.
name.
firstName
Conditional String For ATRP: Max length: 25. Latin symbols with quote ('), hyphen (-) and space ( ). For BAEC: Max length: 42. Latin symbols with accented characters with quote ('), hyphen (- ) and space ( ). First name of the member. Optional for ATRP Required for BAEC Format: For ATRP: Max length: 25. Latin symbols with quote ('), hyphen (-) and space ( ). For BAEC: Max length: 42. Latin symbols with accented characters with quote ('), hyphen (- ) and space ( ).
person.
name.
familyName
Required String For ATRP: Max length: 40. Latin symbols with quote ('), hyphen (-) and space ( ). For BAEC: Max length: 42. Latin symbols with accented characters with quote ('), hyphen (- ) and space ( ). Family name of the member. Format: For ATRP: Max length: 40. Latin symbols with quote ('), hyphen (-) and space ( ). For BAEC: Max length: 42. Latin symbols with accented characters with quote ('), hyphen (- ) and space ( ).

Response Elements

Example Response:

{
  "identifier": "6425162290813 ",
  "dateMade": "2016-08-16T09:13:30.737Z",
  "description": "ccd8e491-973d-46b9-9b6b-f934c37cf945",
  "monetaryAmount": {
    "amount": 1,
    "formattedAmount": "1",
    "currency": {
      "currencyCode": "AVIOS"
    }
  },
  "externalTransactionIdentifier": "ext",
  "externalTransactionDate": "2015-07-10T20:33:43.270+01:00",
  "externalReferenceIdentifier": "B1X2Za",
  "externalReferenceDescription": "ExternalReferenceDescription",
  "externalPartnerIdentifier": "Ext",
  "externalSource": "000081000",
  "type": "COLLECTION"
}
Name Presence Data type Format Description
identifier Present String Alphanumeric Max length: 16 A transaction identifier that uniquely identifies the credit transaction. Example: “19195D“ Format: Alphanumeric Max length: 16
dateMade Present Date ISO-8601 Calendar date format. This is the date and time when credit transaction request was performed. API time zone is UTC. Example: 2016-02-26T10:53:14.301Z Format: ISO-8601 Calendar date format.
description Conditional String Alphanumeric with special characters &.-_' /,%+(andspace) Max length: 50 Credit transaction description. Presence for ATRP. *Optional presence for BAEC Example: DESC Format: Alphanumeric with special characters &.-_' /,%+(andspace) Max length: 50
monetaryAmount Present Complex type [1..1] Credit transaction amount details.
monetaryAmount.
amount
Present String Numeric Max length: 6 Amount credited to the account. Example: 10 Format: Numeric Max length: 6
monetaryAmount.
formattedAmount
Present String Alphanumeric Max length: 6 The amount formatted as specified by the currency code. Example: 10 Format: Alphanumeric Max length: 6
monetaryAmount.
currency
Present Complex type [1..1] Credit transaction currency detail.
monetaryAmount.
currency.
currencyCode
Present String Enumeration Loyalty programme currency identifier. At present only Avios is supported, i.e.: currencyCode = “AVIOS”. Format: Enumeration
externalTransactionIdentifier Present String Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 20 This is the partner’s identifier for the transaction that was previously executed externally within the partner’s system against which the AVIOS collection is being sought by calling Credit Currency API. Format: Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 20
externalTransactionDate Present Date YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format. This is the date the client requires to be stored against the transaction, and would normally relate to the time of the associated activity such as collection time. Example.: 1991-12-15T20:37:21.886Z Format: YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format.
externalReferenceIdentifier Optional String Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 10 This is the booking reference associated with the collection request. Format: Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 10
externalReferenceDescription Optional String Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 62 The description of the transaction executed at partner channel against which collection is being sought by calling Credit Currency API. Format: Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 62
externalPartnerIdentifier Optional String Alphanumeric with special characters space ( ) Max length: 3 This is the channel from where the request was made. Format: Alphanumeric with special characters space ( ) Max length: 3
externalSource Present String Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 10 ATRP: The billing code as given in request BAEC: The location code as given in request Format: Alphanumeric with special characters & . - _ ' / , % + (and space) Max length: 10
type Present String Enumeration Credit transaction type. This will always be COLLECTION. Format: Enumeration

Exception Message Elements

Error Response:

{
  "code": "REQUEST_INVALID",
  "businessMessage": "Request Invalid",
  "developerLink": "https://developer.avios.com/docs",
  "childError": [
    {
      "code": "PARTNER_INVALID",
      "businessMessage": "Partner Invalid",
      "developerLink": "https://developer.avios.com/docs"
    }
  ]
}
Name Presence Data type Format Description
code Present String Alphabetic plus under-score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_).
businessMessage Present String Alphabetic A business level message describing the error which has occurred. Example: Request Invalid. Format: Alphabetic
developerMessage Conditional String Alphabetic Developer message will be present when error message requires a detailed technical description. If no specific developer message is required, developer message will be the same as business message. Format: Alphabetic
developerLink Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
childError Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where more than error may have occurred.
childError.
code
Present String Alphabetic plus under-score (_). The error code for the child error (if returned). Example: DATA_INVALID Format: Alphabetic plus under-score (_).
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Identifies the element in the request which has caused the error to occur. This element will not be visible when headers provided in request message is invalid or missing or the validation of element is done beyond the business API. Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
childError.
businessMessage
Present String Alphabetic A business level message describing the error which has occurred. Example: Programme not supported Format: Alphabetic
childError.
developerMessage
Conditional String Alphabetic Developer message will be present when error message requires a detailed technical description. If no specific developer message is required, developer message will be the same as business message. Format: Alphabetic
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

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

Http Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract or request does not follow the JSON contract *Transaction ID invalid (BAEC programme).
400 REQUEST_INVALID PROGRAMME_INVALID Programme information does not exist.
400 REQUEST_INVALID ACCOUNT_INVALID Account information does not exist. Member not in Frequent Flyer Scheme (BAEC programme) *Member is created later than credit transaction’s date is sent or future date is sent (BAEC programme).
400 REQUEST_INVALID ACCOUNT_NOT_AUTHORISED The provided account-identifier is cancelled, deceased, fraud.
400 REQUEST_INVALID DUPLICATE_TRANSACTION API returns this error when transaction made has the same amount, description and date values as previous transaction made.
400 REQUEST_INVALID PROGRAMME_NOT_SUPPORTED Partner is not associated with the programme.
400 REQUEST_INVALID INVALID_PROMOTER_CODE Invalid external source code (promoter) supplied (ATRP programme) *Invalid external source code (location code) supplied (BAEC programme).
400 MEMBERSHIP_NUMBER_NAME_MISMATCH *The name provided in request does not match against the stored member details (BAEC programme).
400 MEMBERSHIP_NUMBER_SURNAME_MISMATCH The surname provided in request does not match against the stored member details.

Debit Currency

v1

The Debit Currency API is available specifically to redemption partners to request a debit transaction to a member’s loyalty account from a partner’s application. This is typically part of a purchase where Avios loyalty points are redeemed in exchange for a product. This API would normally be used for a purchase that is part-paid in Avios and part-paid in cash, requiring the partner to manage both transactions. It is AGL’s business requirement to have as detailed product information as part of the Debit Currency API call. Some of the information, like currency code and PNR, might be required to appear in multiple data elements.

In order to specify the number of Avios to be redeemed as part of this transaction request, the partner may have either called the Avios Retrieve Product Pricing API or calculated the value themselves.

The redemption rate will have been agreed between Avios and the partner in advance. An OAuth access token will also need to be obtained by the partner based upon the member authorising the debit request against their account.

Business Context

Here’s the process flow:

Debit Currency API Flow

Technical Context

In order to call the Debit Currency API the partner must have previously been issued with a valid Access Token in exchange for the member providing authorisation with their Avios credentials. Although specifying an amount which exceeds the member’s current balance is not permitted (an appropriate error will be returned), the customer journey will be improved if the partner first checks the balance through a call to the Retrieve Account API.

The following steps are performed by this API:

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: The member’s account is debited by the specified number of Avios loyalty points.

Error outcome: An error is returned and the member’s account balance remains unchanged.

Service Details

URI Parameters

Production Endpoint:

'POST https://api.avios.com/{version}/programmes/{programme-identifier}/accounts/{account-identifier}/debit-transaction-requests?api_key={api_key}'

Example

https://api.avios.com/v1/programmes/ATRP/accounts/3081470000000000/debit-transaction-requests?api_key=abcdef
Name Required Type Format Description Example
version Required String Alpha numeric v[0-9] The version number of the API being called. The correct version is confirmed during the partner on-boarding process. Format: Alpha numeric v[0-9] v1
programme-identifier Required String Currently restricted to ATRP or BAEC The identifier for the loyalty programme to which the member belongs. This will have been provided during the partner on-boarding process. Format: Currently restricted to ATRP or BAEC ATRP
account-identifier Required String Min length = 1 Max Length = 24 Numeric only The 16-digit membership number starting with 308147. Format: Min length = 1 Max Length = 24 Numeric only 3081470000000000
api_key Required String Alpha-numeric Max Length = 24 Min Length = 24 The API key provided during the partner on- boarding process. Format: Alpha-numeric Max Length = 24 Min Length = 24 abcdefabcdefabcdefa bcdef

Request Headers

Name Required Type Format Description Example
Authorization Required String JWT token This header contains the Access Token issued by the Authorisation Server. This API can only be accessed when a member has provided authorisation to the partner by providing their membership credentials. Must have a scope of retrieve_username Format: JWT token
Accept Optional String application/json The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/json is accepted currently. Format: application/json application/json
Content-Type Required String application/json The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/json is accepted currently. Format: application/json application/json
X-Forwarded-For Business Required String IP address Identifies the originating IP address of a consumer. This is required by AGL to mitigate against a risk of fraud and a misuse of customer’s credentials. Format: IP address 172.128.25.24
X-Agent-Id Optional / Business Required String Alphanumeric An agent Id represents the agent name/user name/login id and should be provided for offline channels like call centres. API won’t return error if not provided but partners should populate this field as much as possible in order to track potential irregular agent activities. This header is Optional for online channels and Business Required for offline channels. Format: Alphanumeric Masanobu.Fukuoka

Request Elements

The following shows examples of request calls to the Debit Currency API:

Request Example 1 – with product summary MI data

{
  "debitTransaction": {
    "externalTransactionDate": "2019-05-10T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 100,
      "currency": {
        "currencyCode": "AVIOS"
      }
    },
    "exchangeRate": {
      "code": "EUR"
    },
    "description": "Info to show in customer’s Avios Transaction History",
    "externalTransactionIdentifier": "FLB0215",
    "externalReferenceIdentifier": "PNR001",
    "externalReferenceDescription": "Discounted redemption of 100 Avios",
    "externalPartnerIdentifier": "FLB",
    "productSummary": [{
      "productInstanceIdentifier": "PNR001",
      "productFeatureSummary": [{
          "code": "ADULT_COUNT",
          "index": 0,
          "value": "1"
        },
        {
          "code": "YOUNG_ADULT_COUNT",
          "index": 0,
          "value": "0"
        },

        {
          "code": "CHILD_COUNT",
          "index": 0,
          "value": "0"
        },
        {
          "code": "INFANT_COUNT",
          "index": 0,
          "value": "0"
        },
        {
          "code": "SUPPLIER_ID",
          "index": 0,
          "value": "BA"
        },
        {
          "code": "BOOKING_DATE",
          "index": 0,
          "value": "07-Sep-15"
        },
        {
          "code": "PNR",
          "index": 0,
          "value": "PNR001"
        },
        {
          "code": "CASH_DISCOUNT",
          "index": 0,
          "value": "53"
        },
        {
          "code": "CASH_DISCOUNT_CURRENCY_CODE",
          "index": 0,
          "value": "EUR"
        },
        {
          "code": "PURCHASE_CHANNEL",
          "index": 0,
          "value": "Online"
        },
        {
          "code": "FLIGHT_SEGMENT_ID",
          "index": 0,
          "value": "1"
        },
        {
          "code": "LEG_DEPARTURE_LOCATION",
          "index": 0,
          "value": "LGW"
        },
        {
          "code": "LEG_ARRIVAL_LOCATION",
          "index": 0,
          "value": "AGP"
        },
        {
          "code": "LEG_BOOKING_CLASS_CODE",
          "index": 0,
          "value": "H"
        },
        {
          "code": "LEG_CABIN_CLASS_CODE",
          "index": 0,
          "value": "Y"
        },
        {
          "code": "MARKETING_CARRIER_IATA_CODE",
          "index": 0,
          "value": "BA"
        },
        {
          "code": "OPERATING_CARRIER_IATA_CODE",
          "index": 0,
          "value": "BA"
        },
        {
          "code": "MARKETING_CARRIER_FLIGHT_NO",
          "index": 0,
          "value": "2716"
        },
        {
          "code": "OPERATING_CARRIER_FLIGHT_NO",
          "index": 0,
          "value": "2716"
        },
        {
          "code": "PRODUCT_CLASS",
          "index": 0,
          "value": "PLUS"
        },
        {
          "code": "FLIGHT_SEGMENT_ID",
          "index": 1,
          "value": "2"
        },
        {
          "code": "LEG_DEPARTURE_LOCATION",
          "index": 1,
          "value": "AGP"
        },
        {
          "code": "LEG_ARRIVAL_LOCATION",
          "index": 1,
          "value": "LGW"
        },
        {
          "code": "LEG_BOOKING_CLASS_CODE",
          "index": 1,
          "value": "O"
        },
        {
          "code": "LEG_CABIN_CLASS_CODE",
          "index": 1,
          "value": "Y"
        },
        {
          "code": "MARKETING_CARRIER_IATA_CODE",
          "index": 1,
          "value": "BA"
        },
        {
          "code": "OPERATING_CARRIER_IATA_CODE",
          "index": 1,
          "value": "BA"
        },
        {
          "code": "MARKETING_CARRIER_FLIGHT_NO",
          "index": 1,
          "value": "2717"
        },
        {
          "code": "OPERATING_CARRIER_FLIGHT_NO",
          "index": 1,
          "value": "2711"
        },
        {
          "code": "PRODUCT_CLASS",
          "index": 1,
          "value": "PLUS"
        }
      ],
      "productTypeSummary": "FLIGHT"
    }],
    "type": "REDEMPTION"
  }
}

Request Example 2 – without MI data

{
  "debitTransaction": {
    "externalTransactionDate": "1991-12-15T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 100,
      "currency": {
        "currencyCode": "AVIOS"
      }
    },
    "exchangeRate": {
      "code": "1"
    },
    "description": "Redemption of 100 Avios",
    "externalTransactionIdentifier": "FLB0215",
    "externalReferenceIdentifier": "FLB",
    "externalReferenceDescription": "Discounted redemption of 100 Avios",
    "externalPartnerIdentifier": "FLB",
    "type": "REDEMPTION"
  }
}

Request Example 3 for Flight Ancillaries

{
  "debitTransaction": {
    "externalTransactionDate": "2016-12-15T20:37:21.886Z",
    "monetaryAmount": {
      "amount": 350,
      "currency": {
        "currencyCode": "AVIOS"
      }
    },
    "exchangeRate": {
      "code": "1"
    },
    "description": "Redemption of 350 Avios",
    "externalTransactionIdentifier": "VI0215",
    "externalReferenceIdentifier": "VI",
    "externalReferenceDescription": "Discounted redemption of 350 Avios",
    "externalPartnerIdentifier": "VI",
    "productSummary": [
      {
        "productInstanceIdentifier": "Prod1",
        "productTypeSummary": "BAGGAGE",
        "productFeatureSummary": [
          {
            "code": "COUNT",
            "value": "1"
          },
          {
            "code": "SUPPLIER_ID",
            "value": "VI"
          },
          {
            "code": "BOOKING_DATE",
            "value": "07-Jan-17"
          },
          {
            "code": "PNR",
            "value": "YXFQ0H"
          },
          {
            "code": "PNR_CREATE_DATE",
            "value": "07-Jan-17"
          },
          {
            "code": "CASH_DISCOUNT",
            "value": 15
          }
        ]
      }
    ],
    "type": "REDEMPTION"
  }
}
Name Required Type Format Description
debitTransaction Required Complex type [1..1] This element represents debit transaction with associated attributes which are to be recorded.
debitTransaction.
externalTransactionDate
Required Date YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format. This is the date of the transaction at partner channel for which the AVIOS redemption is being sought by calling Debit Currency API. Example:1991-12-15T20:37:21.886Z Format: YYYY-MM- DDThh:mm:ss.sTZD ISO-8601 Calendar date format.
debitTransaction.
monetaryAmount
Required Complex type [1..1] This element contains the amount related attribute associated with the transaction which is requested to Debit Currency API.
debitTransaction.
monetaryAmount.
amount
Required String Numeric Max length: 10 Min value: 1 Max value: 9999999999 Amount (number of Avios) to be debited from the account. Example:100 Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.
monetaryAmount.
currency
Required Complex type [1..1] Represents the currency related information.
debitTransaction.
monetaryAmount.
currency.
currencyCode
Required String Enumeration Represents the currency in which the transaction amount will be recorded. This value must be “AVIOS”. Format: Enumeration
debitTransaction.
exchangeRate
Optional Complex type [1..1] Redemption rate.
debitTransaction.
exchangeRate.
code
Required String Alphanumeric Min length: 1 Use 3-letter currency codes as defined in ISO 4217 (GBP, EUR, USD, CHF etc.). Redemption rate code. The cash currency used for this transaction with Avios. If no cash currency used, use default value 1. Format: Alphanumeric Min length: 1 Use 3-letter currency codes as defined in ISO 4217 (GBP, EUR, USD, CHF etc.).
debitTransaction.
description
Required String Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 64 The description of the transaction which is being submitted. This description will appear in customer’s Transaction History. Format: Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalTransactionIdentifier
Required String Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 32 This is the partner’s identifier for the transaction that was previously executed externally within the partner’s system against which the AVIOS redemption is being sought by calling Debit Currency API. Element can accept accented characters but won’t convert them. Example:00000012345. In case of partner system not generating a unique reference number, a dummy value must be agreed with AGL. Format: Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalReferenceIdentifier
Business Required String Alphanumeric with special ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 32 A unique reference used by partner’s system, this could be partner generated booking reference number or externally generated like a PNR. Element can accept accented characters but won’t convert them. Examples: ISS12345678, 4ZS4JI. In case of partner system not generating a unique reference number, or it is not yet known at the time of the debit_currency API call, a dummy value must be agreed with AGL. Format: Alphanumeric with special ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalReferenceDescription
Required String Alphanumericwith special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 64 The description of the transaction at partner channel against which redemption is being sought by calling Debit Currency API. Example: ERD Format: Alphanumericwith special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalPartnerIdentifier
Required String Alphanumeric with special characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 3 The redemption channel used for submitting Debit Currency API request. Example: FLB Format: Alphanumeric with special characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
productSummary
Business Required Array of Complex type [0..n] Contains the details of the product which has been selected by a customer through partner channel.
debitTransaction.
productSummary.
productInstanceIdentifier
Required String Alphanumeric with special characters: & . - _’, %+(and space) Min length: 1 Max length: 200 This element describes the identifier of the product which is booked as part of the transaction at partner site. Example: PNR001 Format: Alphanumeric with special characters: & . - _’, %+(and space) Min length: 1 Max length: 200
debitTransaction.
productSummary.
productFeatureSummary
Business Required Array of Complex type [0..n] Product feature summary. This provides marketing information about the product and its features. There may be multiple instances of this element.
debitTransaction.
productSummary.
productFeatureSummary.
code
Required String Alphanumeric with special characters: & . - _’/, %+(and space) Min length: 1 Max length: 200 This element contains the code of the selected product’s feature. Please use one of the following: ADULT_COUNT YOUNG_ADULT_COUNT CHILD_COUNT INFANT_COUNT SUPPLIER_ID BOOKING_DATE PNR PNR_CREATE_DATE FLIGHT_SEGMENT_ID LEG_DEPARTURE_DATE LEG_DEPARTURE_LOCATION LEG_ARRIVAL_LOCATION LEG_BOOKING_CLASS_CODE LEG_CABIN_CLASS_CODE MARKETING_CARRIER_IATA_CODE OPERATING_CARRIER_IATA_CODE MARKETING_CARRIER_FLIGHT_NO OPERATING_CARRIER_FLIGHT_NO HOTEL_NAME HOTEL_CHAIN HOTEL_CITY HOTEL_COUNTRY HOTEL_STAY_DURATION HOTEL_CHECK_IN_DATE HOTEL_CHECK_OUT_DATE HOTEL_OCCUPANT_TYPE HOTEL_ROOM_TYPE HOTEL_BOARD_BASIS HOTEL_SPECIAL_ORDER_ACCESSORY HOTEL_CHANNEL HOTEL_STAR_RATING HOTEL_NUMBER_OF_ROOMS CAR_HIRE_CITY CAR_HIRE_COUNTRY CAR_HIRE_DROP_OFF_TIME CAR_HIRE_PICK_UP_TIME CAR_HIRE_VEHICLE_TYPE CAR_HIRE_MILEAGE_ALLOCATED PICK_UP_LOCATION DROP_OFF_LOCATION PICK_UP_DATE DROP_OFF_DATE CHANNEL PRODUCT_CLASS TICKET_PRICE PURCHASE_CHANNEL CASH_DISCOUNT_CURRENCY_CODE BILLING_CURRENCY_CODE CASH_DISCOUNT If a suitable code for partner’s product details is not found, please contact to get them added. This is required to enable smooth ongoing reporting. Example: PNR Format: Alphanumeric with special characters: & . - _’/, %+(and space) Min length: 1 Max length: 200
debitTransaction.
productSummary.
productFeatureSummary.
value
Required String Alphanumeric with special characters: & . - _’/, %+(and space) Min length: 1 Max length: 200 This element contains the value of the selected product’s feature. Example: PNR001 Format: Alphanumeric with special characters: & . - _’/, %+(and space) Min length: 1 Max length: 200
debitTransaction.
productSummary.
productFeatureSummary.
index
Optional / Business Required String Numeric Max numeric value 99999 This element contains the sequence number of the selected product’s feature. Example: 0. This is Optional for single product products like Lounge_pass, but mandatory for Flights and any other products where there is multiple of same type of products. For example: flight, all codes and values related to first segment must have index 0, 1 for next segment and so on Format: Numeric Max numeric value 99999
debitTransaction.
productSummary.
productTypeSummary
Required String Enumeration Product type. Must be one of the following: FLIGHT HOTEL CAR_HIRE INSURANCE SEAT PET BAGGAGE SPECIAL_BAGGAGE LOUNGE_PASS PARKING MEALS WIFI UPGRADE BUY_ON_BOARD UNACCOMPANIED_MINOR FEES SMS BASKET PRIORITY_BOARDING OTHER Format: Enumeration
debitTransaction.
type
Required String Enumeration Debit transaction type. This must be “REDEMPTION”. Format: Enumeration

Response Elements

The following example shows a response from the Debit Currency API:

{
  "debitTransaction": {
    "identifier": "19596A",
    "dateMade": "2017-01-24T12:28:45.197Z ",
    "monetaryAmount": {
      "amount": 100,
      "formattedAmount": "100",
      "currency": {
        "currencyCode": "AVIOS"
      }
    },
    "description": " Redemption of 100 Avios ",
    "externalTransactionIdentifier": " 62219E",
    "externalReferenceDescription": " Discounted redemption of 100 Avios ",
    "externalPartnerIdentifier": "FLB",
    "type": "REDEMPTION"
  }
}

The elements that make up the response message are detailed in the following table:

Name Presence Type Format Description
debitTransaction Conditional Complex type [1..1] This element represents debit transaction with associated attributes. This will be present in case of success response only.
debitTransaction.
identifier
Present String Alphanumeric Max length: 32 A transaction identifier that uniquely identifies the debit transaction which has been recorded in ATRP system. The member account gets debited by the amount in request. Format: Alphanumeric Max length: 32
debitTransaction.
dateMade
Present ISO-8601 String YYYY-MM-DDThh:mm:ss.sTZD This is the date that has been stored against the transaction. This represents the date when the transaction occurred in ATRP or BAEC system. Example: 2016-02-26T10:53:14.301Z Format: YYYY-MM-DDThh:mm:ss.sTZD
debitTransaction.
monetaryAmount
Present Complex type [1..1] This element contains the amount related attribute associated with the transaction which is recorded by Debit Currency API.
debitTransaction.
monetaryAmount.
amount
Present String Numeric Max length: 10 Min value: 1 Max value: 9999999999 Amount (number of Avios) debited from the account. Example: 100 Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.
monetaryAmount.
formattedAmount
Present String Numeric Max length: 10 Min value: 1 Max value: 9999999999 String representation of the amount (number of Avios) debited from the account. Example: 100 Format: Numeric Max length: 10 Min value: 1 Max value: 9999999999
debitTransaction.
monetaryAmount.
currency
Present Complex type [1..1] Represents the currency related information.
debitTransaction.
monetaryAmount.
currency.
currencyCode
Present String Enumeration Represents the currency in which the transaction amount has been recorded. This will always be “AVIOS”. Format: Enumeration
debitTransaction.
description
Present String Alphanumeric with special characters ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min Length: 1 Max length: 51 Describes the description associated with the debit transaction as provided in request. In case if accented characters were passed in request for this field it will return converted characters. Format: Alphanumeric with special characters ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalTransactionIdentifier
Present String Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) The transaction identifier of the partner channel against which debit currency API was called. In case if accented characters were passed in request for this field API won’t convert them and will return them as it is. Format: Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space=""/>
debitTransaction.
externalReferenceIdentifier
Conditional String Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min Length: 1 Max length: 32 This reference identifier similar which was passed in the request. In case if accented characters were passed in request for this field API won’t convert them and will return them as it is. Format: Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalReferenceDescription
Present String Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min Length: 1 Max length: 32 Description of the transaction at partner channel for which debit currency api was invoked. This value will be same as provided in request. In case if accented characters were passed in request for this field it will return converted characters. Format: Alphanumeric with special and accented characters: ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
externalPartnerIdentifier
Present String Alphanumeric with special and ~!@#\$%^&*()_ - +=}]{[;:'><.,?/ (and space) Min length: 1 Max length: 3 Partner identifier will be the same that was passed in request. Format: Alphanumeric with special and ~!@#\$%^&*()_ - +=}]{[;:'><. space="" min="" length:="" max=""/>
debitTransaction.
type
Present String Enumeration. Debit transaction type. This will always be “REDEMPTION” for debit transactions. Format: Enumeration.

Exception Message Elements

Example of an Error Response

The following shows two examples of error responses generated by the Debit Currency API:

Example 1:

{
  "error": {
    "code": "REQUEST_UNAUTHORIZED",
    "businessMessage": "Request Unauthorized",
    "developerLink": "https://developer.avios.com/docs",
    "childError": [
      {
        "code": "DATA_INVALID",
        "businessMessage": "Data Invalid",
        "developerLink": "https://developer.avios.com/docs"
      }
    ]
  }
}

Example 2:

{
  "error": {
    "code": "BALANCE_INSUFFICIENT",
    "businessMessage": "Balance Insufficient",
    "developerLink": "https://developer.avios.com/docs"
  }
}

The exception message responses may be formatted in either upper or lower case.

Name Presence Type Format Description
error Conditional Complex type [0..1] Will only be present if an error has been detected and reported by the API.
error.
code
Present String Alphabetic plus under-score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_).
error.
businessMessage
Conditional String Alphabetic A business level message describing the error which has occurred. Example: Request Invalid Format: Alphabetic
error.
developerMessage
Conditional String Alphabetic Developer 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
Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
error.
childError
Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
error.
childError.
code
Present String Alphabetic plus under-score (_). The error code for the child error (if returned). Example: DATA_INVALID Format: Alphabetic plus under-score (_).
error.
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Identifies the element in the request which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing Paths are not sustained originating from backend system. Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
error.
childError.
businessMessage
Conditional String Alphabetic A business level message describing the error which has occurred. Example: Data Invalid Format: Alphabetic
error.
childError.
developerMessage
Conditional String Alphabetic Developer 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.
childError.
developerLink
Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

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

Http Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract.
400 REQUEST_INVALID MANDATORY_DATA_MISSING No content in the request body or a mandatory element is missing from the request or JSON provided in request doesn’t follow its contract.
400 INVALID_MEMBER If an invalid membership number is supplied from Offline channels.
400 BALANCE_INSUFFICIENT If there is not enough balance in the account to fulfil the debit request.

Retrieve Product Pricing

v2

The Retrieve Product Pricing API is available specifically to redemption partners. It calculates discount price points for requested products. The products can be flights, flight ancillaries, car hire, hotels and insurance. Price points can also be calculated for a package of products containing a mix of any of the products previously listed.

Discount pricing points contain two values:

Product prices can be retrieved without specifying an individual member or they can be tailored to the individual member.

Business Context

Here’s the process flow:

Product Pricing API Flow

Technical Context

The Retrieve Product Prices API does not depend upon member information being supplied. It can be called at any stage either before or after a member logs in and can be invoked before a member registers.

The Retrieve Product Prices API performs the following steps:

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: One or more product pricing points are returned in the API response message.

Error outcome: An error is returned.

Service Details

URI Parameters

Production Endpoint:

POST https://api.avios.com/{version}/product-prices?api_key={api_key}

Example

https://api.avios.com/v2/product-prices?api_key=abcdefabcdefabcdefabcdef
Name Required Data type Format Description Example
Version Required String Alphanumeric v[0-9] The version number of the API being called. The correct version is confirmed during the partner on-boarding process. Format: Alphanumeric v[0-9] v2
api_key Required String As supplied by Avios during partner configuration, alpha-numeric The partner API key provided during initial partner configuration within Loyalty Programme systems as part of the standard partner on-boarding process. Format: As supplied by Avios during partner configuration, alpha-numeric abcdefabcdefabcdefabcdef

Request Headers

Name Required Data type Format Description Example
accept Optional String application/< content-type > The Accept request- header field is used to specify certain media types which are acceptable for the response. Restricted to application/JSON. Format: application/< content-type > application/JSON
content-type Required String application/< content-type > The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload.Restricted to application/JSON. Format: application/< content-type > application/JSON
X-Forwarded-For Optional String Comma separated Valid IP addresses The IP address of the end customer. API will validate just first provided IP address. Format: Comma separated Valid IP addresses 45.143.76.250, 45.143.76.251
Authorization Conditional String JWT Token An access token authorising the partner to access member specific pricing via this API. This is base 64bit code. If membership number is specified in request message, access token has to be provided for that member. If membership number is not provided in request message API doesn’t validate an access token. If Authorisation header and membership number are supplied in the request, then discount price points calculations take member's balance and the specific pricing rules for that partner into consideration. Format: JWT Token
X-Agent-Id Optional String Alphanumeric An agent Id represents the agent name/user name/login id for offline channels like call centres. Format: Alphanumeric Masanobu.Fukuoka

Request Elements

The following is an example of a Flight request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "membership": { "membershipNumber": "0123456789", "tier": "GOLD" },
    "product": [
      {
        "flight": {
          "passengerSummary": {
            "adultCount": "1",
            "youngAdultCount": "1",
            "childCount": "1",
            "infantCount": "1",
            "seniorCount": "1"
          },
          "segment": [
            {
              "outBound": "true",
              "leg": [
                {
                  "fareFamilyCode": "FF1",
                  "schedule": {
                    "departureDateRange": {
                      "startDateTime": "2017-12-31T12:00:00"
                    },
                    "departureLocation": {
                      "id": "LHR",
                      "type": "AIRPORT"
                    },
                    "arrivalLocation": {
                      "id": "BCN",
                      "type": "AIRPORT"
                    }
                  },
                  "marketingCarrier": {
                    "flightNumber": "0309",
                    "iataCode": { "code": "EI" }
                  },
                  "operatingCarrier": {
                    "flightNumber": "0309",
                    "iataCode": { "code": "EI" }
                  },
                  "bookingClass": { "code": "J" },
                  "cabinClass": { "code": "ECONOMY" }
                }
              ]
            }
          ],
          "price": {
            "monetaryAmount": {
              "amount": "1000.00",
              "currency": { "code": "GBP" }
            }
          }
        }
      }
    ]
  }
}

A Flight ancilliary request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "product": {
      "flightAncillary": {
        "flightAncillaryType": "MEALS",
        "price": {
          "monetaryAmount": {
            "amount": "50.00",
            "currency": {
              "code": "GBP"
            }
          }
        }
      }
    }
  }
}

A Car Hire request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "product": {
      "carHire": {
        "price": {
          "monetaryAmount": {
            "amount": "125.00",
            "currency": {
              "code": "GBP"
            }
          }
        }
      }
    }
  }
}

An Hotel request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "product": {
      "hotel": {
        "price": {
          "monetaryAmount": {
            "amount": "355.00",
            "currency": {
              "code": "GBP"
            }
          }
        }
      }
    }
  }
}

An Insurance request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "product": {
      "insurance": {
        "price": {
          "monetaryAmount": {
            "amount": "199.00",
            "currency": {
              "code": "GBP"
            }
          }
        }
      }
    }
  }
}

A Package product request to the Product Pricing API:

{
  "priceSearchCriteria": {
    "priceType": "DYNAMIC_DISCOUNT",
    "priceSource": "CACHED",
    "membership": { "membershipNumber": "0123456789", "tier": "BLUE" },
    "product": {
      "packagedProduct": {
        "flight": {
          "passengerSummary": {
            "adultCount": "1",
            "youngAdultCount": "1",
            "childCount": "1",
            "infantCount": "1",
            "seniorCount": "1"
          },
          "segment": [
            {
              "outBound": "true",
              "leg": [
                {
                  "fareFamilyCode": "FF1",
                  "schedule": {
                    "departureDateRange": {
                      "startDateTime": "2017-12-31T12:00:00"
                    },
                    "departureLocation": {
                      "id": "LHR",
                      "type": "AIRPORT"
                    },
                    "arrivalLocation": {
                      "id": "BCN",
                      "type": "AIRPORT"
                    }
                  },
                  "marketingCarrier": {
                    "flightNumber": "0309",
                    "iataCode": {
                      "code": "EI"
                    }
                  },
                  "operatingCarrier": {
                    "flightNumber": "0309",
                    "iataCode": { "code": "EI" }
                  },
                  "bookingClass": {
                    "code": "J"
                  },
                  "cabinClass": { "code": "ECONOMY" }
                }
              ]
            }
          ],
          "price": {
            "monetaryAmount": {
              "amount": "550.00",
              "currency": {
                "code": "GBP"
              }
            }
          }
        },
        "flightAncillary": {
          "flightAncillaryType": "MEALS",
          "price": {
            "monetaryAmount": {
              "amount": "50.00",
              "currency": {
                "code": "GBP"
              }
            }
          }
        }
      }
    }
  }
}
Name Required Data type Format Description
priceSearchCriteria Required Complex type [1..1] This product price retrieval complex type holds all information needed for successful call for product prices.
priceSearchCriteria.
priceType
Required String Enumeration Type of price. Must be STATIC_DISCOUNT for static discount options and DYNAMIC_DISCOUNT for dynamic discount options. Format: Enumeration
priceSearchCriteria.
priceSource
Required String Enumeration Source of price. Case sensitive and must be set to CACHED. Format: Enumeration
priceSearchCriteria.
membership
Optional Complex type [0..1] Complex type which contains details about a member.
priceSearchCriteria.
membership.
membershipNumber
Optional String Numeric. Max length: 24 only Membership Number Format: Numeric. Max length: 24 only
priceSearchCriteria.
membership.
tier
Optional String Alphabetic. Max length: 20 only Member’s tier Format: Alphabetic. Max length: 20 only
priceSearchCriteria.
product
Required Complex type [1..n] Product is the generalised element and at least one type of product (Flight, Flight Ancillary, Car Hire, Hotel, Insurance and Packaged Product) MUST be supplied in the request.
priceSearchCriteria.
product.
flight
Conditional Complex type [0..1] This element represents the flight product. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
directFlght
Optional String true,false Specifies if the flight is direct. Format: true,false
priceSearchCriteria.
product.
returnJourney
Optional Boolean true,false Specifies if flight has return journey. If not provided in request message default value false is assigned. Format: true,false
priceSearchCriteria.
product.
flight.
passengerSummary
Optional Complex type [0..1] This complex type contains information about passengers.
priceSearchCriteria.
product.
flight.
passengerSummary.
adultCount
Optional Number Numeric only. Max value: 2147483647 Number of adult passengers If this element is not provided 0 as default value is assigned. Format: Numeric only. Max value: 2147483647
priceSearchCriteria.
product.
flight.
passengerSummary.
youngAdultCount
Optional Number Numeric only. Max value: 2147483647 Number of young adult passengers If this element is not provided 0 as default value is assigned. Format: Numeric only. Max value: 2147483647
priceSearchCriteria.
product.
flight.
passengerSummary.
childCount
Optional Number Numeric only. Max value: 2147483647 Number of child passengers. If this element is not provided 0 as default value is assigned. Format: Numeric only. Max value: 2147483647
priceSearchCriteria.
product.
flight.
passengerSummary.
infantCount
Optional Number Numeric only. Max value: 2147483647 Number of infant passengers. If this element is not provided 0 as default value is assigned. Format: Numeric only. Max value: 2147483647
priceSearchCriteria.
product.
flight.
passengerSummary.
seniorCount
Optional Number Numeric only. Max value: 2147483647 Number of senior passengers. If this element is not provided 0 as default value is assigned. Format: Numeric only. Max value: 2147483647
priceSearchCriteria.
product.
flight.
segment
Required Array of Complex type [1..n] Describes the flight schedule and the related operational details in Segment level.
priceSearchCriteria.
product.
flight.
segment.
outbound
Optional Boolean true,false true represents the outbound flight and false represents the inbound flight. If this element is not provided then default false value is assigned. Format: true,false
priceSearchCriteria.
product.
flight.
segment.
leg
Required Array Complex type [1..n] One point-to-point journey in a flight segment. This element describes the route of a leg within the segmentof a flight.
priceSearchCriteria.
product.
flight.
segment.
leg.
fareFamilyCode
Optional String Alphanumeric. Max length: 5 Specifies fare family code. Only uppercase characters are accepted. Example: FF1, FF2, FF3, FF4, FF5, FF6, FF7, FF8, FF9, FF10 Format: Alphanumeric. Max length: 5
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule
Required Complex type [1..1] The flight schedule identifies the departure date, departure location and arrival location.
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
departureDateRange
Optional Complex type [1..1] Specifies departure date. If not supplied in request message API returns SYSTEM_UNAVAILABLE error.
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
departureDateRange.
startDateTime
Optional DateTime ISO-8601 Calendar date format. YYYY-MM-DDThh:mm:ss.sTZD Start date and time of outbound journey. This element doesn’t accept past dates. Example: 2017-12- 12T13:39:16.213+01:00 Format: ISO-8601 Calendar date format. YYYY-MM-DDThh:mm:ss.sTZD
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
departureLocation
Required Complex type [1..1] Outbound location of a particular leg for this route.
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
departureLocation.
id
Required String Alphabetic. Max length: 3 3 letter IATA Airport code that identifies the departure location. API just validate max length of the element but not the value it self. Accepts only uppercase characters. Example: LHR, LGW, LCY Format: Alphabetic. Max length: 3
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
departureLocation.
type
Required String Enumeration Type of departure location. Case sensitive and must be AIRPORT. Format: Enumeration
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
arrivalLocation
Required Complex type [1..1] Inbound location of a particular leg for this route.
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
arrivalLocation.
id
Required String Alphabetic. Max length: 3 3 letter IATA Airport code that identifies the arrival location. API just validate max length of the element but not the value it self. Accepts only uppercase characters. Example: JFK, DUB, SYD Format: Alphabetic. Max length: 3
priceSearchCriteria.
product.
flight.
segment.
leg.
schedule.
arrivalLocation.
type
Required String Enumeration Type of arrival location. Case sensitive and must be AIRPORT. Format: Enumeration
priceSearchCriteria.
product.
flight.
segment.
leg.
marketingCarrier
Required Complex type [1..1] The carrier that sells with its own code as part of a code-share agreement on a flight actually operated by another carrier .
priceSearchCriteria.
product.
flight.
segment.
leg.
marketingCarrier.
flightNumber
Required String Numeric only. Max length: 4 Flight Number. Example: 0016 Format: Numeric only. Max length: 4
priceSearchCriteria.
product.
flight.
segment.
leg.
marketingCarrier.
iatacode
Required Complex type [1..1] Flight’s IATA code.
priceSearchCriteria.
product.
flight.
segment.
leg.
marketingCarrier.
iatacode.
code
Required String Alphabetic. Max length: 2 2 letter IATA carrier code. API just validate max length of the element but not the value it self. Accepts only uppercase characters. Example: EI, BA, VY Format: Alphabetic. Max length: 2
priceSearchCriteria.
product.
flight.
segment.
leg.
operatingCarrier
Required Complex type [1..1] Operating carrier of the flight. The airline actually providing carriage or other services.
priceSearchCriteria.
product.
flight.
segment.
leg.
operatingCarrier.
flightNumber
Required String Numeric only. Max length: 4 Flight Number. Example: 0017 Format: Numeric only. Max length: 4
priceSearchCriteria.
product.
flight.
segment.
leg.
operatingCarrier.
iatacode
Required Complex type [1..1] Flight’s IATA code.
priceSearchCriteria.
product.
flight.
segment.
leg.
operatingCarrier.
iatacode.
code
Required String Alphabetic. Max length: 2 2 letter IATA carrier code. API just validate max length of the element but not the value it self. Accepts only uppercase characters. Example: EI, BA, VY Format: Alphabetic. Max length: 2
priceSearchCriteria.
product.
flight.
segment.
leg.
bookingClass
Optional Complex type [0..1] Contains details about booking class.
priceSearchCriteria.
product.
flight.
segment.
leg.
bookingClass.
code
Optional String Alphabetic. Max length: 1 Booking class code. Only uppercase characters are accepted. Example: Y, K Format: Alphabetic. Max length: 1
priceSearchCriteria.
product.
flight.
segment.
leg.
cabinClass
Optional Complex type [0..1]
priceSearchCriteria.
product.
flight.
segment.
leg.
cabinClass.
code
Optional String Alphabetic. Max length: 20 Cabin class code.API accepts only uppercase characters. Example: ECONOMY, FIRST, BUSINESS. Format: Alphabetic. Max length: 20
priceSearchCriteria.
product.
flight.
price
Required Complex type [1..1] Flight price
priceSearchCriteria.
product.
flight.
price.
monetaryAmount
Required Complex type [1..1] Represents the amount & currency code
priceSearchCriteria.
product.
flight.
price.
monetaryAmount.
amount
Required Number Numeric with special character . (point). Max length: 9 Flight Price. Maximum of 6 digits before the decimal point and 2 after. Example: 1200.00 Format: Numeric with special character . (point). Max length: 9
priceSearchCriteria.
product.
flight.
price.
monetaryAmount.
currency
Required Complex type [1..1] The units in which the price is supplied.
priceSearchCriteria.
product.
flight.
price
Required String Alphabetic. Min length: 3 Max length: 5 3 letter ISO currency code in which the price is denominated. API accepts only uppercase characters. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD. Format: Alphabetic. Min length: 3 Max length: 5
priceSearchCriteria.
product.
flightAncillary
Conditional Complex type [0..1] This element represents the flight ancillary product. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
flightAncillary.
flightAncillaryType
Required String Enumeration MUST be at least one of below values. Only uppercase characters are accepted. SEAT PET BAGGAGE SPECIAL_BAGGAGE LOUNGE_PASS PARKING MEALS WIFI UPGRADE BUY_ON_BOARD UNACCOMPANIED_MINOR FEES Format: Enumeration
priceSearchCriteria.
product.
flightAncillary.
price
Required Complex type [0..1] Flight AncillaryPrice details
priceSearchCriteria.
product.
flightAncillary.
price.
monetaryAmount
Required Complex type [1..1] Represents the amount & currency code
priceSearchCriteria.
product.
flightAncillary.
price.
monetaryAmount.
amount
Required Number Numeric with special character . (point) Max length: 9 FlightAncillaryPrice. Maximum of 6 digits before the decimal point and 2 after. Example: 70.50 Format: Numeric with special character . (point) Max length: 9
priceSearchCriteria.
product.
flightAncillary.
price.
monetaryAmount.
currency
Required Complex type [1..1] The units in which the price is supplied.
priceSearchCriteria.
product.
flightAncillary.
price.
monetaryAmount.
currency.
code
Required String Alphabetic. Min length: 3 Max length: 5 3 letter ISO currency code in which the price is denominated. Only uppercase characters are accepted. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD. Format: Alphabetic. Min length: 3 Max length: 5
priceSearchCriteria.
product.
carHire
Conditional Complex type [0..1] This element represents the Car Hire product. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
carHire.
price
Required Complex type [0..1] Car HirePrice details
priceSearchCriteria.
product.
carHire.
price.
monetaryAmount
Required Complex type [1..1] Represents the amount & currency code
priceSearchCriteria.
product.
carHire.
price.
monetaryAmount.
amount
Required Number Numeric with special character . (point). Max length: 9 Car HirePrice. Maximum of 6 digits before the decimal point and 2 after. Example: 230.00 Format: Numeric with special character . (point). Max length: 9
priceSearchCriteria.
product.
carHire.
price.
monetaryAmount.
currency
Required Complex type [1..1] The units in which the price is supplied.
priceSearchCriteria.
product.
carHire.
price.
monetaryAmount.
currency.
code
Required String Alphabetic. Min length: 3 Max length: 5 3 letter ISO currency code in which the price is denominated. Only uppercase characters are accepted. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD. Format: Alphabetic. Min length: 3 Max length: 5
priceSearchCriteria.
product.
hotel
Conditional Complex type [0..1] This element represents the hotel product. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
hotel.
price
Required Complex type [0..1] Hotel Price details
priceSearchCriteria.
product.
hotel.
price.
monetaryAmount
Required Complex type [1..1] Represents the amount & currency code
priceSearchCriteria.
product.
hotel.
price.
monetaryAmount.
amount
Required Number Numeric with special character . (point). Max length: 9 HotelPrice. Maximum of 6 digits before the decimal point and 2 after. Example: 125.00 Format: Numeric with special character . (point). Max length: 9
priceSearchCriteria.
product.
hotel.
price.
monetaryAmount.
currency
Required Complex type [1..1] The units in which the price is supplied.
priceSearchCriteria.
product.
hotel.
price
Required String Alphabetic. Min length: 3 Max length: 5 3 letter ISO currency code in which the price is denominated. Only uppercase characters are accepted. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD. Format: Alphabetic. Min length: 3 Max length: 5
priceSearchCriteria.
product.
insurance
Conditional Complex type [0..1] This element represents the insurance product. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
insurance.
price
Required Complex type [0..1] InsurancePrice details
priceSearchCriteria.
product.
insurance.
price.
monetaryAmount
Required Complex type [1..1] Represents the amount & currency code
priceSearchCriteria.
product.
insurance.
price.
monetaryAmount.
amount
Required Number Numeric with special character . (point). Max length: 9 InsurancePrice. Maximum of 6 digits before the decimal point and 2 after. Example: 100.00 Format: Numeric with special character . (point). Max length: 9
priceSearchCriteria.
product.
insurance.
price.
monetaryAmount.
currency
Required Complex type [1..1] The units in which the price is supplied.
priceSearchCriteria.
product.
insurance.
price.
monetaryAmount.
currency.
code
Required String Alphabetic. Min length: 3 Max length: 5 3 letter ISO currency code in which the price is denominated. Only uppercase characters are accepted. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD. Format: Alphabetic. Min length: 3 Max length: 5
priceSearchCriteria.
product.
packagedProduct
Conditional Array of Complex type [0..n] This element represents the packaged product. Products (Flight, Flight Ancillary, Car Hire, Hotel and Insurance) could be packaged together to retrieve the discount price points. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
packagedProduct.
flight
Conditional Array of Complex type [0..n] The entire list of above mentioned Flight related elements are applicable for this packaged Flight also. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
packagedProduct.
flightAncillary
Conditional Array of Complex type [0..n] The entire list of above mentioned Flight Ancillary related elements are applicable for this packaged Flight Ancillary also. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
packagedProduct.
carHire
Conditional Array of Complex type [0..n] The entire list of above mentioned Car Hire related elements are applicable for this packaged Car Hire also. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
packagedProduct.
hotel
Conditional Array of Complex type [0..n] The entire list of above mentioned Hotel related elements are applicable for this packaged Hotel also. At least one type of product must be supplied in request.
priceSearchCriteria.
product.
packagedProduct.
insurance
Conditional Array of Complex type [0..n] The entire list of above mentioned Insurance related elements are applicable for this packaged Insurance also. At least one type of product must be supplied in request.

Response Elements

The following is an exmaple of a Flight response from the Product Pricing API:

{
  "product": [
    {
      "flight": {
        "passengerSummary": {
          "adultCount": 1,
          "youngAdultCount": 1,
          "childCount": 1,
          "infantCount": 1,
          "seniorCount": 1
        },
        "segment": [
          {
            "outBound": true,
            "priceScheme": "PEAK",
            "leg": [
              {
                "schedule": {
                  "departureDateRange": {
                    "startDateTime": "2017-04-02T13:52:21.313Z"
                  },
                  "departureLocation": {
                    "id": "DUB",
                    "type": "AIRPORT"
                  },
                  "arrivalLocation": {
                    "id": "LHR",
                    "type": "AIRPORT"
                  }
                },
                "marketingCarrier": {
                  "flightNumber": "0309",
                  "iataCode": {
                    "code": "EI"
                  }
                },
                "operatingCarrier": {
                  "flightNumber": "0309",
                  "iataCode": { "code": "EI" }
                },
                "bookingClass": {
                  "code": "J"
                },
                "cabinClass": {
                  "code": "ECONOMY"
                },
                "fareFamilyCode": "FF1"
              }
            ]
          }
        ],
        "price": [
          {
            "monetaryAmount": [
              {
                "amount": "1500",
                "currency": {
                  "code": "AVIOS"
                }
              },
              {
                "amount": "5.00",
                "currency": {
                  "code": "GBP"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "4500",
                "currency": {
                  "code": "AVIOS"
                }
              },
              { "amount": "15.00", "currency": { "code": "GBP" } }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "7500",
                "currency": {
                  "code": "AVIOS"
                }
              },
              {
                "amount": "25.00",
                "currency": {
                  "code": "GBP"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          }
        ]
      }
    }
  ]
}

A Flight ancilliary response from the Product Pricing API:

{
  "product": {
    "flightAncillary": {
      "flightAncillaryType": "BAGGAGE",
      "price": [
        {
          "monetaryAmount": [
            {
              "amount": "25.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "750",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "50.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "1450",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "75.00",
              "currency": {
                "code": "GBP"
              }
            },
            { "amount": "2500", "currency": { "code": "AVIOS" } }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        }
      ]
    }
  }
}

A Car Hire response from the Product Pricing API:

{
  "product": {
    "carHire": {
      "price": [
        {
          "monetaryAmount": [
            {
              "amount": "35.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "1750",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "50.00",
              "currency": {
                "code": "GBP"
              }
            },
            { "amount": "2450", "currency": { "code": "AVIOS" } }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "75.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "2500",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        }
      ]
    }
  }
}

A Hotel response from the Product Pricing API:

{
  "product": {
    "hotel": {
      "price": [
        {
          "monetaryAmount": [
            { "amount": "50.00", "currency": { "code": "GBP" } },
            { "amount": "2050", "currency": { "code": "AVIOS" } }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "75.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "5000",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "100.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "9000",
              "currency": { "code": "AVIOS" }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        }
      ]
    }
  }
}

A Insurance response from the Product Pricing API:

{
  "product": {
    "insurance": {
      "price": [
        {
          "monetaryAmount": [
            {
              "amount": "50.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "2050",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "75.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "5000",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        },
        {
          "monetaryAmount": [
            {
              "amount": "100.00",
              "currency": {
                "code": "GBP"
              }
            },
            {
              "amount": "9000",
              "currency": {
                "code": "AVIOS"
              }
            }
          ],
          "priceOptionType": "PART_AVIOS_PART_CASH"
        }
      ]
    }
  }
}

A Package product response from the Product Pricing API:

{
  "product": {
    "packagedProduct": {
      "flight": {
        "passengerSummary": {
          "adultCount": "1",
          "youngAdultCount": "1",
          "childCount": "1",
          "infantCount": "1",
          "seniorCount": "1"
        },
        "segment": {
          "outBound": "true",
          "priceScheme": "PEAK",
          "leg": {
            "schedule": {
              "departureDateRange": { "startDateTime": "2016-12-31T12:00:00" },
              "departureLocation": { "id": "LHR", "type": "AIRPORT" },
              "arrivalLocation": { "id": "JFK", "type": "AIRPORT" }
            },
            "marketingCarrier": {
              "flightNumber": "151",
              "iataCode": { "code": "EI" }
            },
            "operatingCarrier": {
              "flightNumber": "151",
              "iataCode": { "code": "EI" }
            },
            "bookingClass": { "code": "Y" },
            "cabinClass": { "code": "Economy" },
            "fareFamilyCode": "FF1"
          }
        },
        "price": [
          {
            "monetaryAmount": [
              { "amount": "50.00", "currency": { "code": "GBP" } },
              {
                "amount": "1000",
                "currency": {
                  "code": "AVIOS"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "175.00",
                "currency": {
                  "code": "GBP"
                }
              },
              {
                "amount": "15250",
                "currency": {
                  "code": "AVIOS"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "250.00",
                "currency": {
                  "code": "GBP"
                }
              },
              { "amount": "25000", "currency": { "code": "AVIOS" } }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          }
        ]
      },
      "flightAncillary": {
        "flightAncillaryType": "BAGGAGE",
        "price": [
          {
            "monetaryAmount": [
              {
                "amount": "25.00",
                "currency": {
                  "code": "GBP"
                }
              },
              {
                "amount": "750",
                "currency": {
                  "code": "AVIOS"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "50.00",
                "currency": {
                  "code": "GBP"
                }
              },
              {
                "amount": "1450",
                "currency": {
                  "code": "AVIOS"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          },
          {
            "monetaryAmount": [
              {
                "amount": "75.00",
                "currency": {
                  "code": "GBP"
                }
              },
              {
                "amount": "2500",
                "currency": {
                  "code": "AVIOS"
                }
              }
            ],
            "priceOptionType": "PART_AVIOS_PART_CASH"
          }
        ]
      }
    }
  }
}
Name Presence Data type Format Description
product Present Complex type [1..n] Product is the generalised element.
product.
flight
Conditional Complex type [0..1] This element further specifies the product. In this case, the element describes a flight. Is visible only if passed in request message.
priceSearchCriteria.
product.
directFlght
Present String True/false Specifies if the flight is direct. If not provided in request message default false is assigned. Format: True/false
product.
flight.
returnJourney
Present Boolean True/false Specifies if the journey is return. If not provided in request message default false is assigned. Format: True/false
product.
flight.
passengerSummary
Conditional Complex type [0..1] Contains information about passengers. Is visible if passed in request message.
product.
flight.
passengerSummary.
adultCount
Present Number Numeric only. Max value: 2147483647 Number of adult passengers. If this element were not passed in request message 0 is assigned as default value. Format: Numeric only. Max value: 2147483647
product.
flight.
passengerSummary.
youngAdultCount
Present Number Numeric only. Max value: 2147483647 Number of young adult passengers. If this element were not passed in request message 0 is assigned as default value. Format: Numeric only. Max value: 2147483647
product.
flight.
passengerSummary.
childCount
Present Number Numeric only. Max value: 2147483647 Number of child passengers. If this element were not passed in request message 0 is assigned as default value. Format: Numeric only. Max value: 2147483647
product.
flight.
passengerSummary.
infantCount
Present Number Numeric only Max value: 2147483647 Number of infant passengers. If this element were not passed in request message 0 is assigned as default value. Format: Numeric only Max value: 2147483647
product.
flight.
passengerSummary.
seniorCount
Present Number Numeric only Max value: 2147483647 Number of senior passengers. If this element were not passed in request message 0 is assigned as default value. Format: Numeric only Max value: 2147483647
product.
flight.
segment
Present Array of Complex type [1..n] Flight Segment.
product.
flight.
segment.
outbound
Present Boolean true/false true represents the outbound flight and false represents the inbound flight. If not provided in request message then will be defaulted to false. Format: true/false
product.
flight.
segment.
leg
Present Array of Complex type [1..n] One point-to-point journey in a flight segment. This element describes the route of a leg within the segment of a flight.
priceSearchCriteria.
product.
flight.
segment.
leg.
fareFamilyCode
Conditional String Alphanumeric Max length: 5 Specifies fare family code. Will be visible only if provided in request message. Example: FF1, FF2, FF3, FF4, FF5, FF6, FF7, FF8, FF9, FF10 Format: Alphanumeric Max length: 5
product.
flight.
segment.
leg.
schedule
Present Complex type [1..1] The flight schedule identifies the departure date, departure location and arrival location.
product.
flight.
segment.
leg.
schedule.
departureDateRange
Present Complex type [1..1] Specifies departure date.
product.
flight.
segment.
leg.
schedule.
departureDateRange.
startDateTime
Present DateTime ISO-8601 Calendar date format. YYYY-MM-DDThh:mm:ss.sTZ D Start date and time of outbound journey. Example: 2017- 12-12T13:39:16.213+01:00 Format: ISO-8601 Calendar date format. YYYY-MM-DDThh:mm:ss.sTZ D
product.
flight.
segment.
leg.
schedule.
departureLocation
Present Complex type [1..1] Outbound location of a particular leg for this route.
product.
flight.
segment.
leg.
schedule.
departureLocation.
id
Present String Alphabetic. Max length: 3 3 letter IATA Airport code that identifies the departure location. Example: LHR, LGW, LCY Format: Alphabetic. Max length: 3
product.
flight.
segment.
leg.
schedule.
departureLocation.
type
Present String Enumeration Type of departure location. Will always be AIRPORT. Format: Enumeration
product.
flight.
segment.
leg.
schedule.
arrivalLocation
Present Complex type [1..1] Inbound location of a particular leg for this route.
product.
flight.
segment.
leg.
schedule.
arrivalLocation.
id
Present String Alphabetic. Max length: 3 3 letter IATA Airport code that identifies the arrival location. Example: JFK, DUB, SYD Format: Alphabetic. Max length: 3
product.
flight.
segment.
leg.
schedule.
arrivalLocation.
type
Present String Enumeration Type of arrival location. Will always be AIRPORT. Format: Enumeration
product.
flight.
segment.
leg.
marketingCarrier
Present Complex type [1..1] Marketing carrier of the flight.
product.
flight.
segment.
leg.
marketingCarrier.
flightNumber
Present String Numeric only Max length: 4 Flight Number. Example: 0016 Format: Numeric only Max length: 4
product.
flight.
segment.
leg.
marketingCarrier.
iatacode
Present Complex type [1..1] Flight’s IATA code.
product.
flight.
segment.
leg.
marketingCarrier.
iatacode.
code
Present String Alphabetic. Max length: 2 Min length: 2 2 letter IATA carrier code. Example: EI, BA, VY Format: Alphabetic. Max length: 2 Min length: 2
product.
flight.
segment.
leg.
operatingCarrier
Present Complex type [1..1] Operating carrier of the flight.
product.
flight.
segment.
leg.
operatingCarrier.
flightNumber
Present String Numeric only Max length: 4 Flight Number.Example: 0017 Format: Numeric only Max length: 4
product.
flight.
segment.
leg.
operatingCarrier.
iatacode
Present Complex type [1..1] Flight’s IATA code.
product.
flight.
segment.
leg.
operatingCarrier.
iatacode.
code
Present String Alphabetic. Max length: 2 Min length: 2 2 letter IATA carrier code. Example: EI, BA, VY Format: Alphabetic. Max length: 2 Min length: 2
product.
flight.
segment.
leg.
bookingClass
Conditional Complex type [0..1] Information about booking class. Will be visible if supplied in request message.
product.
flight.
segment.
leg.
bookingClass.
code
Conditional String Alphabetic. Max length: 1 Booking class.Example: Y, KWill not be visible if not provided in request message. Format: Alphabetic. Max length: 1
product.
flight.
segment.
leg.
cabinClass
Conditional Complex type [0..1] Information about cabin class. Will be visible if supplied in request message.
product.
flight.
segment.
leg.
cabinClass.
code
Conditional String Alphabetic Max length: 20 Example: ECONOMY, BUSINESS, FIRST. Will not be visible if not provided in request message. Format: Alphabetic Max length: 20
product.
flight.
price
Present Array of Complex type [1..1] Flight level discount price options.
product.
flight.
price.
monetaryAmount
Present Array of Complex type [1..n] Represents the amount & currency code
product.
flight.
price.
monetaryAmount.
amount
Present Number Numeric with special character . (point). Max length: 9 Contains discounted cash price or AVIOS value of the cash discount.Maximum of 6 digits before the decimal point and 2 after. Format: Numeric with special character . (point). Max length: 9
product.
flight.
price.
monetaryAmount.
currency
Present Complex type [1..1] The units in which the price is supplied.
product.
flight.
price.
monetaryAmount.
currency.
code
Present String Alphabetic only. Max length: 5 Min length: 3 3 letter ISO 4217 currency code in which the price is denominated. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD Format: Alphabetic only. Max length: 5 Min length: 3
product.
flight.
price.
priceOptionType
Present String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH. Format: Enumeration
product.
flightAncillary
Conditional Complex type [0..1] This element further specifies the product. In this case, the element describes a Flight Ancillary. Is visible only if passed in request message.
product.
flightAncillary.
flightAncillaryType
Present String Enumeration Will be any one of below values. SEAT PET BAGGAGE SPECIAL_BAGGAGE LOUNGE_PASS PARKING MEALS WIFI UPGRADE BUY_ON_BOARD UNACCOMPANIED_MINOR FEES Format: Enumeration
product.
flightAncillary.
price
Present Array of Complex type [1..1] Flight Ancillary Price details
product.
flightAncillary.
price.
monetaryAmount
Present Array of Complex type [1..n] Represents the amount & currency code
product.
flightAncillary.
price.
monetaryAmount.
amount
Present Number Numeric with special character . (point). Max length: 9 Contains discounted cash price or AVIOS value of the cash discount.Maximum of 6 digits before the decimal point and 2 after. Format: Numeric with special character . (point). Max length: 9
product.
flightAncillary.
price.
monetaryAmount.
currency
Present Complex type [1..1] The units in which the price is supplied.
product.
flightAncillary.
price.
monetaryAmount.
currency.
code
Present String Alphabetic only. Max length: 5 Min length: 3 3 letter ISO 4217 currency code in which the price is denominated. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD Format: Alphabetic only. Max length: 5 Min length: 3
product.
flightAncillary.
price.
priceOptionType
Present String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH Format: Enumeration
product.
carHire
Conditional Complex type [0..1] This element further analyses the product. In this case, the element describes a Car Hire. Is visible only if passed in request message.
product.
carHire.
price
Present Array of Complex type [1..1] Car Hire Price details
product.
carHire.
price.
monetaryAmount
Present Array of Complex type [1..n] Represents the amount & currency code
product.
carHire.
price.
monetaryAmount.
amount
Present Number Numeric with special character . (point). Max length: 9 Contains discounted cash price or AVIOS value of the cash discount.Maximum of 6 digits before the decimal point and 2 after. Format: Numeric with special character . (point). Max length: 9
product.
carHire.
price.
monetaryAmount.
currency
Present Complex type [1..1] The units in which the price is supplied.
product.
carHire.
price.
monetaryAmount.
currency.
code
Present String Alphabetic only. Max length: 5 Min length: 3 3 letter ISO 4217 currency code in which the price is denominated. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD Format: Alphabetic only. Max length: 5 Min length: 3
product.
carHire.
price.
priceOptionType
Present String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH Format: Enumeration
product.
hotel
Conditional Complex type [0..1] This element further analyses the product. In this case, the element describes a Hotel. Is visible only if passed in request message.
product.
hotel.
price
Present Array of Complex type [1..1] Hotel Price details
product.
hotel.
price.
monetaryAmount
Present Array of Complex type [1..n] Represents the amount & currency code
product.
hotel.
price.
monetaryAmount.
amount
Present Number Numeric with special character . (point). Max length: 9 Contains discounted cash price or AVIOS value of the cash discount.Maximum of 6 digits before the decimal point and 2 after. Format: Numeric with special character . (point). Max length: 9
product.
hotel.
price.
monetaryAmount.
currency
Present Complex type [1..1] The units in which the price is supplied.
product.
hotel.
price.
monetaryAmount.
currency.
code
Present String Alphabetic only. Max length: 5 Min length: 3 3 letter ISO 4217 currency code in which the price is denominated. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD Format: Alphabetic only. Max length: 5 Min length: 3
product.
hotel.
price.
priceOptionType
Present String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH Format: Enumeration
product.
insurance
Conditional Complex type [0..1] This element further analyses the product. In this case, the element describes Insurance. Is visible only if passed in request message.
product.
insurance.
price
Present Array of Complex type [1..1] Insurance Price details
product.
insurance.
price.
monetaryAmount
Present Array of Complex type [1..n] Represents the amount & currency code
product.
insurance.
price.
monetaryAmount.
amount
Present Number Numeric with special character . (point). Max length: 9 Contains discounted cash price or AVIOS value of the cash discount.Maximum of 6 digits before the decimal point and 2 after. Format: Numeric with special character . (point). Max length: 9
product.
insurance.
price.
monetaryAmount.
currency
Present Complex type [1..1] The units in which the price is supplied.
product.
insurance.
price.
monetaryAmount.
currency.
code
Present String Alphabetic only. Max length: 5 Min length: 3 3 letter ISO currency code in which the price is denominated. Example: USD, GBP, CAD, EUR, CHF, SEK, DKK, NOK, RUB, ZAR and MAD Format: Alphabetic only. Max length: 5 Min length: 3
product.
insurance.
price.
priceOptionType
Present String Enumeration Specifies the price option. Will be PART_AVIOS_PART_CASH Format: Enumeration
product.
packagedProduct
Conditional Array of Complex type [0..n] This element further analyses the product. In this case, the element describes Packaged Product. Is visible only if passed in request message. Products (Flight, Flight Ancillary, Car Hire, Hotel and Insurance) could be packaged together to retrieve the discount price points.
product.
packagedProduct.
flight
Conditional Array of Complex type [0..n] The entire list of above mentioned Flight related elements are applicable for this packaged Flight also. Is visible only if passed in request message.
product.
packagedProduct.
flightAncillary
Conditional Array of Complex type [0..n] The entire list of above mentioned Flight Ancillary related elements are applicable for this packaged Flight Ancillary also. Is visible only if passed in request message.
product.
packagedProduct.
carHire
Conditional Array of Complex type [0..n] The entire list of above mentioned Car Hire related elements are applicable for this packaged Car Hire also. Is visible only if passed in request message.
product.
packagedProduct.
hotel
Conditional Array of Complex type [0..n] The entire list of above mentioned Hotel related elements are applicable for this packaged Hotel also. Is visible only if passed in request message.
product.
packagedProduct.
insurance
Conditional Array of Complex type [0..n] The entire list of above mentioned Insurance related elements are applicable for this packaged Insurance also. Is visible only if passed in request message.

Exception Message Elements

The following is an example of an error response from the Product Pricing API:

{
  "error": {
    "code": "REQUEST_UNAUTHORIZED",
    "businessMessage": "RequestUnauthorized",
    "developerMessage": "RequestUnauthorized",
    "developerLink": "https://developer.avios.com/docs",
    "childError": [
      {
        "code": "GATEWAY_AUTHENTICATION_FAILED",
        "businessMessage": "GatewayAuthenticationFailed",
        "developerMessage": "GatewayAuthenticationFailed",
        "developerLink": "https://developer.avios.com/docs"
      }
    ]
  }
}
Name Presence Data type Format Description
error Present Complext ype [0..1] Will only be present if an error has been detected and reported by the API.
error.
code
Present String Alphabetic plus under-score (_). Error code Format: Alphabetic plus under-score (_).
error.
businessMessage
Conditional String Alphabetic Error “business-facing” error message. Format: Alphabetic
error.
developerMessage
Conditional String Alphabetic Error message specific to a developer. Format: Alphabetic
error.
developerLink
Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).
error.
childError.
Conditional Array of complex type [0..n] Will only be present if an error has been detected and reported by the API.
error.
childError.
code
Conditional String Alphabetic plus under-score (_). Error code Format: Alphabetic plus under-score (_).
error.
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Path of the node on which caused the error to occur Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
error.
childError.
businessMessage
Conditional String Alphabetic Error message to business Format: Alphabetic
error.
childError.
developerMessage
Conditional String Alphabetic Error message specific to client developer. Format: Alphabetic
error.
childError.
developerLink
Conditional String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

HTTP Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract.
400 REQUEST_INVALID INVALID_OUTBOUND_DATE If Outbound DepartureDateTime is less than current time
400 REQUEST_INVALID INVALID_INBOUND_DATE If Inbound DepartureDateTime is less than current time or
400 REQUEST_INVALID MANDATORY_DATA_MISSING If the mandatory data elements are not supplied in the request
400 REQUEST_INVALID INVALID_PRICE_SOURCE If unsupported price source is received. Only valid price source is CACHED
400 REQUEST_INVALID MARSHALLING_FAILED Price type STATIC_DISCOUNT is used with other product than FLIGHT.
400 REQUEST_INVALID INVALID_PRICE_TYPE If unsupported price type is received. Only valid price types are STATIC_DISCOUNT DYNAMIC_DISCOUNT
400 REQUEST_INVALID INVALID_CONTENT_TYPE If invalid content type is supplied in the request
400 REQUEST_INVALID MEDIA_TYPE_NOT_SUPPORTED If invalid accept header value is supplied in request.
400 REQUEST_INVALID INVALID_CURRENCY If exchange rates are not configured for requested currency
400 INVALID_MARKETING_OPERATING_CARRIER_COMBINATION If supplied marketing & operating carrier codes are not valid
400 INSUFFICIENT_MEMBER_BALANCE If member is logged in and doesn’t have enough Avios balance to use.

Retrieve Transactions

v1

The Retrieve Transactions API 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 API Flow

Technical Context

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: Transaction details are returned in the API 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
Name Required Type Format Description Example
version Required String Alphanumeric. v[1..9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric. v[1..9] v1
programme-identifier Required String Currently restricted to ATRP. The 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 Numeric Min length = 1.Max Length = 24. Numeric only. Unique Identifier of the member of the loyalty programme. Example: membership number Format: Min length = 1.Max Length = 24. Numeric only. 3081470000000000
api_key Required String Alphanumeric. Min length = 24. Max Length = 24. The 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

Name Required Type Format Description Example
Accept Optional String Currently restricted to application/json The Accept request-header field specifies certain media types, which are acceptable for the response. Format: Currently restricted to application/json application/json
Authorization Required String JWT Token The 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 String IP address Identifies 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 API:

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
Name Required Type Format Description
start-record Optional Integer Numeric only. Max numeric value = 99999, min numeric value = 1. Index 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 Integer Numeric only. Max numeric value = 99999, min numeric value = 1. Index 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 Date format (YYYY-MM-DD) The 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 Date format (YYYY-MM-DD) The 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 String String of max length 10 The 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",
        "dateMade": "2016-09-02T11:03:34.000+01:00",
        "description": "Amit Test",
        "externalSource": "LLOYDS TSB",
        "externalReferenceIdentifier": "B1X2ZA",
        "amount": {
          "amount": 100,
          "formattedAmount": "100",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    },
    {
      "debitTransaction": {
        "identifier": "3654B32AF11EA384E050A8C0020A53F0",
        "dateMade": "2016-06-28T11:02:49.000+01:00",
        "description": "Avios Booking (LMR0284938)",
        "externalReferenceIdentifier": "LMR0284938",
        "amount": {
          "amount": 5200,
          "formattedAmount": "5200",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    },
    {
      "creditTransaction": {
        "identifier": "2E8DBE53DBEE56F2E050A8C0020A091E",
        "dateMade": "2014-09-25T14:44:34.000+01:00",
        "description": "Avios Amendment (Ref. 5306475)",
        "externalReferenceIdentifier": "6475UK",
        "amount": {
          "amount": 8625,
          "formattedAmount": "8625",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    }
  ]
}

With Range Filter:

{
  "transaction": [
    {
      "debitTransaction": {
        "identifier": "395079D03F46027BE050A8C0020A62BD",
        "dateMade": "2016-09-01T15:39:11.000+01:00",
        "description": "Avios Booking (LMR0290526)",
        "externalReferenceIdentifier": "LMR0290526",
        "amount": {
          "amount": 4900,
          "formattedAmount": "4900",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    },
    {
      "debitTransaction": {
        "identifier": "3654B32AF123A384E050A8C0020A53F0",
        "dateMade": "2016-06-28T11:02:50.000+01:00",
        "description": "Avios Booking (LMR0284943)",
        "externalReferenceIdentifier": "LMR0284943",
        "amount": {
          "amount": 19300,
          "formattedAmount": "19300",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    }
  ]
}

With range and match filter:

{
  "transaction": [
    {
      "creditTransaction": {
        "identifier": "6965162461003",
        "dateMade": "2016-09-02T11:03:34.000+01:00",
        "description": "Amit Test",
        "externalSource": "LLOYDS TSB",
        "externalReferenceIdentifier": "B1X2ZA",
        "amount": {
          "amount": 100,
          "formattedAmount": "100",
          "currency": {
            "currencyCode": "AVIOS"
          }
        }
      }
    }
  ]
}
Name Presence Type Format Description
transaction Conditional Array of Complex type [0..1] A 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..n] A 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 String Alphanumeric. Max length: 32 The unique identifier of the debit transaction within Avios systems. Format: Alphanumeric. Max length: 32
Transaction.
debitTransaction.
dateMade
Present Date YYYY-MM-DDThh:mm:ss.sTZD The 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 String Alphanumeric with special characters~!@#\$%^&*()_-+=}]{[ ;:’><.,?/ (andspace). Min Length: 1, max length: 51. A description of the debit transaction. Example: DESC ERI Format: Alphanumeric with special characters~!@#\$%^&*()_-+=}]{[ ;:’><. min="" length:="" max=""/>
transaction.
debitTransaction.
externalReferenceIdentifier
Present String Alphanumeric only. Max length: 10 The 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..1] A Complex Type, which represents the transaction amount.
Transaction.
debitTransaction.
amount.
amount
Present Big decimal Numeric. Max length: 6 The transaction amount, in Avios, expressed as a numeric. Example: 1 Format: Numeric. Max length: 6
transaction.
debitTransaction.
amount.
formattedAmount
Present String Alphanumeric. Max length: 6 The 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..1] A complex type, which represents the specific currency of a transaction.
Transaction.
debitTransaction.
amount.
currency.
currencyCode
Present String Enumeration Loyalty programme currency identifier. At present only ‘AVIOS’ is supported. Example: AVIOS Format: Enumeration
transaction.
creditTransaction
Conditional Array of Complex type [0..n] A 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 String Alpha numeric. Max length: 32 The unique identifier of the credit transaction within Avios systems. Format: Alpha numeric. Max length: 32
Transaction.
creditTransaction.
dateMade
Present Date YYYY-MM-DDThh:mm:ss.sTZD This 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 String Alphanumeric with special characters. Min length: 1 Max length: 51 & . - _ ‘ / , % + (and space) A description of the credit transaction. Example: JKL Format: Alphanumeric with special characters. Min length: 1 Max length: 51 & . - _ ‘ / , % + (and space)
transaction.
creditTransaction.
externalSource
Present String Alphanumeric with special characters. Max length: 10 & . - _ ‘ / , % + (and space) The partner name related to the transaction. Format: Alphanumeric with special characters. Max length: 10 & . - _ ‘ / , % + (and space)
Transaction.
creditTransaction.
externalReferenceIdentifier
Present String Alphanumeric with special characters. Max length: 10 & . - _ ‘ / , % + (and space) The partner’s reference for the credit transaction. Example: 14426D Format: Alphanumeric with special characters. Max length: 10 & . - _ ‘ / , % + (and space)
transaction.
creditTransaction.
amount
Present Complex type [1..1] A Complex Type, which represents the transaction amount.
Transaction.
creditTransaction.
amount.
amount
Present Big decimal Max length: 6 Numeric The transaction amount, in Avios, expressed as a numeric. Example: 999999 Format: Max length: 6 Numeric
transaction.
creditTransaction.
amount.
formattedAmount
Present String Max length: 6 Alphanumeric The 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..1] A complex type, which represents the specific currency of a transaction.
Transaction.
creditTransaction.
amount.
currency.
currencyCode
Present String Enumeration Loyalty 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.avios.com/docs",
    "childError": [
      {
        "code": "DATE_RANGE_INVALID",
        "path": "date-made-to",
        "businessMessage": "date-made-to should be greater than date-made-from",
        "developerLink": "https://developer.avios.com/docs"
      }
    ]
  }
}
Name Presence Type Format Description
error Conditional Complex Type [0..1] Will only be present if an error has been detected and reported by the API.
error.
code
Present String Alphabetic plus under- score (_). Error code. Example: REQUEST_INVALID Format: Alphabetic plus under- score (_).
error.
businessMessage
Present String Alphabetic A business level message describing the error, which has occurred. Example: Request invalid Format: Alphabetic
error.
developerMessage
Conditional String Alphabetic Developer 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 String Alphabetic plus colon (â˜ş, oblique (.), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (â˜ş, oblique (.), dash (-), underscore (_) or period (.).
error.
childError
Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
error.
childError.
code
Present String Alphabetic plus under- score (_). The 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 String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]). Path of the node on which error occurred. This will not come in case of any of the authorization header elements are invalid or missing. Example: member.person.name.firstName Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]).
error.
childError.
businessMessage
Present String Alphabetic A business level message describing the error, which has occurred. Example: Data invalid Format: Alphabetic
error.
childError.
developerMessage
Conditional String Alphabetic Developer 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 String Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.). A URL link to a web page containing more detailed information about the error code. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (-), underscore (_) or period (.).

Error Codes

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

HTTP Status Code Parent error code Child error code Description
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.

Reverse Transaction

v1

The Reverse Transaction API is intended to reverse previously processed debit transactions. Identification details of the transaction to be reversed are passed in the request. The entire amount for the given transaction will be reversed and a transaction identifier for the reversed transaction will be supplied in the response. Before invoking this service, an access token should be obtained from a successful call to the Create Token API.

Business Context

Here’s the process flow:

Reverse Transactions API Flow

Important Technical Notes

Pre-conditions

Post-conditions

Success outcome: A reverse transaction is generated for the member’s account with the original product value (credit).

Error outcome: Service error is returned.

Service Details

URI Parameters

Production Endpoint:

'POST https://api.avios.com/{version}/programmes/{programme-identifier}/accounts/{account-identifier}/reverse-transaction-requests?api_key={api_key}'

Example

https://api.avios.com/v1/programmes/ATRP/accounts/3081470000000000/reverse-transaction-requests?api_key=abcdef
Name Required Data type Format Description Example
version Required String Alphanumeric v[0-9] The version of the API which will be confirmed during the on-boarding process. Format: Alphanumeric v[0-9] v1
programme-identifier Required String Currently restricted to ATRP or BAEC The 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 API key. Format: Currently restricted to ATRP or BAEC ATRP
account-identifier Required String Min length = 1, Max Length = 24. Numeric only. The 16-digit membership number starting with 308147. Format: Min length = 1, Max Length = 24. Numeric only. 3081470000000000
api_key Required String Alphanumeric only. Min length = 24, Max length = 24 The API key provided during the partner configuration which takes place as part of the partner on-boarding process. Format: Alphanumeric only. Min length = 24, Max length = 24 abcdabcdabcdabcdabcdabcd

Request Headers

Name Required Data type Format Description Example
Authorization Required String JWT token Security token authorising access to the specified member's account. Format: JWT token
Accept Optional String application/< content-type > The Accept request-header field is used to specify certain media types which are acceptable for the response. Only application/jsonis accepted currently. Format: application/< content-type > application/json
Content-Type Required String application/< content-type > The Content-Type request-header field indicates the media type of the entity-body sent to the recipient as request payload. Only application/jsonis accepted currently. Format: application/< content-type > application/json
X-Forwarded-For Optional String Valid IP address The IP address of the end customer. Format: Valid IP address 172.17.1.1
X-Agent-Id Optional String Alphanumeric An agent Id represents the agent name/user name/login id for offline channels like call centres. Format: Alphanumeric Masanobu.Fukuoka

Request Elements

Example of a Request Call to the Reverse Transaction API:

{
  "reversalTransaction": {
    "externalTransactionIdentifier": "12",
    "type": "CANCELLATION",
    "description": "dfs",
    "reversedTransaction": {
      "identifier": "3875243275815CB1E050A8C0020A4B4A"
    }
  }
}
Name Required Data type Format Description
externalTransactionIdentifier Required String Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1 Max length: 64 Represents the transaction which was originally executed in the external system (i.e.: the external partner’s system). Example: 12 Format: Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1 Max length: 64
description Required String Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1 Max length: 64 Description of the reversal transaction for which the request is placed. Format: Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1 Max length: 64
type Required String Enumeration Reversal transaction type. This must be “CANCELLATION”. Format: Enumeration
reversedTransaction Required Complex type [1..1] Contains the transaction that is to be reversed.
reversedTransaction.
identifier
Required String Alphanumeric. Max length: 32 The identifier of the original or actual transaction that is to be reversed. Example: 3875243275815CB1E050A8C0020A4B4A Format: Alphanumeric. Max length: 32

Response Elements

The following is an example of a response generated by the Reverse Transaction API:

{
  "reversalTransaction": {
    "identifier": "3875243275825CB1E050A8C0021A4B4A",
    "dateMade": "2016-12-19T10:46:00.696Z",
    "externalTransactionIdentifier": "12",
    "description": "dfs",
    "type": "CANCELLATION",
    "reversedTransaction": {
      "identifier": "3875243275815CB1E050A8C0020A4B4A"
    }
  }
}

The elements that make up the response message are detailed in the following table:

Name Presence Data type Format Description
identifier Present String Alphanumeric. Min length: 1, Max length: 32 A transaction identifier that uniquely identify the debit or credit transaction specified in the request message. Example: 3875243275815CB1E050A8C0020A4B4A Format: Alphanumeric. Min length: 1, Max length: 32
dateMade Present Date ISO-8601 This is the date that has been stored against the reversal transaction. Example: 2016-12-19T08:46:07.552Z Format: ISO-8601
externalTransactionIdentifier Present String Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1, Max length: 64 This identifies the transaction which was originally executed in the external system (i.e.: the external partner’s system). Example: 12 Format: Alphanumeric with special characters: & . - _’/,%+(and space). Min length: 1, Max length: 64
description Present String Alphanumeric with special characters: & . - _’/,%+(and space). Max length: 64 Reverse transaction description as placed in request. Example: dfs Format: Alphanumeric with special characters: & . - _’/,%+(and space). Max length: 64
type Present String Enumeration Reversal transaction type will always be "CANCELLATION". Format: Enumeration
reversedTransaction Present Complex type [1..1] Information describing the reversed transaction.
reversedTransaction.
identifier
Present String Alphanumeric Max 32 Identifier of original transaction which is reversed. Example: 3875243275815CB1E050A8C0020A4B4A Format: Alphanumeric Max 32

Exception Message Elements

The following shows examples of error responses generated by the Reverse Transaction API:

Example 1: Application error:

{
  "error": {
    "code": "REVERSAL_NO_LONGER_PERMITTED",
    "businessMessage": "Reversal No Longer Permitted",
    "developerLink": "https://developer.avios.com"
  }
}

Example 2: Validation error:

{
  "error": {
    "code": "REQUEST_INVALID",
    "businessMessage": "Request Invalid",
    "developerLink": "https://developer.avios.com/docs",
    "childError": [
      {
        "code": "DATA_INVALID",
        "businessMessage": "Data Invalid",
        "developerMessage": "cvc-type.3.1.3: The value '' of element 'ExternalTransactionIdentifier' is not valid.",
        "developerLink": "https://developer.avios.com/docs"
      }
    ]
  }
}
Name Presence Data type Format Description
error.
code
Present String Alphabetic plus under-score (_) Error code. Example: REQUEST_INVALID Format: Alphabetic plus under-score (_)
error.
businessMessage
Present String Alphabetic A business level message describing the error which has occurred. Example: Request Invalid Format: Alphabetic
error.
developerMessage
Conditional String Alphabetic Developer 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 String Alphabetic plus colon (:), oblique (/), dash (- ), underscore (_) or period (.) A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (- ), underscore (_) or period (.)
error.
childError
Conditional Array of complex type [0..n] Present for certain errors (e.g. validation) where one or more child error may have occurred.
error.
childError.
code
Present String Alphabetic plus under-score (_) The error code for the child error (if returned). Example: DATA_INVALID Format: Alphabetic plus under-score (_)
error.
childError.
path
Conditional String Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (]) Identifies the element in the request which has caused the error to occur. This will not come in case of any of the authorization header elements are invalid or missing. If the validation is done beyond the business api, then the path may not come. Format: Alphabetic plus period (.), oblique (/), open bracket ([) or close bracket (])
error.
childError.
businessMessage
Present String Alphabetic A business level message describing the error which has occurred. Example: Data Invalid. Format: Alphabetic
error.
childError.
developerMessage
Conditional String Alphabetic Developer 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.
childError.
developerLink
Present String Alphabetic plus colon (:), oblique (/), dash (- ), underscore (_) or period (.) A link to supporting documentation for this API. Example: https://developer.avios.com/docs Format: Alphabetic plus colon (:), oblique (/), dash (- ), underscore (_) or period (.)

Error Codes

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

Http Status Code Parent error code Child error code Description
400 REQUEST_INVALID DATA_INVALID Request element does not follow the request contract.
400 REQUEST_INVALID MANDATORY_DATA_MISSING Invalid enumeration in request or request not properly formed.
400 ACCOUNT_NOT_AUTHORIZED Passed-in account id is cancelled, deceased, fraud or group.
400 REVERSAL_NO_LONGER_PERMITTED Reversal request comes after permitted time post debit transaction.
400 REVERSAL_NOT_PERMITTED It is not a debit transaction which was tried to reverse.
400 INVALID_MEMBER If an invalid membership number is supplied from Offline channels.

Error Codes

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

HTTP code Parent Error Code Description
400 REQUEST_INVALID Request element does not follow the request contract.
401 REQUEST_UNAUTHORIZED Token in authorization header is invalid for the Programme identifier is invalid.
400 INVALID_MEMBER If an invalid membership number is supplied from Offline channels.
403 DEVELOPER_NOT_AUTHORIZED The provided API key does not provide access to this API.
403 DEVELOPER_INACTIVE The provided API key is no longer active and access to this API is forbidden.
403 USAGE_RATE_EXCEEDED The usage rate (calls per second) has been exceeded for the API Key.
403 USAGE_RATE_LIMIT_EXCEEDED The usage rate limit (calls per day) has been exceeded for the API Key.
403 SSL_REQUIRED This API is required to be accessed using SSL.
503 SCHEDULED_MAINTENANCE This API is not available due to scheduled maintenance.
503 SYSTEM_UNAVAILABLE When a system is not available.
504 GATEWAY_TIMEOUT This API has failed to respond within the expected time.
596 The provided HTTP method is other than ‘POST‘, 'PATCH', 'GET' or 'DELETE'.
406 The provided Accept header is invalid.
415 The provided content-type value is invalid.

Glossary

Acronym Description
API Application Program Interface: a set of routines, protocols and tools for building software applications. The API specifies how software components should interact and APIs are used when programming graphical user interface (GUI) components.
APID Avios Partner Identification
ATRP Avios Travel Rewards Programme.
Avios The Avios reward programme.
BAEC British Airways Executive Club.
BAEC OCD BAEC gateway
Business Required Parameters marked business required are needed in order for AGL to process your request
ISO International Standards Organisation
JSON Java Script Object Notation: An open standard format that uses human- readable text to transmit data objects consisting of attribute–value pairs. It is the primary data format used for asynchronous browser/server communication (AJAJ), largely replacing XML (used by AJAX).
JWT JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.
Mashery A cloud hosted component of the API handling process. This function adds or modifies certain API parameters when a call is received and prior to processing by the called Avios application.
On-boarding The process of signing-up a partner commercially and getting them up to speed with Avios.
PUNTO Vueling’s Loyalty Programme
SOAP Simple Object Access Protocol: a protocol specification for exchanging structured information in the implementation of web services in computer networks. It uses the XML Information Set for its message format, and relies on other application layer protocols, most notably Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission
URI and URL A Uniform Resource Locator (URL), commonly informally termed a web address is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifier (URI) although many people use the two terms interchangeably. A URL implies the means to access an indicated resource, which is not true of every URI. URLs are most commonly used to reference web pages (http), but are also used for file transfer (ftp), email (mailto), database access (JDBC) and many other applications.
UUID A Universally Unique Identifier (UUID) URN Namespace, rfc4122
XML Extensible Markup Language: a mark-up language that defines a set of rules for encoding documents in a format which is both human-readable and machine-readable.