Quick Start Guide for Loyalty Points Balances and Redemption APIs

This guide shows you how to use the Loyalty Points Balance and Redemption APIs in order to:

1. Check a customer's loyalty points balance
2. Redeem an offer against that balance
3. Verify that the offer was successfully redeemed

Authentication

The Loyalty Points Balance and Redemption APIs have different authentication requirements. These are 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.

Redemption API

Simply submit your API key with the request, along with the unique ID of the customer.

Base URLs

Step 1: Check a customer's loyalty points balance

a. Begin authentication

Use a POST request to get a basic public token from the Shell Identity API. The body of the request must contain your SH256-encrypted Client ID:

Key request parameters

Sample request

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

Sample response

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

b. 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=****************

c. 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.

d. 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.

e. 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"
        }
    ]
}

Step 2. Redeeming the offer

After determining the customer's points balance, you can now use it to redeem an offer using the Redemption API. In this example, we redeem an offer for two items (two cheeseburgers and two coffees). The itemId for each item is provided by Shell. The unique referenceId for this redemption (as determined by the partner) is 999999999.

Key request parameters

Sample request

curl --location --request POST 'https://api-test.shell.com/loyalty/v1/consumers/redemption?language_code=de-AT' \
--header 'country-code: AT' \
--header 'user-authorization-token: Bearer ********' \
--header 'client-authorization-token: Bearer ************' \
--header 'channel: partner' \
--header 'consumerUUID: **************' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uuid" : "*****************",
    "referenceId": "ec5e505c-eb8f-434a-9a60-a06f8d8710bb",
    "redemptionReqArray": [
        {
            "itemId": "9999999",
            "points": 3,
            "reasonForRedemption": "Cheeseburger"
        }
    ]
}'

The API responds with an array that contains the status of each of the requested redemption operations, including each item's ID, the quantity of items of that type that points were exchanged for, and the loyalty points redeemed.

Sample response

{
    "redemptionReqArray": [
        {
            "itemId": 9999999,
            "points": 3,
            "reasonForRedemption": "Cheeseburger"
        }
    ],
    "referenceId": "7a1f7955-72d9-4f25-b44a-c3875019f321",
    "transactionDateTime": "2023-01-16T18:47:45+01:00",
    "updatedPointBalance": "89"
}

Step 3: Verifying that the offer was successfully redeemed

Make another request to the Loyalty Points Balance API to verify that the offer was redeemed and that the customer's loyalty points balance has been updated. 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

{
    "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"
        }
    ]
}