Shell B2B Mobility Toll Transaction Data API - Quick Start Guide

API Version: 1.0.0 | Authentication: OAuth 2.0 | Status: Production

Overview

The Shell B2B Mobility Toll Transaction Data API is a REST-based API that provides comprehensive access to toll transaction records and related data for Shell mobility customers. This API enables developers to retrieve, filter, and analyze toll transaction data programmatically for account reconciliation, billing verification, expense management, and compliance requirements.

Key Features

Retrieve toll transaction data by account number
Filter transactions by date range (from and to dates)
Search by invoice status and VRN (Vehicle Registration Number)
Advanced sorting capabilities on multiple fields
Pagination support for large datasets
Flexible field filtering to optimize response payload
Comprehensive toll details including entry/exit points
Support for multiple toll networks and operators

Authentication

OAuth 2.0 (Standard Authentication Method)

The Shell Toll Transaction Data API uses OAuth 2.0 Client Credentials flow for secure authentication.

OAuth 2.0 Flow

Step 1: Obtain Access Token

Request an access token from the OAuth token endpoint:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret

Step 2: Use Access Token in API Requests

Authorization: Bearer <access-token>
Content-Type: application/json
RequestId: eb621f45-a543-4d9a-a934-2f223b263c42

Token Management

Token management best practices:

Access tokens have a limited lifetime (typically 15 mins)
Implement token caching to avoid unnecessary token requests
Refresh tokens before expiry to ensure uninterrupted service
Never share your client_secret or embed it in client-side code

Environments

The API is available in two environments:

Environment	Base URL	Purpose
Production	https://api.shell.com/toll-data/v1	Live production environment
Test (UAT)	https://api-test.shell.com/toll-data/v1	Testing and development environment

OAuth Token URLs:

Environment	Token URL
Production	https://api.shell.com/v2/oauth/token
Test (UAT)	https://api-test.shell.com/v2/oauth/token

Tip: Always test your integration in the Test environment before moving to production.

Quick Start

1. Get Your OAuth Credentials

Contact Shell Technical Support
Request OAuth 2.0 credentials (client_id and client_secret)
Review terms of service

2. Obtain Access Token

First, get your OAuth access token:

cURL Example:

curl -X POST https://api-test.shell.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret"

Response:

{
  "access_token": "eyJhbGciOi*******5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 899
}

3. Make Your First API Request

Example: Search Toll Transactions

cURL Example:

curl -X POST https://api-test.shell.com/toll-data/v1/transactions/search \
  -H "Authorization: Bearer eyJhbGci******NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "RequestId: eb621f45-a543-4d9a-a934-2f223b263c42" \
  -d '{
    "Filters": {
        "ColCoCode": 86,
        "PayerNumber": "NL20016398",
        "AccountNumber": "NL20027701",
        "Filter": "All",
        "FromDate": "2026-01-01",
        "ToDate": "2026-01-31"
    },
    "Page": 1,
    "PageSize": 10
}'

Example Response:

{
  "RequestId": "eb621f45-a543-4d9a-a934-2f223b263c42",
  "Status": "SUCCESS",
  "Page": 1,
  "TotalRecords": 150,
  "TotalPages": 15,
  "PageSize": 10,
  "Data": [
    {
      "NetworkDescription": "Societa Autostradali",
      "TollChargerCode": "410|610",
      "DelcoCode": "714",
      "DelcoName": "Shell Fleet Solutions Consorzio",
      "NetworkCode": "TLI",
      "Network": "euroShell Consortio",
      "PurchasedInCountry": "Italy",
      "PurchasedInCountryCode": "IT",
      "CardNumber": "707737*******334272",
      "CardId": 123456789,
      "CardGroupName": "Shell Fleet Solutions Consorzio",
      "VehicleRegistration": "KN 00000",
      "CostCenter": "100",
      "SystemEntryDate": "20260123",
      "SystemEntryTime": "13:14:25",
      "TransactionDate": "20260120",
      "TransactionTime": "10:30:00",
      "PostingDate": "20260123",
      "PostingTime": "00:00:00",
      "PayerNumber": "NL20016398",
      "AccountNumber": "NL20027701",
      "AccountName": "Test Account Name",
      "StartDate": "20260120",
      "StartTime": "06:47:41",
      "EndDate": "20260120",
      "EndTime": "07:30:15",
      "TollGateEntry": "ROMA NORD",
      "TollGateExit": "BRENNERO",
      "DistanceDriven": "71.6",
      "RouteDescription": "ROMA NORD - BRENNERO",
      "TransactionType": "Road tax",
      "ProductCode": "14",
      "ProductDescription": "Road tax",
      "TransactionNetAmount": "127.1",
      "TransactionTax": "0.0",
      "TransactionGrossAmount": "127.1",
      "TransactionCurrencyCode": "EUR",
      "TransactionStatus": "Reporting",
      "InvoiceNumber": "8600397548",
      "InvoiceDate": "20260125",
      "InvoiceStatus": "Invoiced",
      "PaymentMethod": "Post Pay",
      "OBUSerialNumber": "00049000000836932426",
      "EmissionClass": "Euro 6",
      "ContractID": "fb75eb53-46eb-450b-862e-6045002c3fa8",
      "ShellTransactionID": "04176c5c-e7b2-49c8-bcb3-23d07ba583f2",
      "TollOperator": "Toll4Europe",
      "TollDomain": "Toll4Europe",
      "TariffRelevantInformation": "Vehicle Class: 2, Axle Count: 2, Road Category: Motorway",
      "AdditionalTransactionInfo": "Location:1",
      "TCInvoiceNumber": "12343343",
      "TCInvoiceDate": "20260123"
    }
  ]
}

API Endpoints Reference

Toll Transactions

Endpoint	Method	Description
/toll-data/v1/transactions/search	POST	Retrieve toll transaction data with flexible filtering and pagination

Common Use Cases:

Retrieve toll transactions by date range
Filter by invoice status (Invoiced, Uninvoiced, All)
Search by vehicle registration number (VRN)
Filter by card group
Sort transactions by multiple criteria
Select specific fields to optimize response size

Common Use Cases

This section maps common business scenarios to API usage patterns to help you quickly identify how to use the API for your specific needs.

Use Case 1: Daily Toll Transaction Reconciliation

Scenario: You need to reconcile all toll transactions from your fleet on a daily basis for accounting purposes.