Provides access to the Shell network of fuel and EV charging sites for B2B mobility customers. Enables applications to query site locations, available fuel types, EV charging availability, amenities, and opening hours across the Shell station network.
openapi: 3.1.0
info:
title: Shell B2B Mobility API
description: >-
The Shell B2B Mobility API enables fleet operators and business customers
to manage fuel cards, retrieve transaction data, manage invoices, query fuel
station sites, and control card limits and restrictions. Supports B2B fleet
management workflows across the Shell global network.
version: '2.1.0'
contact:
name: Shell Developer Portal
url: https://developer.shell.com/
email: [email protected]
license:
name: Shell API Terms
url: https://www.shell.com/terms-and-conditions
x-date: '2026-05-02'
servers:
- url: https://api.shell.com/mobility/v2
description: Shell B2B Mobility API
security:
- OAuth2: []
tags:
- name: Cards
description: Manage B2B fuel cards
- name: Transactions
description: Retrieve fuel card transaction data
- name: Invoices
description: Manage fuel card invoices
- name: Sites
description: Query Shell fuel and EV charging sites
- name: Customers
description: Manage B2B customer data
- name: Limits
description: Manage card spending limits and restrictions
paths:
/cards:
get:
operationId: listCards
summary: List Cards
description: Returns a list of fuel cards associated with the B2B account.
tags:
- Cards
parameters:
- name: colCoCode
in: query
description: Country code for the collecting company
required: true
schema:
type: integer
- name: payerNumber
in: query
description: Payer account number
schema:
type: string
- name: accountNumber
in: query
description: Customer account number
schema:
type: string
- name: cardStatus
in: query
description: Filter cards by status
schema:
type: string
enum: [Active, Blocked, Cancelled, Expired, Pending]
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
maximum: 100
responses:
'200':
description: A list of fuel cards
content:
application/json:
schema:
$ref: '#/components/schemas/CardListResponse'
post:
operationId: orderCard
summary: Order Card
description: Places an order for a new fuel card.
tags:
- Cards
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardOrderRequest'
responses:
'200':
description: Card order placed
content:
application/json:
schema:
$ref: '#/components/schemas/CardOrderResponse'
/cards/{cardId}:
get:
operationId: getCard
summary: Get Card
description: Returns details for a specific fuel card.
tags:
- Cards
parameters:
- name: cardId
in: path
required: true
schema:
type: string
- name: colCoCode
in: query
required: true
schema:
type: integer
responses:
'200':
description: Card details
content:
application/json:
schema:
$ref: '#/components/schemas/Card'
/cards/{cardId}/cancel:
post:
operationId: cancelCard
summary: Cancel Card
description: Cancels a fuel card.
tags:
- Cards
parameters:
- name: cardId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
colCoCode:
type: integer
reason:
type: string
responses:
'200':
description: Card cancelled
content:
application/json:
schema:
type: object
/cards/{cardId}/block:
post:
operationId: blockCard
summary: Block Card
description: Blocks or unblocks a fuel card.
tags:
- Cards
parameters:
- name: cardId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
colCoCode:
type: integer
action:
type: string
enum: [Block, Unblock]
reason:
type: string
responses:
'200':
description: Card block status updated
content:
application/json:
schema:
type: object
/transactions:
get:
operationId: listTransactions
summary: List Transactions
description: Returns a list of fuel card transactions for the specified date range.
tags:
- Transactions
parameters:
- name: colCoCode
in: query
required: true
schema:
type: integer
- name: payerNumber
in: query
schema:
type: string
- name: accountNumber
in: query
schema:
type: string
- name: cardPAN
in: query
description: Card PAN to filter transactions
schema:
type: string
- name: fromDate
in: query
description: Start date for transaction search (YYYY-MM-DD)
required: true
schema:
type: string
format: date
- name: toDate
in: query
description: End date for transaction search (YYYY-MM-DD)
required: true
schema:
type: string
format: date
- name: productCode
in: query
description: Filter by fuel product code
schema:
type: string
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
maximum: 500
responses:
'200':
description: A list of transactions
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionListResponse'
/transactions/{transactionId}:
get:
operationId: getTransaction
summary: Get Transaction
description: Returns details for a specific fuel card transaction.
tags:
- Transactions
parameters:
- name: transactionId
in: path
required: true
schema:
type: string
- name: colCoCode
in: query
required: true
schema:
type: integer
responses:
'200':
description: Transaction details
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
/invoices:
get:
operationId: listInvoices
summary: List Invoices
description: Returns a list of invoices for the B2B account.
tags:
- Invoices
parameters:
- name: colCoCode
in: query
required: true
schema:
type: integer
- name: payerNumber
in: query
schema:
type: string
- name: accountNumber
in: query
schema:
type: string
- name: invoiceDateFrom
in: query
schema:
type: string
format: date
- name: invoiceDateTo
in: query
schema:
type: string
format: date
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: A list of invoices
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceListResponse'
/invoices/{invoiceNumber}:
get:
operationId: getInvoice
summary: Get Invoice
description: Returns a specific invoice.
tags:
- Invoices
parameters:
- name: invoiceNumber
in: path
required: true
schema:
type: string
- name: colCoCode
in: query
required: true
schema:
type: integer
responses:
'200':
description: Invoice details
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
/sites:
get:
operationId: listSites
summary: List Sites
description: Returns a list of Shell fuel and EV charging sites matching the specified criteria.
tags:
- Sites
parameters:
- name: latitude
in: query
description: Latitude coordinate for location-based search
schema:
type: number
format: float
- name: longitude
in: query
description: Longitude coordinate for location-based search
schema:
type: number
format: float
- name: radius
in: query
description: Search radius in kilometers
schema:
type: number
format: float
- name: countryCode
in: query
description: ISO 2-letter country code
schema:
type: string
- name: fuelType
in: query
description: Filter by fuel type
schema:
type: string
- name: evCharging
in: query
description: Filter for EV charging available sites
schema:
type: boolean
- name: page
in: query
schema:
type: integer
- name: pageSize
in: query
schema:
type: integer
responses:
'200':
description: A list of Shell sites
content:
application/json:
schema:
$ref: '#/components/schemas/SiteListResponse'
/sites/{siteId}:
get:
operationId: getSite
summary: Get Site
description: Returns details for a specific Shell site.
tags:
- Sites
parameters:
- name: siteId
in: path
required: true
schema:
type: string
responses:
'200':
description: Site details
content:
application/json:
schema:
$ref: '#/components/schemas/Site'
/limits:
post:
operationId: updateCardLimits
summary: Update Card Limits
description: Updates spending limits and restrictions for fuel cards.
tags:
- Limits
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardLimitUpdateRequest'
responses:
'200':
description: Card limits updated
content:
application/json:
schema:
type: object
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.shell.com/oauth/token
scopes:
mobility.cards: Manage fuel cards
mobility.transactions: Access transaction data
mobility.invoices: Access invoice data
mobility.sites: Query site data
schemas:
Card:
type: object
properties:
cardId:
type: string
cardPAN:
type: string
description: Primary Account Number
maskedPAN:
type: string
cardStatus:
type: string
enum: [Active, Blocked, Cancelled, Expired, Pending]
expiryDate:
type: string
accountNumber:
type: string
payerNumber:
type: string
driverName:
type: string
vehicleRegistration:
type: string
cardType:
type: string
colCoCode:
type: integer
limits:
type: array
items:
$ref: '#/components/schemas/CardLimit'
CardLimit:
type: object
properties:
type:
type: string
value:
type: number
period:
type: string
currency:
type: string
CardListResponse:
type: object
properties:
cards:
type: array
items:
$ref: '#/components/schemas/Card'
totalCount:
type: integer
currentPage:
type: integer
pageCount:
type: integer
CardOrderRequest:
type: object
required:
- colCoCode
- accountNumber
properties:
colCoCode:
type: integer
payerNumber:
type: string
accountNumber:
type: string
driverName:
type: string
vehicleRegistration:
type: string
cardType:
type: string
embossText:
type: string
CardOrderResponse:
type: object
properties:
orderId:
type: string
status:
type: string
estimatedDeliveryDate:
type: string
format: date
Transaction:
type: object
properties:
transactionId:
type: string
date:
type: string
format: date-time
cardPAN:
type: string
maskedPAN:
type: string
siteCode:
type: string
siteName:
type: string
siteCountry:
type: string
productCode:
type: string
productName:
type: string
quantity:
type: number
format: float
quantityUnit:
type: string
unitPrice:
type: number
format: float
amount:
type: number
format: float
currency:
type: string
mileage:
type: number
driverName:
type: string
vehicleRegistration:
type: string
accountNumber:
type: string
payerNumber:
type: string
TransactionListResponse:
type: object
properties:
transactions:
type: array
items:
$ref: '#/components/schemas/Transaction'
totalCount:
type: integer
currentPage:
type: integer
pageCount:
type: integer
Invoice:
type: object
properties:
invoiceNumber:
type: string
invoiceDate:
type: string
format: date
dueDate:
type: string
format: date
payerNumber:
type: string
accountNumber:
type: string
totalAmount:
type: number
format: float
currency:
type: string
status:
type: string
enum: [Open, Paid, Overdue, Cancelled]
lineItems:
type: array
items:
type: object
InvoiceListResponse:
type: object
properties:
invoices:
type: array
items:
$ref: '#/components/schemas/Invoice'
totalCount:
type: integer
currentPage:
type: integer
pageCount:
type: integer
Site:
type: object
properties:
siteId:
type: string
siteName:
type: string
siteCode:
type: string
address:
type: object
properties:
street:
type: string
city:
type: string
postalCode:
type: string
country:
type: string
location:
type: object
properties:
latitude:
type: number
format: float
longitude:
type: number
format: float
fuelTypes:
type: array
items:
type: string
evCharging:
type: boolean
evChargingPoints:
type: integer
amenities:
type: array
items:
type: string
openingHours:
type: object
SiteListResponse:
type: object
properties:
sites:
type: array
items:
$ref: '#/components/schemas/Site'
totalCount:
type: integer
currentPage:
type: integer
pageCount:
type: integer
CardLimitUpdateRequest:
type: object
required:
- colCoCode
- cardId
properties:
colCoCode:
type: integer
payerNumber:
type: string
accountNumber:
type: string
cardId:
type: string
limits:
type: array
items:
$ref: '#/components/schemas/CardLimit'