Quick Start Guide for Managing Catalogue for a Customer

This guide shows you how to manage the catalogue for a customer, which consists of the following APIs:

1. View Catalogue
2. Redeem an Item from the Catalogue

Note:

• The Customer is the end-user of the API.

• The Partner is the Shell development partner, i.e. the commercial entity using the Shell API as part of their eco-system.

Authentication

The Authentication flow as outlined below.

Sequence Flow Diagram

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.

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_clientID).toString();

Key Request Parameters

Sample Request

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

Sample Response

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

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 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.customer.shell.com/?market=<country-code>&partner=true&clientId=<client-id>&redirect=<redirect-url>

The query parameters you must supply are:

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://<redirect-url>?accessCode=****************

3. Access User Details

You can get the user's unique ID (UUID) and authorization token from the /api/v2/auth/exchangeAccessCode endpoint. Here, you need to use the access code together with the basic public token.

Key Request Parameters

Sample Request

curl --location --request POST 'https://test.id.customer.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-TH",
        "country": "TH"
    },
    "accessToken": "**********",
    "refreshToken": "**********"
    "loyalty": {
        "cardId": null,
        "accounts": [
            {
                "card": [
                    {
                        "cardId": "*****************",
                        "cardEnabled": true,
                        "cardType": "DIGITAL"
                    }
                ]
            }
        ]
    }
}

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 customerUUID in later steps.
• accessToken: This is referred to as the user-authorization-token in later steps. Note, this is valid for 55 mins.

• refreshToken: A refreshToken is available for the user-authorization-token. Refer to Step 3 for details. refreshToken has the expiry time of 30 days. In the response above, the field refreshToken is used to get new accessToken via the endpoint:

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

* **loyalty**: This is the loyalty card linked to a customer's account, which includes card ID.

### **4. Get an Access Token**

