openapi: 3.1.0
info:
  title: Shell B2B Mobility Accounts Orders 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: Orders
  description: Manage lubricants orders
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List Orders
      description: Returns a list of lubricants orders for the account.
      tags:
      - Orders
      parameters:
      - name: accountNumber
        in: query
        required: true
        schema:
          type: string
      - name: status
        in: query
        description: Filter by order status
        schema:
          type: string
          enum:
          - Pending
          - Confirmed
          - Processing
          - Shipped
          - Delivered
          - Cancelled
      - name: fromDate
        in: query
        schema:
          type: string
          format: date
      - name: toDate
        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 orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
    post:
      operationId: placeOrder
      summary: Place Order
      description: Places a new lubricants order.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
      responses:
        '201':
          description: Order placed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: Returns details for a specific lubricants order.
      tags:
      - Orders
      parameters:
      - name: orderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        productName:
          type: string
        quantity:
          type: number
          format: float
        unit:
          type: string
          enum:
          - litre
          - kg
          - drum
          - pail
          - can
        unitPrice:
          type: number
          format: float
        totalPrice:
          type: number
          format: float
    OrderListResponse:
      type: object
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        totalCount:
          type: integer
        currentPage:
          type: integer
        pageCount:
          type: integer
    OrderCreateRequest:
      type: object
      required:
      - accountNumber
      - deliveryAddress
      - items
      properties:
        accountNumber:
          type: string
        poNumber:
          type: string
          description: Customer purchase order number
        requestedDeliveryDate:
          type: string
          format: date
        deliveryAddress:
          type: object
        items:
          type: array
          items:
            type: object
            properties:
              productId:
                type: string
              quantity:
                type: number
              unit:
                type: string
        notes:
          type: string
    Order:
      type: object
      properties:
        orderId:
          type: string
        accountNumber:
          type: string
        status:
          type: string
          enum:
          - Pending
          - Confirmed
          - Processing
          - Shipped
          - Delivered
          - Cancelled
        orderDate:
          type: string
          format: date-time
        expectedDeliveryDate:
          type: string
          format: date
        deliveryAddress:
          type: object
          properties:
            name:
              type: string
            street:
              type: string
            city:
              type: string
            postalCode:
              type: string
            country:
              type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        totalAmount:
          type: number
          format: float
        currency:
          type: string
        tracking:
          type: object
  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