openapi: 3.1.0
info:
  title: Orb Alerts Invoices API
  description: Orb is a usage-based billing and metering platform. The REST API ingests timestamped usage events, models customers, plans, prices, items, and billable metrics, manages subscriptions, and automates invoicing, credit ledgers, coupons, alerts, and webhooks. All endpoints are served over HTTPS at https://api.withorb.com/v1 and authenticated with a Bearer API key.
  termsOfService: https://www.withorb.com/legal/terms-of-service
  contact:
    name: Orb Support
    url: https://www.withorb.com
    email: team@withorb.com
  version: '1.0'
servers:
- url: https://api.withorb.com/v1
  description: Orb production API
security:
- bearerAuth: []
tags:
- name: Invoices
paths:
  /invoices:
    get:
      operationId: listInvoices
      tags:
      - Invoices
      summary: List invoices
      parameters:
      - name: customer_id
        in: query
        schema:
          type: string
      - name: subscription_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - draft
          - issued
          - paid
          - synced
          - void
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of invoices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceList'
    post:
      operationId: createInvoice
      tags:
      - Invoices
      summary: Create a one-off invoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreate'
      responses:
        '201':
          description: The newly created one-off invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{invoice_id}:
    parameters:
    - name: invoice_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: fetchInvoice
      tags:
      - Invoices
      summary: Fetch invoice
      responses:
        '200':
          description: The requested invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices/{invoice_id}/issue:
    parameters:
    - name: invoice_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: issueInvoice
      tags:
      - Invoices
      summary: Issue invoice
      description: Transitions a draft invoice to issued, triggering payment collection.
      responses:
        '200':
          description: The issued invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
  /invoices/{invoice_id}/void:
    parameters:
    - name: invoice_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: voidInvoice
      tags:
      - Invoices
      summary: Void invoice
      responses:
        '200':
          description: The voided invoice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: The number of items to return per page (default 20, max 100).
      schema:
        type: integer
        default: 20
        maximum: 100
    Cursor:
      name: cursor
      in: query
      description: An opaque cursor for the next page of results.
      schema:
        type: string
  schemas:
    PaginationMetadata:
      type: object
      properties:
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
    InvoiceCreate:
      type: object
      required:
      - currency
      - invoice_date
      - line_items
      properties:
        customer_id:
          type: string
        external_customer_id:
          type: string
        currency:
          type: string
        invoice_date:
          type: string
          format: date-time
        net_terms:
          type: integer
        memo:
          type: string
        line_items:
          type: array
          items:
            type: object
            required:
            - name
            - quantity
            - unit_config
            properties:
              name:
                type: string
              quantity:
                type: number
              item_id:
                type: string
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              unit_config:
                type: object
                properties:
                  unit_amount:
                    type: string
    Customer:
      type: object
      properties:
        id:
          type: string
        external_customer_id:
          type: string
          nullable: true
        name:
          type: string
        email:
          type: string
          format: email
        currency:
          type: string
          example: USD
        timezone:
          type: string
          example: America/New_York
        payment_provider:
          type: string
          nullable: true
          enum:
          - stripe_charge
          - stripe_invoice
          - quickbooks
          - bill.com
          - netsuite
        balance:
          type: string
          description: The customer's account balance in the smallest currency unit.
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
    InvoiceLineItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        quantity:
          type: number
        amount:
          type: string
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        status:
          type: integer
        type:
          type: string
        title:
          type: string
        detail:
          type: string
    InvoiceList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
        pagination_metadata:
          $ref: '#/components/schemas/PaginationMetadata'
    Invoice:
      type: object
      properties:
        id:
          type: string
        invoice_number:
          type: string
        status:
          type: string
          enum:
          - draft
          - issued
          - paid
          - synced
          - void
        customer:
          $ref: '#/components/schemas/Customer'
        subscription:
          type: object
          nullable: true
          properties:
            id:
              type: string
        currency:
          type: string
        total:
          type: string
        subtotal:
          type: string
        amount_due:
          type: string
        due_date:
          type: string
          format: date-time
          nullable: true
        issued_at:
          type: string
          format: date-time
          nullable: true
        hosted_invoice_url:
          type: string
          format: uri
          nullable: true
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
        created_at:
          type: string
          format: date-time
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate with an Orb API key sent as a Bearer token in the Authorization header: `Authorization: Bearer <ORB_API_KEY>`.'