openapi: 3.0.3
info:
  title: Octane REST Admin Customer Portal 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: Customer Portal
  description: End-customer portal operations
paths:
  /customer_portal_settings:
    get:
      summary: Get Customer Portal Settings
      description: Get the customer portal configuration.
      operationId: customerPortalSettingsGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Customer portal settings
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Create Customer Portal Settings
      description: Create customer portal configuration.
      operationId: customerPortalSettingsPost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Customer portal settings
          content:
            application/json:
              schema:
                type: object
  /ecp/active_subscription:
    get:
      summary: Get ECP Active Subscription
      description: Get the active subscription from the end-customer portal.
      operationId: ecpActiveSubscriptionGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Active subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveSubscription'
    post:
      summary: Update ECP Active Subscription
      description: Update subscription from the end-customer portal.
      operationId: ecpActiveSubscriptionPost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionArgs'
      responses:
        '200':
          description: Updated subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveSubscription'
  /ecp/active_subscription/add_ons:
    post:
      summary: Add Add-Ons to ECP Subscription
      description: Add add-ons to the active subscription from the end-customer portal.
      operationId: ecpActiveSubscriptionAddOnsPost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated subscription
          content:
            application/json:
              schema:
                type: object
  /ecp/contact_info:
    get:
      summary: Get ECP Contact Info
      description: Get contact information from the end-customer portal.
      operationId: ecpContactInfoGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Contact info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactInfo'
    put:
      summary: Update ECP Contact Info
      description: Update contact information from the end-customer portal.
      operationId: ecpContactInfoPut
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInfoInputArgs'
      responses:
        '200':
          description: Updated contact info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactInfo'
  /ecp/credit/available_balance:
    get:
      summary: Get ECP Credit Balance
      description: Get available credit balance from the end-customer portal.
      operationId: ecpCreditAvailableBalanceGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Available credit balance
          content:
            application/json:
              schema:
                type: object
  /ecp/credit_grants:
    get:
      summary: Get ECP Credit Grants
      description: Get credit grants from the end-customer portal.
      operationId: ecpCreditGrantsGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Credit grants
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /ecp/credit/ledger:
    get:
      summary: Get ECP Credit Ledger
      description: Get credit ledger from the end-customer portal.
      operationId: ecpCreditLedgerGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Credit ledger
          content:
            application/json:
              schema:
                type: object
  /ecp/credit/purchase:
    post:
      summary: Purchase Credits (ECP)
      description: Purchase additional credits from the end-customer portal.
      operationId: ecpCreditPurchasePost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Purchase result
          content:
            application/json:
              schema:
                type: object
  /ecp/credit_top_off_plan:
    get:
      summary: Get ECP Credit Top-Off Plan
      description: Get credit top-off plan from the end-customer portal.
      operationId: ecpCreditTopOffPlanGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Credit top-off plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTopOffPlan'
  /self_serve_settings:
    get:
      summary: Get Self-Serve Settings
      description: Get self-serve enrollment settings for a vendor.
      operationId: selfServeSettingsGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Self-serve settings
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Create Self-Serve Settings
      description: Create self-serve enrollment settings.
      operationId: selfServeSettingsPost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Self-serve settings
          content:
            application/json:
              schema:
                type: object
    put:
      summary: Update Self-Serve Settings
      description: Update self-serve enrollment settings.
      operationId: selfServeSettingsPut
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated self-serve settings
          content:
            application/json:
              schema:
                type: object
  /self_serve_settings/customization:
    get:
      summary: Get Self-Serve Customization
      description: Get customization settings for self-serve portal.
      operationId: selfServeSettingsCustomizationGet
      tags:
      - Customer Portal
      responses:
        '200':
          description: Customization settings
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Create Self-Serve Customization
      description: Create customization settings for self-serve portal.
      operationId: selfServeSettingsCustomizationPost
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Customization settings
          content:
            application/json:
              schema:
                type: object
    put:
      summary: Update Self-Serve Customization
      description: Update customization settings for self-serve portal.
      operationId: selfServeSettingsCustomizationPut
      tags:
      - Customer Portal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated customization settings
          content:
            application/json:
              schema:
                type: object
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.
    ContactInfo:
      type: object
      properties:
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        zipcode:
          type: string
        url:
          type: string
          format: uri
        logo_url:
          type: string
          format: uri
        email:
          type: string
          format: email
        secondary_emails:
          type: array
          items:
            type: string
        phone:
          type: string
        legal_name:
          type: string
        vat_id:
          type: string
    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.
    ContactInfoInputArgs:
      type: object
      properties:
        address_line_1:
          type: string
        address_line_2:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        zipcode:
          type: string
        url:
          type: string
          format: uri
        logo_url:
          type: string
          format: uri
        email:
          type: string
          format: email
        secondary_emails:
          type: array
          items:
            type: string
        phone:
          type: string
        legal_name:
          type: string
        vat_id:
          type: string
    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
    CreditTopOffPlan:
      type: object
      properties:
        customer_name:
          type: string
        threshold:
          type: number
          description: Credit balance threshold that triggers a top-off.
        top_off_amount:
          type: number
          description: Amount of credits to add when threshold is reached.
        enabled:
          type: boolean
    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.