Quick Start Guide for Retrieving Transactions of a Customer
This guide shows the detailed steps to fetch and retrieve the list of transactions of a customer. A customer can enjoy the benefits of Shell Loyalty Services by registering and signing into Shell Login / Registration Portal.
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
| Environment | Base URL |
|---|---|
| Test | https://api-test.shell.com |
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
| Element | Value |
|---|---|
| Method | POST |
| Endpoint | /api/v2/auth/token |
| Headers | _Content-type_: application/json |
| Body | data-urlencode: Your Client ID, encrypted using the SHA256 algorithm. |
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_name>"
}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>/&scopes=write:assign_offers write:activate_offers read:view_loyalty_details
The query parameters you must supply are:
| Query Parameter | Description |
|---|---|
| market | A combination of language code (lower case) and country code (upper case), separated by a hyphen. For example: en-TH. |
| clientId | unique Shell client ID of the partner. Same key is passed previously to get the public token. |
| partner | true (default for any customer). |
| redirect | Your application redirect URL. |
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
| Element | Value |
|---|---|
| Method | POST |
| Endpoint | /api/v2/auth/exchangeAccessCode |
| Headers | Content-Type: application/json |
| Authorization: Basic |
|
| Body | accessCode : The access code you retrieved in step 2 |
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 6 for details. 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
| Element | Value |
|---|---|
| Method | POST |
| Endpoint | /api/v2/auth/token/refresh |
| Headers | Content-Type: application/json |
| Authorization: Basic |
|
| Body | refreshToken : The refresh token that was provided in the response from Step 3 |
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
6. Get a List of Transactions of a Customer
You can use this API to fetch and retrieve the list of transactions of a customer.
Key Request Parameters
| Element | Value |
|---|---|
| Method | GET |
| Endpoint | /loyalty/v1/consumers/transactionsL |
| Query Parameters | language_code: This is a concatenation of language in lower case as per ISO 639-1 , “-” and country code as per ISO 3166-1 alpha-2. For example: en-GB. |
| Headers | Content-Type: application/json |
| user-authorization-token: The accessToken you retrieved from the /auth/exchangeAccessCode endpoint prefixed by Bearer. | |
| client-authorization_token: The accessToken you retrieved from the /oauth/token endpoint, prefixed by Bearer. | |
| application: A constant value 'PARTNER'. | |
| consumerUUID: This is the customer's unique ID. The value of uuid is retrieved from /auth/exchangeAccessCode endpoint. |
Sample Request
curl --location 'https://api-test.shell.com/loyalty/v1/consumers/transactionsL?language_code=pl-PL' \
--header 'country-code: PL' \
--header 'user-authorization-token: Bearer clk6qsn0z000o1rpactbsyu93' \
--header 'client-authorization-token: Bearer fmVQg8M2F2NGeI3RE18G8R8luKTk' \
--header 'language: en' \
--header 'x-correlation-id: 8483a8c3-e2c7-4849-835f-8ed27e5be276' \
--header 'application: PARTNER' \
--header 'channel: PARTNER' \
--header 'consumerUUID: bd68f27f-80f7-440a-b096-f65155161345'Sample Response
{
"totalResults": 1,
"nextPage": "",
"previousPage": "",
"totalSaved": 0,
"transactions": [
{
"transactionDateTime": 1688987241000,
"transactionDateTimeStamp": "2023-07-10T11:07:21.000Z",
"siteData": {
"countryCode": "PL",
"siteId": "00000000",
"name": "Biuro Obsługi Klienta",
"postcode": null,
"city": null,
"address": null
},
"loyalty": {
"loyaltyCard": "70043708289502916"
},
"transactionId": "b0d065f63bcde251313ae1f22e4718c0",
"partnerCode": null,
"partnerName": null,
"referenceId": null,
"totalAmount": 0,
"totalDiscountAmount": 0,
"totalDiscountedFullAmount": 0,
"balances": [
{
"currencyType": "POINT",
"amounts": [
{
"amount": 200,
"state": "AVAILABLE"
},
{
"amount": 200,
"state": "CHANGE"
},
{
"amount": 200,
"state": "EARNED"
},
{
"amount": 0,
"state": "REDEEMED"
}
]
}
],
"currencyCode": "PLN",
"saleItems": [
{
"detailType": "CENTRAL_AWARD",
"productData": {
"id": "1452",
"name": "Offer points",
"productType": "CC",
"reasonForRedemption": null
},
"amount": null,
"originalAmount": null,
"discountAmount": 0,
"vatRate": null,
"quantity": 0,
"points": null,
"offerInfos": [],
"vouchers": null,
"voucherItems": null,
"offerLang": {
"id": "16281",
"title": "200 Points - PLGCCTest",
"description": "200 Points - PLGCCTest",
"customText": "200 Points - PLGCCTest"
},
"commentText": null
}
],
"redeemedItems": [],
"transactionVouchers": [],
"receiptNumber": null,
"pointsToCash": null,
"companyId": null,
"isPartnerRedemption": false,
"currencyData": null
}
]
}4.1 How Pages Work When Returning Transactions?
When you invoke the API to return the list of transactions of a customer, you can see the parameter totalResults returned in the API response. This parameter displays the total number of transaction records of the customer.
For Example:
If you have "totalResults" returned as 100 in the response, then based on how many records you would like to display per page, you can define "page" and "pageSize" parameters.
page and pageSize need to be passed as query parameters in the endpoint URL (Example: https://api-test.shell.com/loyalty/v1/consumers/transactionsL?page=1&pageSize=20)
In the API request, if you set “page” to 1 and “pageSize” to 20, then 20 records are displayed in the page.
In the next API request, if you set to “page” to 2 and retain the “pageSize” value to 20, then it displays the next 20 records (from 21st to 40th record).
Note that in the API request where you set “page” to 2, and if you reduce “pageSize” to 5 from previous value of 20, then it displays the 6th to 10th record as it recalculates. Hence it is important to retain the same “pageSize” value to display sequence of records in the response.
