Select your language

Machine-translated (Beta)

B2B Mobility Customer Data 3.0.5

This API allows querying customer account details and card groups. It allows the fetching of account details, card delivery addresses, international and national pricelists and cardtypes.

Get status change, maintenance and version updates about this API.

B2B Mobility Customer Data Quickstart

Introduction

The B2B Mobility Customer Data API is a RESTful service that enables you to query and manage customer account details, card groups, and related configurations within the Shell Cards Platform. This API provides flexible search capabilities, supports pagination, and allows you to retrieve account information, card delivery addresses, price lists, and card types. It also supports operations for creating and updating card groups, as well as moving cards between groups.

Benefit Description
Comprehensive Account Management Access detailed customer account information including billing, card summaries, and status
Card Group Operations Create, update, and terminate card groups with flexible card movement capabilities
Price List Access Retrieve national and international price lists with customer-specific discounts
Flexible Search Query data with multiple search criteria and pagination support

Authentication

This API supports both Basic Authentication and OAuth 2.0. OAuth 2.0 is the recommended authentication method for enhanced security.

Migration Note

The API now supports OAuth 2.0 authentication. If you are currently using Basic Authentication, we recommend migrating to OAuth 2.0 for improved security. The Base URL has been updated, and all endpoints are now versioned under the /v1 path. Please refer to the OAuth 2.0 Migration Support for detailed migration guidance.

Authorization flow

  1. Request Client ID and Secret

Contact Shell API Team in order to request access to OAuth authentication. The Shell API team will provide a Client ID and Secret.

  1. Request Bearer token

Once you get the credentials, make a request to the Shell Authentication API's OAuth token endpoint with your credentials.

Example request:

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

You'll receive a Bearer token in the response:

{
   "access_token": "**************",
   "expires_in": "899",
   "token_type": "Bearer"
}

Note: The bearer token expiration time is provided in seconds.

  1. Authorize API requests

When calling Shell APIs, include the following in the header of the request.

Authorization: Bearer access_token

Base URLs

Environment URL
Test https://api-test.shell.com/test
Production https://api.shell.com

Core Integration

1. Get Logged-In User Details

Description: This endpoint retrieves the user data of the logged-in user, including accessible payers, accounts, and roles. This operation should be called after successful authentication to obtain the PayerId needed for subsequent API calls.

Path: POST /user-management/v1/loggedinuser

Sample Request
curl --location 'https://api-test.shell.com/test/user-management/v1/loggedinuser' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "IncludePayerGroup": false,
    "IncludeEIDDetails": false,
    "RequestedAPIName": "v1/Card/OrderCard"
  }
}'
Request Parameters
Parameter Type Required Description
RequestId string Yes Mandatory UUID (RFC 4122) for request tracking
IncludePayerGroup boolean No Include payer group information when true (default: false)
IncludeEIDDetails boolean No Include Electronic Invoice Data when true (default: false)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "UserName": "John123",
      "DisplayName": "John A.",
      "HasAPIAccess": true,
      "Payers": [
        {
          "IsDefault": true,
          "ColcoId": 1,
          "ColcoCode": 86,
          "PayerId": 1234,
          "PayerNumber": "GB000000123",
          "PayerName": "MATTHEW ALGIE & COMPANY LIMITED"
        }
      ]
    }
  ]
}
Response Fields
Field Type Description
UserName string Logged in user identifier
DisplayName string Name of the logged in user
HasAPIAccess boolean True if user has access to the requested API
PayerId integer Payer Id for use in subsequent requests
PayerNumber string Payer Number for use in subsequent requests

2. Query Customer Accounts

Description: This endpoint allows querying customer account details from the Shell Cards Platform with flexible search criteria and pagination support. Use the PayerId obtained from the previous step.

Path: POST /customer-management/v1/accounts

