openapi: 3.1.0
info:
  title: Shell B2B Mobility Accounts 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: Accounts
  description: Manage loyalty accounts
paths:
  /accounts:
    post:
      operationId: enrollAccount
      summary: Enroll Loyalty Account
      description: Creates a new Shell loyalty account for a customer.
      tags:
      - Accounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountEnrollRequest'
      responses:
        '201':
          description: Account enrolled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyAccount'
  /accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Get Loyalty Account
      description: Returns details for a specific loyalty account.
      tags:
      - Accounts
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Loyalty account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyAccount'
    put:
      operationId: updateAccount
      summary: Update Loyalty Account
      description: Updates details for a specific loyalty account.
      tags:
      - Accounts
      parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdateRequest'
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyAccount'
  /accounts/{accountNumber}:
    get:
      operationId: getAccount
      summary: Get Account
      description: Returns details for a lubricants customer account.
      tags:
      - Accounts
      parameters:
      - name: accountNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LubricantsAccount'
components:
  schemas:
    LubricantsAccount:
      type: object
      properties:
        accountNumber:
          type: string
        companyName:
          type: string
        accountType:
          type: string
        creditLimit:
          type: number
        availableCredit:
          type: number
        currency:
          type: string
        paymentTerms:
          type: string
        primaryContact:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            phone:
              type: string
    AccountEnrollRequest:
      type: object
      required:
      - firstName
      - lastName
      - email
      properties:
        externalId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        dateOfBirth:
          type: string
          format: date
        countryCode:
          type: string
        marketingConsent:
          type: boolean
    AccountUpdateRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        marketingConsent:
          type: boolean
    LoyaltyAccount:
      type: object
      properties:
        accountId:
          type: string
        externalId:
          type: string
          description: Partner-provided customer identifier
        status:
          type: string
          enum:
          - Active
          - Inactive
          - Suspended
        tier:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        dateOfBirth:
          type: string
          format: date
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  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