Quick Start Guide for Loyalty Assign Offer API

To use the Loyalty Assign Offer API, you must first use the Loyalty Tokens API to request permission from a Shell GO+ customer to perform the assignment or revocation of an offer and retrieve an access token you can use to authenticate with. The full process is explained.

Authentication

The Loyalty Assign Offer have a specific Authentication flow as outlined below.

Loyalty Assign Offer API

To assign an offer to a customer 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 Assign Offer API. For an illustrated overview of the steps involved - see the sequence diagram below.

Note: the SSO access token is passed in the user-authorization-token and the API gateway access token is passed in the 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

Now to exchange the accessCode for an access token, for example:

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 **************' \
--data-raw '{
  "accessCode": "**************"
}'

Sample response

{
    "uuid": "********************",
    "market": {
        "code": "en-BG",
        "country": "BG"
    },
    "accessToken": "**********",
    "refreshToken": "**********"
}

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. Note, this is valid for 20mins.
• refreshToken: A refreshToken is available for the . Refer to Step 6 for details. In the response above the field refreshToken is used to get new accessToken via the endpoint:

  https://test.id.consumer.shell.com/api/v2/auth/token/refresh.

  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. Assigning an offer to a customer

Now, we have all the necessary user and client authorization tokens in order to proceed and assign a particular offer to the customer. Please note that the Offer ID would be provided by Shell which defines the offer for the customer.

Key request parameters

Sample request

curl --location --request POST 'https://api-test.shell.com/loyalty/v1/consumers/offers?language_code=ph-PH' \
--header 'country-code: PH' \
--header 'user-authorization-token: Bearer {{sso_access_token}}' \
--header 'client-authorization-token: Bearer {{accessToken}}' \
--header 'application: PARTNER' \
--header 'Content-Type: application/json' \
--data-raw '{
"referenceId": "as3df5131fas3f54f92h5dffd",
"consumerUuid": "*************",
"offerId": "95232796812",
"validFrom": "2022-06-22T17:12:55Z",
"validityPeriod": 31,
"validTo": "2021-03-08T17:12:55Z"
}'

Sample response

{
  "offerData": {
    "offerId": 5231933,
    "referenceId": "asdfasdfadsfasdfsdsd",
    "title": "Buy 1 Get 1",
    "description": "Buy one and get one free",
    "validFrom": "2021-03-08T17:12:55Z",
    "validTo": "2021-04-08T17:12:55Z"
  },
  "consumerUUID": "******************"
}

Note: Optional step in order to referesh the user authorization token if in case the partner would like to keep the customer under rolling session.

6. Refresh User Authorization Token

With the refresh token provided when exchanging the accessCode, a new access token (user-authorization token) can be generated.

Key request parameters

Sample request

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

Sample response

{
    "accessToken": "***********",
    "refreshToken": "***********",
    "expiresIn": 3300
}