openapi: 3.0.3
info:
  title: Octane REST Admin Subscriptions API
  description: REST API for managing meters, customers, pricing plans, subscriptions, measurements, and real-time usage data for usage-based billing workflows. Octane enables infrastructure and SaaS companies to implement flexible pay-as-you-go billing similar to Snowflake and AWS.
  version: 1.0.0
  contact:
    name: Octane Support
    url: https://www.getoctane.io
servers:
- url: https://api.getoctane.io
  description: Octane Production API
security:
- BearerApiKeyAuth: []
tags:
- name: Subscriptions
  description: Manage customer subscriptions to price plans
paths:
  /customers/{customer_name}/active_subscription:
    get:
      summary: Get Customer Active Subscription
      description: Get the active subscription for a customer.
      operationId: customersCustomerNameActiveSubscriptionGet
      tags:
      - Subscriptions
      parameters:
      - name: customer_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveSubscription'
    post:
      summary: Create Customer Subscription
      description: Subscribe a customer to a price plan.
      operationId: customersCustomerNameActiveSubscriptionPost
      tags:
      - Subscriptions
      parameters:
      - name: customer_name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionArgs'
      responses:
        '200':
          description: Active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveSubscription'
components:
  schemas:
    BillingCycleDate:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Start of the current billing cycle.
        end:
          type: string
          format: date-time
          description: End of the current billing cycle.
    CreateSubscriptionArgs:
      type: object
      properties:
        price_plan_name:
          type: string
          description: Name of the price plan to subscribe to.
        price_plan_uuid:
          type: string
          description: UUID of the price plan to subscribe to.
        price_plan_tag:
          type: string
          description: Tag of the price plan version to use.
        effective_at:
          type: string
          format: date-time
          description: When the subscription should take effect.
        align_to_calendar:
          type: boolean
          description: Align billing cycle to calendar period.
        coupon_override_name:
          type: string
          description: Coupon to apply to the subscription.
        discount_override:
          $ref: '#/components/schemas/DiscountInputArgs'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/DiscountInputArgs'
        features_override:
          type: array
          items:
            type: object
        add_ons:
          type: array
          items:
            type: object
        limits_override:
          type: array
          items:
            type: object
        trial_override:
          $ref: '#/components/schemas/TrialInputArgs'
        credit_plan:
          type: object
    Trial:
      type: object
      properties:
        time_length:
          type: integer
          description: Duration of the trial period.
        time_unit_name:
          type: string
          description: Unit of time for the trial (e.g., "day", "month").
        credit:
          type: number
          description: Trial credit amount.
    TrialInputArgs:
      type: object
      properties:
        time_length:
          type: integer
          description: Duration of the trial period.
        time_unit_name:
          type: string
          description: Unit of time for the trial.
        credit:
          type: number
          description: Trial credit amount.
    PriceTier:
      type: object
      description: A price tier within a tiered pricing scheme.
      properties:
        price:
          type: number
          description: Price per unit at this tier.
        cap:
          type: number
          description: Upper bound of usage for this tier (null = unlimited).
    Limit:
      type: object
      required:
      - feature
      - limit
      properties:
        feature:
          $ref: '#/components/schemas/Feature'
        limit:
          type: number
          description: Numeric limit for the feature.
    ActiveSubscription:
      type: object
      required:
      - uuid
      - customer_name
      - price_plan_name
      - price_plan_uuid
      properties:
        uuid:
          type: string
          description: Unique identifier for the subscription.
        customer_name:
          type: string
          description: Name of the subscribed customer.
        price_plan_name:
          type: string
          description: Name of the price plan.
        price_plan_uuid:
          type: string
          description: UUID of the price plan.
        price_plan:
          $ref: '#/components/schemas/PricePlan'
        effective_at:
          type: string
          format: date-time
          description: When the subscription became effective.
        expired_at:
          type: string
          format: date-time
          nullable: true
          description: When the subscription expires.
        align_to_calendar:
          type: boolean
          description: Whether the billing cycle aligns to the calendar.
        base_price_override:
          type: number
          description: Override for the plan's base price.
        current_billing_cycle:
          $ref: '#/components/schemas/BillingCycleDate'
        total_fixed_price:
          type: number
        discounted_fixed_price:
          type: number
        discounts:
          type: array
          items:
            type: object
        add_ons:
          type: array
          items:
            type: object
        features_override:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
        limits_override:
          type: array
          items:
            $ref: '#/components/schemas/Limit'
        trial_override:
          $ref: '#/components/schemas/Trial'
        credit_plan:
          type: object
    PricePlan:
      type: object
      required:
      - name
      - period
      - metered_components
      properties:
        name:
          type: string
          description: Unique name identifier for the price plan.
        display_name:
          type: string
          description: Human-readable display name.
        description:
          type: string
          description: Description of the price plan.
        external_uuid:
          type: string
          description: External UUID reference.
        base_price:
          type: number
          description: Fixed base price for the plan period.
        base_price_frequency:
          type: string
          description: How often the base price is charged.
        base_price_description:
          type: string
          description: Description of what the base price covers.
        period:
          type: string
          enum:
          - monthly
          - quarterly
          - annual
          description: Billing period for this plan.
        minimum_charge:
          type: number
          description: Minimum charge amount for the period.
        minimum_charge_frequency:
          type: string
          description: Frequency of minimum charge.
        metered_components:
          type: array
          items:
            $ref: '#/components/schemas/MeteredComponent'
          description: Usage-based metered pricing components.
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
          description: Features included in this plan.
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/AddOn'
          description: Available add-ons for this plan.
        limits:
          type: array
          items:
            $ref: '#/components/schemas/Limit'
          description: Usage limits for features.
        tags:
          type: array
          items:
            type: object
          description: Version tags for this plan.
        trial:
          $ref: '#/components/schemas/Trial'
        created_at:
          type: string
          format: date-time
    MeteredComponent:
      type: object
      required:
      - meter_name
      - meter_display_name
      - price_scheme
      - label_limits
      properties:
        meter_name:
          type: string
          description: Name of the meter this component is based on.
        meter_display_name:
          type: string
          description: Display name of the meter.
        display_name:
          type: string
          description: Display name for this component on invoices.
        external_uuid:
          type: string
          description: External UUID reference.
        price_scheme:
          $ref: '#/components/schemas/PriceScheme'
        limit:
          type: number
          description: Usage limit for this component.
        label_limits:
          type: array
          items:
            type: object
          description: Per-label usage limits.
        minimum_charge:
          type: number
        minimum_charge_frequency:
          type: string
        watermark:
          type: number
          description: High-watermark for pricing.
    Feature:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Unique name of the feature.
        display_name:
          type: string
          description: Human-readable display name.
        description:
          type: string
          description: Description of the feature.
    DiscountInputArgs:
      type: object
      properties:
        discount_type:
          type: string
          enum:
          - PERCENT
          - AMOUNT
          description: Type of discount.
        amount:
          type: number
          description: Discount amount or percentage.
        scope:
          type: string
          enum:
          - SUBSCRIPTION
          - COMPONENT
          - ADD_ON
          description: What the discount applies to.
        billing_cycle_duration:
          type: integer
          description: How many billing cycles the discount lasts.
        billing_cycle_start_offset:
          type: integer
          description: Offset from subscription start to begin applying discount.
        metered_component_uuid:
          type: string
          description: UUID of the metered component to discount.
        add_on_name:
          type: string
          description: Name of the add-on to discount.
        labels:
          type: object
          description: Label filters for the discount.
    PriceScheme:
      type: object
      description: Pricing scheme configuration for a metered component.
      properties:
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PriceTier'
        scheme_type:
          type: string
          enum:
          - FLAT
          - TIERED
          - VOLUME
          - PACKAGE
        unit_name:
          type: string
        time_unit_name:
          type: string
    AddOn:
      type: object
      required:
      - feature
      - price
      - price_scheme_type
      - single_use
      - quantity_enabled
      properties:
        feature:
          $ref: '#/components/schemas/Feature'
        price:
          type: number
          description: Price of the add-on.
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PriceTier'
        price_scheme_type:
          type: string
          description: Pricing scheme type for the add-on.
        single_use:
          type: boolean
          description: Whether the add-on can only be purchased once.
        quantity_enabled:
          type: boolean
          description: Whether quantity selection is enabled.
        immediately_charge:
          type: boolean
          description: Whether to charge immediately on purchase.
        limit:
          type: number
          description: Maximum quantity allowed.
        price_frequency:
          type: string
          description: How often the add-on price recurs.
        charge_frequency:
          type: string
          description: How often to charge for the add-on.
  securitySchemes:
    BearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header.