Quick Start Guide for Loyalty Points Balances and Redemption APIs

This guide shows you how to check the Loyalty Points Balance of the customer.

Authentication

The Loyalty Points Balance API have a specific Authentication flow as outlined below.

Loyalty Points Balance API

To view a customer's loyalty points balance on their Shell GO+ account, you first need to make a request to the SSO Tokens API to confirm the customer's consent. This API gives you an access token you can then use to make requests to the Loyalty Points Balance API. The full process is explained in the Loyalty APIs Authentication Guide, but the basic steps are included here. For an illustrated overview of the steps involved - see the sequence diagram below.

*Note: the SSO access token is passed in user-authorization-token and the API gateway access token is passed in client-authorization-token.

Base URLs

1. Begin authentication

Use a POST request to get a basic public token from the Shell Identity API.
Note: The body of the request must contain your SH256-encrypted Client ID. For example, typically formed using the javascript notation:

var digest = CryptoJS.SHA256(user_clinetID).toString();

Key request parameters

Sample request

curl --location --request POST 'https://test.id.consumer.shell.com/api/v2/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "digest": "******************"
}'

Sample response

{
    "token": "**********",
    "tokenType": "Basic",
    "expiresIn": "unlimited",
    "owner": "partner_1"
}

2. Request user permissions

To act on behalf of the user and satisfy the OAuth flow, you need the user to sign into their Shell GO+ account. Once they have signed in, your application redirects the user to the Shell login page with the appropriate query parameters set in the SSO Widget:

https://test.login.consumer.shell.com/?market=<country-code>&partner=true&clientId=<client-id>&redirect=<redirect-url>

The query parameters you must supply are:

• market: A combination of language code (lower case) and country code (upper case), separated by a hyphen. For example: en-BG.
• clientId: unique Shell client ID of the partner. Same key passed previously to get the public token.
• partner: true (default for any customer).
• redirect: Your application redirect URL.

Notes:

• the redirect url test.shell.com needs to be white listed by Shell.
• always use a unique id as part of the redirect url to maintain the conversation state and ensure session tracking, rather than rely on cookies.
  For example test.shell.com/session=1452923773

Once signed in, the Shell SSO login redirects to the application URL specified in the redirect parameter. The URL contains a query parameter specifying the access code. See the code line below.

Note: the accessCode is only valid for 30 secs.

https://<your-redirect-url>?accessCode=****************

3. Access user details

To get the user's unique ID (UUID) and authorization token from the /auth/exchangeAccessCode endpoint, use the access code from step b together with the basic public token you retrieved in step a.

Key request parameters

Sample request

curl --location --request POST 'https://test.id.consumer.shell.com/api/v2/auth/exchangeAccessCode' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic abcde12345' \
--data-raw '{
  "accessCode": "**************"
}'

Sample response

{
    "uuid": "43f1b82a-59c7-42f3-a0ed-fc47b4b4b50e",
    "market": {
        "code": "en-BG",
        "country": "BG"
    },
    "accessToken": "zyxwvu98765",
    "refreshToken": "edcba54321"
}

Note: Make a note of the following values in the response:

• uuid: This is the customer's unique ID. This is referred to as the in later steps.
• accessToken: This is referred to as the in later steps.

4. Get an access token

Obtain an API gatewway access token by making a POST request to the Shell Authentication OAuth endpoint

Key request parameters

Sample request

curl --location --request POST 'https://api-test.shell.com/v1/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=***********' \
--data-urlencode 'client_secret=**********' \
--data-urlencode 'grant_type=client_credentials'

Sample response

{
    "access_token": "***********",
    "expires_in(seconds)": "899",
    "token_type": "BearerToken"
}

Note: Make a note of the accessToken in the response. This is the system to system token referred to as the client-authorisation-token in later steps.

Note: The Access Token in this example is valid for 899s.

5. Viewing the Customer's Loyalty Points balance

Before you redeem an offer, check that the customer has sufficient loyalty points. Do this by making a request to the Loyalty Points Balance API, passing the following header credentials:

• user-authorization-token: The value of the accessToken retrieved from the /auth/exchangeAccessCode endpoint
• client-authorization-token: The value of the accessToken retrieved from the /oauth/token endpoint
• country-code: two character ISO 3166-1 alpha-2 country code
• application: a constant value “PARTNER”
• consumerUUID: The value of the uuid retrieved from the /auth/exchangeAccessCode endpoint.

Key request parameters

Sample request

curl --location --request GET 'https://api-test.shell.com/loyalty/v1/consumers/balances?language_code=de-AT' \
--header 'country-code: AT' \
--header 'user-authorization-token: Bearer **************' \
--header 'client-authorization-token: Bearer ************' \
--header 'language: de' \
--header 'channel: partner' \
--header 'consumerUUID: ************' 

Sample response

The response displays the customer's point balances including the currency in which they are held and the state of each balance.

Possible values for currencyType include:

• POINT: Loyalty Points
• QV: Qualifying Visit (Tracker in the UK)
• AIRMILES: Netherlands only
• CASH: This is the cash cvalue of POINT, if points-to-cash is available

Possible values for state include:

• AVAILABLE: Number of available POINT, QV, etc
• EXPIRING: Points that are due to expire
• TOTAL_SPENT: If points-to-cash is available

{
    "balances": [
        {
            "amounts": [
                {
                    "amount": 95.0,
                    "cashAmount": 0.95,
                    "dateTime": "2023-01-16T17:44:38Z",
                    "dateTimestamp": 1673891078178,
                    "period": 1,
                    "position": [
                        0
                    ],
                    "state": "AVAILABLE"
                },
                {
                    "amount": 5.0,
                    "cashAmount": 0.05,
                    "dateTime": "2023-01-16T17:44:38Z",
                    "dateTimestamp": 1673891078178,
                    "period": 1,
                    "position": [
                        0
                    ],
                    "state": "REDEEMED"
                },
                {
                    "amount": 100.0,
                    "cashAmount": 1.0,
                    "dateTime": "2023-01-16T17:44:38Z",
                    "dateTimestamp": 1673891078178,
                    "period": 1,
                    "position": [
                        0
                    ],
                    "state": "EARNED"
                }
            ],
            "currencyType": "POINT"
        }
    ]
}