Obtain an API gateway access token by making a **POST** request to the [Shell Authentication OAuth](https://developer.shell.com/api-catalog/v1.0.0/shell-authentication) endpoint

#### Key request parameters

| Element  | Value   |
|---|---|
|Method| `POST` |
|Endpoint| `/oauth/token` |
|Headers| _Content-Type_: `application/x-www-form-urlencoded` | 
|data-url-encode|`client_id=*******************` |
|data-url-encode|`client_secret=***********`|
|data-url-encode|`grant_type=client_credentials`|
<br>

#### Sample request

```curl
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 (15 mins).

5. 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.customer.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
}

Note:

Make a note of the following value in the response:

accessToken: This is referred to as the in previous steps. Note, this is valid for 55 mins.

6. Regenerate Access Code Post Its Expiration

After the Access Code expires, you can regenerate the Access Code from /api/v2/auth/accessCode endpoint. Use the accessToken (obtained in Step 3) above as Bearer in the Authorization header.

Note:

You must have the required credentials to call this API as this uses the endpoint that is related to SSO Backend. 

The URLs for SSO Backend API for UAT and Production environment are as below:

    UAT - https://test.id.consumer.shell.com
    Production - https://id.consumer.shell.com

Key Request Parameters

Sample Request

curl --location --request GET 'https://test.id.customer.shell.com/api/v2/auth/accessCode' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer **************' \
--header 'x-sso-market: en-TH'

Sample Response

{
    "accessCode": "**************",
    "expiresIn": 30
}

7. View Catalogue API

You can use this API to view the catalogue for a customer.

Key Request Parameters

Sample Request

curl --location 'https://api-test.shell.com/loyalty/v1/consumers/catalogue?language_code=en-TH&page=3' \
--header 'country-code: TH' \
--header 'user-authorization-token: Bearer clo8f2jqe02cd1wmograssg7y' \
--header 'client-authorization-token: Bearer PIa0OtlsaANx2se9kFC0XC0PNUwu' \
--header 'language: th' \
--header 'x-correlation-id: 8483a8c3-e2c7-4849-835f-8ed27e5be276' \
--header 'application: PARTNER' \
--header 'channel: PARTNER' \
--header 'consumer-id: ab3373b6-30e7-4dde-968f-43bd5734d427'

Sample Response

{
    "catalogueItems": [
        {
            "catalogueId": "51",
            "catalogueItemId": "10935",
            "productCode": "8851959222010",
            "productName": "Shell voucher 250 PTS/ 25 TBH",
            "productDescription": "Shell voucher 250 PTS/ 25 TBH",
            "displayProductDescriptionHTML": "<p>Shell voucher 250 PTS/ 25 TBH</p>",
            "imageUrl": "",
            "deliveryMode": "ONSITE",
            "points": "250",
            "cash": "0",
            "available": true,
            "stock": "-1",
            "purchasable": true,
            "partnerCode": null,
            "partnerName": null
        },
        {
            "catalogueId": "108",
            "catalogueItemId": "10696",
            "productCode": "5015",
            "productName": "Ferrari Cap",
            "productDescription": "Ferrari Cap - Order on our webpage and pick up on nearest Shell petrol station!",
            "displayProductDescriptionHTML": "<p>Ferrari Cap - Order on our webpage and pick up on nearest Shell petrol station!</p>",
            "imageUrl": "https://dynamo-cdn-uat.azureedge.net/media_5e6c4011913acc1500db5a2a",
            "deliveryMode": "ONSITE",
            "points": "50",
            "cash": "0",
            "available": true,
            "stock": "-1",
            "purchasable": true,
            "partnerCode": null,
            "partnerName": null
        },
        {
            "catalogueId": "108",
            "catalogueItemId": "8696",
            "productCode": "10",
            "productName": "SHELL Fuel Discount Voucher value 100 THB",
            "productDescription": "SHELL Fuel Discount Voucher value 500 PTS / 100 THB",
            "displayProductDescriptionHTML": "<p>SHELL Fuel Discount Voucher value 500 PTS / 100 THB</p>",
            "imageUrl": "https://dynamo-cdn-uat.azureedge.net/media_5e6c4011913acc1500db5a2a",
            "deliveryMode": "ONSITE",
            "points": "500",
            "cash": "0",
            "available": true,
            "stock": "-1",
            "purchasable": true,
            "partnerCode": null,
            "partnerName": null
        },
        {
            "catalogueId": "108",
            "catalogueItemId": "10566",
            "productCode": "027",
            "productName": "VP 100 PTS / 20 THB",
            "productDescription": "VP 100 PTS / 20 THB",
            "displayProductDescriptionHTML": "<p>VP 100 PTS / 20 THB</p>",
            "imageUrl": "https://dynamo-cdn-uat.azureedge.net/media_5e6c4011913acc1500db5a2a",
            "deliveryMode": "ONSITE",
            "points": "100",
            "cash": "0",
            "available": true,
            "stock": "-1",
            "purchasable": true,
            "partnerCode": null,
            "partnerName": null
        }
    ],
    "totalResults": 4,
    "minPoint": "50",
    "maxPoint": "500"
}

8. Redeem an Item from Catalogue

You can use this API to redeem an item from the catalogue for a customer.

Key Request Parameters

Sample Request

curl --location --request POST 'https://api-test.shell.com/loyalty/v1/consumers/catalogue/redeem?language_code=th-TH' \
--header 'user-authorization-token: Bearer clqxf348b02cg28mvtpualm1j' \
--header 'client-authorization-token: Bearer 0wOLZb0KbXlIGMIzgRBkvb8ErgOI' \
--header 'country-code: TH' \
--header 'channel: Partner' \
--header 'consumer-id: 117643bf-1d1f-44c4-9088-cdd4b00e0acc' \
--header 'Content-Type: application/json' \
--header 'application: Partner' \
--header 'Cookie: PF=ahV4tIvlpmRGSIKdA9UOfq' \
--data-raw '{
  "referenceId": "Testredeem012",
  "orders": [
    {
      "itemId": 10935,
      "productCode": "8851959222010",
      "deliveryMode": "ONSITE",
      "points": 250,
      "cash": 0,
      "quantity": 1,
      "reasonForRedemption": "Line Redemption"
    }
  ]
}'

Sample Response

{
    "balances": [
        {
            "currencyType": "POINT",
            "amounts": [
                {
                    "amount": "54300",
                    "state": "AVAILABLE",
                    "dateTime": "2024-01-03T06:57:45Z",
                    "dateTimestamp": 1704265065000,
                    "cashAmount": null
                },
                {
                    "amount": "5700",
                    "state": "TOTAL_SPENT",
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "TARGET",
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "EXPIRING",
                    "period": 1,
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "EXPIRING",
                    "period": 2,
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "EXPIRING",
                    "period": 3,
                    "cashAmount": null
                }
            ]
        },
        {
            "currencyType": "STAMP_COUNTER",
            "amounts": [
                {
                    "amount": "5",
                    "state": "AVAILABLE",
                    "dateTime": "2023-12-07T08:21:29Z",
                    "dateTimestamp": 1701937289000,
                    "cashAmount": null,
                    "additionalValues": [
                        {
                            "additionalValue": null,
                            "additionalValueType": "ASSIGNABLE_TO"
                        },
                        {
                            "additionalValue": "1",
                            "additionalValueType": "OFFER_TYPE_SEQUENCE"
                        }
                    ]
                },
                {
                    "amount": "10",
                    "state": "TARGET",
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "EXPIRING",
                    "period": 1,
                    "cashAmount": null
                }
            ]
        },
        {
            "currencyType": "MILES",
            "amounts": [
                {
                    "amount": "0",
                    "state": "AVAILABLE",
                    "dateTime": "2024-01-03T06:57:42Z",
                    "dateTimestamp": 1704265062000,
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "TARGET",
                    "cashAmount": null
                },
                {
                    "amount": "0",
                    "state": "RESERVED",
                    "dateTime": "2024-01-03T06:57:42Z",
                    "dateTimestamp": 1704265062000,
                    "cashAmount": null
                }
            ]
        }
    ],
    "referenceId": "Testredeem012"
}