openapi: 3.1.0
info:
  title: Orb Alerts Subscriptions 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: Subscriptions
paths:
  /subscriptions:
    get:
      operationId: listSubscriptions
      tags:
      - Subscriptions
      summary: List subscriptions
      parameters:
      - name: customer_id
        in: query
        schema:
          type: string
      - name: external_customer_id
        in: query
        schema:
          type: string
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - ended
          - upcoming
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
    post:
      operationId: createSubscription
      tags:
      - Subscriptions
      summary: Create subscription
      description: Creates a subscription that associates a customer with a plan, starting the accrual of usage charges into a draft invoice.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
      responses:
        '201':
          description: The newly created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
  /subscriptions/{subscription_id}:
    parameters:
    - name: subscription_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: fetchSubscription
      tags:
      - Subscriptions
      summary: Fetch subscription
      responses:
        '200':
          description: The requested subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSubscription
      tags:
      - Subscriptions
      summary: Update subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: The updated subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /subscriptions/{subscription_id}/cancel:
    parameters:
    - name: subscription_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: cancelSubscription
      tags:
      - Subscriptions
      summary: Cancel subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cancel_option
              properties:
                cancel_option:
                  type: string
                  enum:
                  - end_of_subscription_term
                  - immediate
                  - requested_date
                cancellation_date:
                  type: string
                  format: date-time
      responses:
        '200':
          description: The canceled subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
  /subscriptions/{subscription_id}/usage:
    parameters:
    - name: subscription_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: fetchSubscriptionUsage
      tags:
      - Subscriptions
      summary: Fetch subscription usage
      description: Returns usage quantities for the subscription's billable metrics over a window.
      parameters:
      - name: timeframe_start
        in: query
        schema:
          type: string
          format: date-time
      - name: timeframe_end
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: The subscription usage breakdown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionUsage'
  /subscriptions/{subscription_id}/schedule_plan_change:
    parameters:
    - name: subscription_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: schedulePlanChange
      tags:
      - Subscriptions
      summary: Schedule plan change
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - change_option
              properties:
                plan_id:
                  type: string
                external_plan_id:
                  type: string
                change_option:
                  type: string
                  enum:
                  - requested_date
                  - end_of_subscription_term
                  - immediate
                change_date:
                  type: string
                  format: date-time
      responses:
        '200':
          description: The subscription with the scheduled change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
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
    Metric:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - active
          - draft
          - archived
        item:
          $ref: '#/components/schemas/Item'
        metadata:
          type: object
          additionalProperties:
            type: string
    SubscriptionUsage:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              billable_metric:
                $ref: '#/components/schemas/Metric'
              usage:
                type: array
                items:
                  type: object
                  properties:
                    quantity:
                      type: number
                    timeframe_start:
                      type: string
                      format: date-time
                    timeframe_end:
                      type: string
                      format: date-time
    Plan:
      type: object
      properties:
        id:
          type: string
        external_plan_id:
          type: string
          nullable: true
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - active
          - archived
          - draft
        currency:
          type: string
        net_terms:
          type: integer
          nullable: true
        prices:
          type: array
          items:
            $ref: '#/components/schemas/Price'
        created_at:
          type: string
          format: date-time
    SubscriptionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        pagination_metadata:
          $ref: '#/components/schemas/PaginationMetadata'
    Item:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        external_connections:
          type: array
          items:
            type: object
            properties:
              external_connection_name:
                type: string
              external_entity_id:
                type: string
        created_at:
          type: string
          format: date-time
    Subscription:
      type: object
      properties:
        id:
          type: string
        customer:
          $ref: '#/components/schemas/Customer'
        plan:
          $ref: '#/components/schemas/Plan'
        status:
          type: string
          enum:
          - active
          - ended
          - upcoming
        start_date:
          type: string
          format: date-time
        end_date:
          type: string
          format: date-time
          nullable: true
        current_billing_period_start_date:
          type: string
          format: date-time
        current_billing_period_end_date:
          type: string
          format: date-time
        net_terms:
          type: integer
        auto_collection:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
    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
    Price:
      type: object
      properties:
        id:
          type: string
        external_price_id:
          type: string
          nullable: true
        name:
          type: string
        price_type:
          type: string
          enum:
          - usage_price
          - fixed_price
        model_type:
          type: string
          enum:
          - unit
          - tiered
          - package
          - matrix
          - bulk
          - tiered_package
          - grouped_tiered
          - threshold_total_amount
        cadence:
          type: string
          enum:
          - one_time
          - monthly
          - quarterly
          - semi_annual
          - annual
        currency:
          type: string
        item:
          $ref: '#/components/schemas/Item'
        unit_config:
          type: object
          nullable: true
          properties:
            unit_amount:
              type: string
        created_at:
          type: string
          format: date-time
    SubscriptionCreate:
      type: object
      properties:
        customer_id:
          type: string
        external_customer_id:
          type: string
        plan_id:
          type: string
        external_plan_id:
          type: string
        start_date:
          type: string
          format: date-time
        net_terms:
          type: integer
        auto_collection:
          type: boolean
        metadata:
          type: object
          additionalProperties:
            type: string
    Error:
      type: object
      properties:
        status:
          type: integer
        type:
          type: string
        title:
          type: string
        detail:
          type: string
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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>`.'