Sample Request
curl --location 'https://api-test.shell.com/test/customer-management/v1/accounts' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE",
    "IncludeCardSummary": true
  },
  "Page": 1,
  "PageSize": 50
}'
Request Parameters
Parameter Type Required Description
ColCoCode integer Yes Collecting Company Code (Shell Code)
PayerNumber string Yes Payer Number of the customer
Status string No Account status filter (ACTIVE, BLOCKED, CANCELLED, etc.)
IncludeCardSummary boolean No Include card summary details (default: true)
Page integer No Page number (default: 1)
PageSize integer No Records per page (default: 50)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "AccountId": 1,
      "AccountNumber": "GB000000124",
      "AccountFullName": "Acme Corporation",
      "Status": "Active",
      "CurrencyCode": "EUR",
      "TotalCards": 1000,
      "TotalActiveCards": 500
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}
Response Fields
Field Type Description
AccountId integer Account identifier
AccountNumber string Account number
AccountFullName string Full name of the account
Status string Current account status
CurrencyCode string ISO currency code
TotalCards integer Total number of cards under the account
TotalActiveCards integer Number of active cards

3. Query Card Groups

Description: This endpoint retrieves card group details from the Shell Cards Platform with flexible search criteria and pagination. Card groups help organize cards within an account.

Path: POST /customer-management/v1/cardgroups

Sample Request
curl --location 'https://api-test.shell.com/test/customer-management/v1/cardgroups' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Filters": {
    "ColCoCode": 86,
    "PayerNumber": "GB000000123",
    "Status": "ACTIVE"
  },
  "Page": 1,
  "PageSize": 50
}'
Request Parameters
Parameter Type Required Description
ColCoCode integer Yes Collecting Company Code
PayerNumber string Yes Payer Number of the customer
Status string Yes Card group status (ACTIVE, TERMINATED, ALL)
CardGroupName string No Filter by card group name (min 2 characters)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "CardGroupId": 40000,
      "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
      "Status": "ACTIVE",
      "PrintOnCard": true,
      "CardTypeId": 1234,
      "TotalCards": 1234,
      "ActiveCards": 999
    }
  ],
  "Page": 1,
  "TotalRecords": 100,
  "TotalPages": 2,
  "PageSize": 50
}
Response Fields
Field Type Description
CardGroupId integer Card group identifier
CardGroupName string Name of the card group
Status string Status of the card group
TotalCards integer Total number of cards in the group
ActiveCards integer Number of active cards in the group

4. Create Card Group

Description: This endpoint creates a new card group in the Shell Cards Platform and optionally moves up to 500 cards into the newly created group. Move card requests are queued after validation.

Path: POST /customer-management/v1/createcardgroup

Sample Request
curl --location 'https://api-test.shell.com/test/customer-management/v1/createcardgroup' \
--header 'RequestId: 2b0cbe11-f109-4c43-9201-49af0370df1c' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "ColCoCode": 86,
  "PayerNumber": "GB000000123",
  "AccountNumber": "GB000000124",
  "CardGroupName": "006240 FIRE BRIGHT SOLUTIONS",
  "PrintOnCard": true,
  "Cards": [
    {
      "AccountNumber": "GB99215176",
      "PAN": "7002051006629890645"
    }
  ]
}'
Request Parameters
Parameter Type Required Description
ColCoCode integer Yes Collecting Company Code
PayerNumber string Yes Payer Number of the customer
AccountNumber string Yes Account Number of the customer
CardGroupName string Yes Name of the new card group (1-40 characters)
PrintOnCard boolean Yes Whether to emboss card group name on cards
Cards array No List of cards to move (max 500)
Sample Response
{
  "RequestId": "2b0cbe11-f109-4c43-9201-49af0370df1c",
  "Status": "SUCCESS",
  "Data": [
    {
      "MainReference": 1234,
      "NewCardGroupReference": 5672,
      "SuccessfulRequests": [
        {
          "PAN": "7002051123456789145",
          "Reference": 12345
        }
      ],
      "ErrorCards": []
    }
  ]
}
Response Fields
Field Type Description
MainReference integer Reference number for tracking the overall request
NewCardGroupReference integer Reference number for the card group creation
SuccessfulRequests array List of successfully queued card move requests
ErrorCards array List of cards that failed validation

Error Handling

The API uses standard HTTP status codes. In case of an error, additional details will be provided in the response body.

Error Code Description Solution
E0001 Validation Error Check the request parameters for missing or invalid values
E0003 Unauthorized Verify credentials and ensure user has access to the operation
E0005 Resource Not Found Confirm the requested resource exists and is accessible
9015 Duplicate Card Group Name Use a unique card group name for the customer

About us

The Shell Developer Portal supports partners in onboarding to Shell APIs and turning ideas into production-ready solutions.

 

Shell logo

Contact

Get in touch

Login to your account

Ask AI Assistant about Shell APIs and API Products