openapi: 3.1.0
info:
  title: Shell B2B Mobility Accounts Cards 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: api-maintainers@shell.com
  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
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
components:
  schemas:
    CardListResponse:
      type: object
      properties:
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
        totalCount:
          type: integer
        currentPage:
          type: integer
        pageCount:
          type: integer
    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'
    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
    CardLimit:
      type: object
      properties:
        type:
          type: string
        value:
          type: number
        period:
          type: string
        currency:
          type: string
  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