> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get subscription (V2)

> Use when you need a subscription with related data (line items, prices, plan). Supports expand for detailed payloads without extra round-trips.



## OpenAPI

````yaml /api-reference/openapi.json get /subscriptions/{id}/v2
openapi: 3.0.1
info:
  title: Flexprice API
  description: Flexprice API Service
  contact:
    name: API Support
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1.0'
servers:
  - url: https://us.api.flexprice.io/v1
    description: US Region
  - url: https://api.cloud.flexprice.io/v1
    description: India Region
security: []
paths:
  /subscriptions/{id}/v2:
    get:
      tags:
        - Subscriptions
      summary: Get subscription (V2)
      description: >-
        Use when you need a subscription with related data (line items, prices,
        plan). Supports expand for detailed payloads without extra round-trips.
      operationId: getSubscriptionV2
      parameters:
        - name: id
          in: path
          description: Subscription ID
          required: true
          schema:
            type: string
        - name: expand
          in: query
          description: >-
            Comma-separated list of fields to expand (e.g.,
            'subscription_line_items,prices,plan')
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseV2'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    SubscriptionResponseV2:
      type: object
      properties:
        active_pause_id:
          type: string
          description: |-
            ActivePauseID references the current active pause configuration
            This will be null if no pause is active or scheduled
        billing_anchor:
          type: string
          description: >-
            BillingAnchor is the reference point that aligns future billing
            cycle dates.

            It sets the day of week for week intervals, the day of month for
            month and year intervals,

            and the month of year for year intervals. The timestamp is in UTC
            format.
          format: date-time
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_cycle:
          $ref: '#/components/schemas/types.BillingCycle'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: BillingPeriodCount is the total number units of the billing period.
        cancel_at:
          type: string
          description: CancelAt is the date the subscription will be canceled
          format: date-time
        cancel_at_period_end:
          type: boolean
          description: >-
            CancelAtPeriodEnd is whether the subscription was canceled at the
            end of the current period
        cancelled_at:
          type: string
          description: CanceledAt is the date the subscription was canceled
          format: date-time
        collection_method:
          type: string
          description: CollectionMethod determines how invoices are collected
        commitment_amount:
          type: string
          description: >-
            CommitmentAmount is the minimum amount a customer commits to paying
            for a billing period
        commitment_duration:
          $ref: '#/components/schemas/types.BillingPeriod'
        coupon_associations:
          type: array
          description: >-
            CouponAssociations are included when "coupon_associations" is in
            expand parameter
          items:
            $ref: '#/components/schemas/CouponAssociationResponse'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_grants:
          type: array
          description: >-
            CreditGrants are included when "credit_grants" is in expand
            parameter
          items:
            $ref: '#/components/schemas/CreditGrantResponse'
        currency:
          type: string
          description: >-
            Currency is the currency of the subscription in lowercase 3 digit
            ISO codes
        current_period_end:
          type: string
          description: >-
            CurrentPeriodEnd is the end of the current period that the
            subscription has been invoiced for.

            At the end of this period, a new invoice will be created.
          format: date-time
        current_period_start:
          type: string
          description: >-
            CurrentPeriodStart is the end of the current period that the
            subscription has been invoiced for.

            At the end of this period, a new invoice will be created.
          format: date-time
        customer:
          $ref: '#/components/schemas/CustomerResponse'
        customer_id:
          type: string
          description: CustomerID is the identifier for the customer in our system
        customer_timezone:
          type: string
        enable_true_up:
          type: boolean
        end_date:
          type: string
          description: EndDate is the end date of the subscription
          format: date-time
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the subscription
        gateway_payment_method_id:
          type: string
          description: >-
            GatewayPaymentMethodID is the gateway payment method ID for this
            subscription
        id:
          type: string
          description: ID is the unique identifier for the subscription
        invoicing_customer_id:
          type: string
          description: >-
            InvoicingCustomerID is the customer ID to use for invoicing

            This can differ from the subscription customer (e.g., parent company
            invoicing for child company)
        line_items:
          type: array
          description: >-
            LineItems is expanded only if "subscription_line_items" is in expand
            parameter

            Each line item can optionally include expanded price data
          items:
            $ref: '#/components/schemas/SubscriptionLineItemResponse'
        lookup_key:
          type: string
          description: LookupKey is the key used to lookup the subscription in our system
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        overage_factor:
          type: string
          description: >-
            OverageFactor is a multiplier applied to usage beyond the commitment
            amount
        parent_subscription_id:
          type: string
          description: >-
            ParentSubscriptionID is the parent subscription ID for hierarchy
            (e.g. child subscription under a parent)
        pause_status:
          $ref: '#/components/schemas/types.PauseStatus'
        pauses:
          type: array
          description: Pauses are included when subscription has pause status
          items:
            $ref: '#/components/schemas/subscription.SubscriptionPause'
        payment_behavior:
          type: string
          description: PaymentBehavior determines how subscription payments are handled
        payment_terms:
          $ref: '#/components/schemas/types.PaymentTerms'
        phases:
          type: array
          description: Phases are included when "phases" is in expand parameter
          items:
            $ref: '#/components/schemas/SubscriptionPhaseResponse'
        plan:
          $ref: '#/components/schemas/PlanResponse'
        plan_id:
          type: string
          description: PlanID is the identifier for the plan in our system
        proration_behavior:
          $ref: '#/components/schemas/types.ProrationBehavior'
        start_date:
          type: string
          description: StartDate is the start date of the subscription
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_status:
          $ref: '#/components/schemas/types.SubscriptionStatus'
        subscription_type:
          $ref: '#/components/schemas/types.SubscriptionType'
        tenant_id:
          type: string
        trial_end:
          type: string
          description: TrialEnd is the end date of the trial period
          format: date-time
        trial_start:
          type: string
          description: TrialStart is the start date of the trial period
          format: date-time
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
        version:
          type: integer
          description: Version is used for optimistic locking
    errors.ErrorResponse:
      type: object
      properties:
        code:
          type: string
          enum:
            - not_found
            - already_exists
            - version_conflict
            - validation_error
            - invalid_operation
            - permission_denied
            - http_client_error
            - database_error
            - system_error
            - internal_error
            - service_unavailable
        details:
          type: object
          additionalProperties:
            type: object
        http_status_code:
          type: integer
        message:
          type: string
      x-speakeasy-name-override: ErrorResponse
    types.BillingCadence:
      type: string
      enum:
        - RECURRING
      x-enum-varnames:
        - BILLING_CADENCE_RECURRING
      x-speakeasy-name-override: BillingCadence
    types.BillingCycle:
      type: string
      enum:
        - anniversary
        - calendar
      x-enum-varnames:
        - BillingCycleAnniversary
        - BillingCycleCalendar
      x-speakeasy-name-override: BillingCycle
    types.BillingPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - ONETIME
      x-enum-varnames:
        - BILLING_PERIOD_MONTHLY
        - BILLING_PERIOD_ANNUAL
        - BILLING_PERIOD_WEEKLY
        - BILLING_PERIOD_DAILY
        - BILLING_PERIOD_QUARTER
        - BILLING_PERIOD_HALF_YEAR
        - BILLING_PERIOD_ONETIME
      x-speakeasy-name-override: BillingPeriod
    CouponAssociationResponse:
      type: object
      properties:
        coupon:
          $ref: '#/components/schemas/Coupon'
        coupon_id:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        end_date:
          type: string
          description: Optional
          format: date-time
        environment_id:
          type: string
        id:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        start_date:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
          description: Mandatory
        subscription_line_item_id:
          type: string
          description: Optional
        subscription_phase_id:
          type: string
          description: Optional
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    CreditGrantResponse:
      type: object
      properties:
        cadence:
          $ref: '#/components/schemas/types.CreditGrantCadence'
        conversion_rate:
          type: string
          description: |-
            amount in the currency =  number of credits * conversion_rate
            ex if conversion_rate is 1, then 1 USD = 1 credit
            ex if conversion_rate is 2, then 1 USD = 0.5 credits
            ex if conversion_rate is 0.5, then 1 USD = 2 credits
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_grant_anchor:
          type: string
          format: date-time
        credits:
          type: string
        end_date:
          type: string
          format: date-time
        environment_id:
          type: string
        expiration_duration:
          type: integer
        expiration_duration_unit:
          $ref: '#/components/schemas/types.CreditGrantExpiryDurationUnit'
        expiration_type:
          $ref: '#/components/schemas/types.CreditGrantExpiryType'
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        period:
          $ref: '#/components/schemas/types.CreditGrantPeriod'
        period_count:
          type: integer
        plan_id:
          type: string
        priority:
          type: integer
        scope:
          $ref: '#/components/schemas/types.CreditGrantScope'
        start_date:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
        tenant_id:
          type: string
        topup_conversion_rate:
          type: string
          description: >-
            topup_conversion_rate is the conversion rate for the topup to the
            currency

            ex if topup_conversion_rate is 1, then 1 USD = 1 credit

            ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits

            ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    CustomerResponse:
      type: object
      properties:
        address_city:
          type: string
          description: AddressCity is the city of the customer's address
        address_country:
          type: string
          description: >-
            AddressCountry is the country of the customer's address (ISO 3166-1
            alpha-2)
        address_line1:
          type: string
          description: AddressLine1 is the first line of the customer's address
        address_line2:
          type: string
          description: AddressLine2 is the second line of the customer's address
        address_postal_code:
          type: string
          description: AddressPostalCode is the postal code of the customer's address
        address_state:
          type: string
          description: AddressState is the state of the customer's address
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        email:
          type: string
          description: Email is the email of the customer
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the customer
        external_id:
          type: string
          description: ExternalID is the external identifier for the customer
        id:
          type: string
          description: ID is the unique identifier for the customer
        integrations:
          type: array
          items:
            $ref: '#/components/schemas/EntityIntegrationMappingResponse'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Metadata
        name:
          type: string
          description: Name is the name of the customer
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
      description: Customer response object containing all customer information
    SubscriptionLineItemResponse:
      type: object
      properties:
        addon_association_id:
          type: string
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: from price at create; default 1
        commitment_amount:
          type: string
          description: Commitment fields
        commitment_duration:
          $ref: '#/components/schemas/types.BillingPeriod'
        commitment_overage_factor:
          type: string
        commitment_quantity:
          type: string
        commitment_true_up_enabled:
          type: boolean
        commitment_type:
          $ref: '#/components/schemas/types.CommitmentType'
        commitment_windowed:
          type: boolean
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
        customer_id:
          type: string
        display_name:
          type: string
        end_date:
          type: string
          format: date-time
        entity_id:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.SubscriptionLineItemEntityType'
        environment_id:
          type: string
        id:
          type: string
        invoice_cadence:
          $ref: '#/components/schemas/types.InvoiceCadence'
        metadata:
          type: object
          additionalProperties:
            type: string
        meter_display_name:
          type: string
        meter_id:
          type: string
        plan_display_name:
          type: string
        price:
          $ref: '#/components/schemas/PriceResponse'
        price_id:
          type: string
        price_type:
          $ref: '#/components/schemas/types.PriceType'
        price_unit:
          type: string
        price_unit_id:
          type: string
        quantity:
          type: string
        start_date:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
        subscription_phase_id:
          type: string
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.Metadata:
      type: object
      additionalProperties:
        type: string
      x-speakeasy-name-override: Metadata
    types.PauseStatus:
      type: string
      enum:
        - none
        - active
        - scheduled
        - completed
        - cancelled
      x-enum-varnames:
        - PauseStatusNone
        - PauseStatusActive
        - PauseStatusScheduled
        - PauseStatusCompleted
        - PauseStatusCancelled
      x-speakeasy-name-override: PauseStatus
    subscription.SubscriptionPause:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the pause
        id:
          type: string
          description: ID is the unique identifier for the subscription pause
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        original_period_end:
          type: string
          description: >-
            OriginalPeriodEnd is the end of the billing period when the pause
            was created
          format: date-time
        original_period_start:
          type: string
          description: >-
            OriginalPeriodStart is the start of the billing period when the
            pause was created
          format: date-time
        pause_end:
          type: string
          description: PauseEnd is when the pause will end (null for indefinite)
          format: date-time
        pause_mode:
          $ref: '#/components/schemas/types.PauseMode'
        pause_start:
          type: string
          description: PauseStart is when the pause actually started
          format: date-time
        pause_status:
          $ref: '#/components/schemas/types.PauseStatus'
        reason:
          type: string
          description: Reason is the reason for pausing
        resume_mode:
          $ref: '#/components/schemas/types.ResumeMode'
        resumed_at:
          type: string
          description: ResumedAt is when the pause was actually ended (if manually resumed)
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
          description: SubscriptionID is the identifier for the subscription
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.PaymentTerms:
      type: string
      enum:
        - 15 NET
        - 30 NET
        - 45 NET
        - 60 NET
        - 75 NET
        - 90 NET
      x-enum-varnames:
        - PaymentTerms15Net
        - PaymentTerms30Net
        - PaymentTerms45Net
        - PaymentTerms60Net
        - PaymentTerms75Net
        - PaymentTerms90Net
      x-speakeasy-name-override: PaymentTerms
    SubscriptionPhaseResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        end_date:
          type: string
          description: >-
            EndDate is when the phase ends (nil if phase is still active or
            indefinite)
          format: date-time
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the phase
        id:
          type: string
          description: ID is the unique identifier for the subscription phase
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        start_date:
          type: string
          description: StartDate is when the phase starts
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        subscription_id:
          type: string
          description: SubscriptionID is the identifier for the subscription
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    PlanResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_grants:
          type: array
          items:
            $ref: '#/components/schemas/CreditGrantResponse'
        description:
          type: string
        display_order:
          type: integer
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementResponse'
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        prices:
          type: array
          description: 'TODO: Add inline addons'
          items:
            $ref: '#/components/schemas/PriceResponse'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.ProrationBehavior:
      type: string
      enum:
        - create_prorations
        - none
      x-enum-comments:
        ProrationBehaviorCreateProrations: 'Default: Create credits/charges on invoice'
        ProrationBehaviorNone: Calculate but don't apply (e.g., for previews)
      x-enum-varnames:
        - ProrationBehaviorCreateProrations
        - ProrationBehaviorNone
      x-speakeasy-name-override: ProrationBehavior
    types.Status:
      type: string
      enum:
        - published
        - deleted
        - archived
      x-enum-varnames:
        - StatusPublished
        - StatusDeleted
        - StatusArchived
      x-speakeasy-name-override: Status
    types.SubscriptionStatus:
      type: string
      enum:
        - active
        - paused
        - cancelled
        - incomplete
        - trialing
        - draft
      x-enum-varnames:
        - SubscriptionStatusActive
        - SubscriptionStatusPaused
        - SubscriptionStatusCancelled
        - SubscriptionStatusIncomplete
        - SubscriptionStatusTrialing
        - SubscriptionStatusDraft
      x-speakeasy-name-override: SubscriptionStatus
    types.SubscriptionType:
      type: string
      enum:
        - standalone
        - parent
        - inherited
      x-enum-varnames:
        - SubscriptionTypeStandalone
        - SubscriptionTypeParent
        - SubscriptionTypeInherited
      x-speakeasy-name-override: SubscriptionType
    Coupon:
      type: object
      properties:
        amount_off:
          type: string
        cadence:
          $ref: '#/components/schemas/types.CouponCadence'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
        duration_in_periods:
          type: integer
        environment_id:
          type: string
        id:
          type: string
        max_redemptions:
          type: integer
        metadata:
          type: object
          additionalProperties:
            type: string
        name:
          type: string
        percentage_off:
          type: string
        redeem_after:
          type: string
        redeem_before:
          type: string
        rules:
          type: object
          additionalProperties: true
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        total_redemptions:
          type: integer
        type:
          $ref: '#/components/schemas/types.CouponType'
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.CreditGrantCadence:
      type: string
      enum:
        - ONETIME
        - RECURRING
      x-enum-varnames:
        - CreditGrantCadenceOneTime
        - CreditGrantCadenceRecurring
      x-speakeasy-name-override: CreditGrantCadence
    types.CreditGrantExpiryDurationUnit:
      type: string
      enum:
        - DAY
        - WEEK
        - MONTH
        - YEAR
      x-enum-varnames:
        - CreditGrantExpiryDurationUnitDays
        - CreditGrantExpiryDurationUnitWeeks
        - CreditGrantExpiryDurationUnitMonths
        - CreditGrantExpiryDurationUnitYears
      x-speakeasy-name-override: CreditGrantExpiryDurationUnit
    types.CreditGrantExpiryType:
      type: string
      enum:
        - NEVER
        - DURATION
        - BILLING_CYCLE
      x-enum-varnames:
        - CreditGrantExpiryTypeNever
        - CreditGrantExpiryTypeDuration
        - CreditGrantExpiryTypeBillingCycle
      x-speakeasy-name-override: CreditGrantExpiryType
    types.CreditGrantPeriod:
      type: string
      enum:
        - DAILY
        - WEEKLY
        - MONTHLY
        - ANNUAL
        - QUARTERLY
        - HALF_YEARLY
      x-enum-varnames:
        - CREDIT_GRANT_PERIOD_DAILY
        - CREDIT_GRANT_PERIOD_WEEKLY
        - CREDIT_GRANT_PERIOD_MONTHLY
        - CREDIT_GRANT_PERIOD_ANNUAL
        - CREDIT_GRANT_PERIOD_QUARTER
        - CREDIT_GRANT_PERIOD_HALF_YEARLY
      x-speakeasy-name-override: CreditGrantPeriod
    types.CreditGrantScope:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
      x-enum-varnames:
        - CreditGrantScopePlan
        - CreditGrantScopeSubscription
      x-speakeasy-name-override: CreditGrantScope
    EntityIntegrationMappingResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        entity_id:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.IntegrationEntityType'
        environment_id:
          type: string
        id:
          type: string
        provider_entity_id:
          type: string
        provider_type:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.CommitmentType:
      type: string
      enum:
        - amount
        - quantity
      x-enum-varnames:
        - COMMITMENT_TYPE_AMOUNT
        - COMMITMENT_TYPE_QUANTITY
      x-speakeasy-name-override: CommitmentType
    types.SubscriptionLineItemEntityType:
      type: string
      enum:
        - plan
        - addon
        - subscription
      x-enum-varnames:
        - SubscriptionLineItemEntityTypePlan
        - SubscriptionLineItemEntityTypeAddon
        - SubscriptionLineItemEntityTypeSubscription
      x-speakeasy-name-override: SubscriptionLineItemEntityType
    types.InvoiceCadence:
      type: string
      enum:
        - ARREAR
        - ADVANCE
      x-enum-varnames:
        - InvoiceCadenceArrear
        - InvoiceCadenceAdvance
      x-speakeasy-name-override: InvoiceCadence
    PriceResponse:
      type: object
      properties:
        addon:
          $ref: '#/components/schemas/AddonResponse'
        amount:
          type: string
          description: |-
            Amount stored in main currency units (e.g., dollars, not cents)
            For USD: 12.50 means $12.50
        billing_cadence:
          $ref: '#/components/schemas/types.BillingCadence'
        billing_model:
          $ref: '#/components/schemas/types.BillingModel'
        billing_period:
          $ref: '#/components/schemas/types.BillingPeriod'
        billing_period_count:
          type: integer
          description: BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
        conversion_rate:
          type: string
          description: >-
            ConversionRate is the conversion rate of the price unit to the fiat
            currency
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        currency:
          type: string
          description: Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
        description:
          type: string
          description: Description of the price
        display_amount:
          type: string
          description: |-
            DisplayAmount is the formatted amount with currency symbol
            For USD: $12.50
        display_name:
          type: string
          description: DisplayName is the name of the price
        display_price_unit_amount:
          type: string
          description: DisplayPriceUnitAmount is the formatted amount of the price unit
        end_date:
          type: string
          description: EndDate is the end date of the price
          format: date-time
        entity_id:
          type: string
          description: EntityID holds the value of the "entity_id" field.
        entity_type:
          $ref: '#/components/schemas/types.PriceEntityType'
        environment_id:
          type: string
          description: EnvironmentID is the environment identifier for the price
        group:
          $ref: '#/components/schemas/GroupResponse'
        group_id:
          type: string
          description: GroupID references the group this price belongs to
        id:
          type: string
          description: ID uuid identifier for the price
        invoice_cadence:
          $ref: '#/components/schemas/types.InvoiceCadence'
        lookup_key:
          type: string
          description: LookupKey used for looking up the price in the database
        metadata:
          $ref: '#/components/schemas/price.JSONBMetadata'
        meter:
          $ref: '#/components/schemas/MeterResponse'
        meter_id:
          type: string
          description: MeterID is the id of the meter for usage based pricing
        min_quantity:
          type: string
          description: MinQuantity is the minimum quantity of the price
          nullable: true
        parent_price_id:
          type: string
          description: >-
            ParentPriceID references the root price (always set for price
            lineage tracking)
        plan:
          $ref: '#/components/schemas/PlanResponse'
        price_unit:
          type: string
          description: PriceUnit is the code of the price unit (e.g., 'btc', 'eth')
        price_unit_amount:
          type: string
          description: PriceUnitAmount is the amount of the price unit
        price_unit_id:
          type: string
          description: PriceUnitID is the id of the price unit (for CUSTOM type)
        price_unit_tiers:
          type: array
          description: >-
            PriceUnitTiers are the tiers for the price unit when BillingModel is
            TIERED
          items:
            $ref: '#/components/schemas/price.PriceTier'
        price_unit_type:
          $ref: '#/components/schemas/types.PriceUnitType'
        pricing_unit:
          $ref: '#/components/schemas/PriceUnitResponse'
        start_date:
          type: string
          description: StartDate is the start date of the price
          format: date-time
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        tier_mode:
          $ref: '#/components/schemas/types.BillingTier'
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/price.PriceTier'
        transform_quantity:
          $ref: '#/components/schemas/price.JSONBTransformQuantity'
        trial_period_days:
          type: integer
          description: >-
            TrialPeriodDays is the number of days for the trial period

            Note: This is only applicable for recurring prices
            (BILLING_CADENCE_RECURRING)
        type:
          $ref: '#/components/schemas/types.PriceType'
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.PriceType:
      type: string
      enum:
        - USAGE
        - FIXED
      x-enum-varnames:
        - PRICE_TYPE_USAGE
        - PRICE_TYPE_FIXED
      x-speakeasy-name-override: PriceType
    types.PauseMode:
      type: string
      enum:
        - immediate
        - scheduled
        - period_end
      x-enum-varnames:
        - PauseModeImmediate
        - PauseModeScheduled
        - PauseModePeriodEnd
      x-speakeasy-name-override: PauseMode
    types.ResumeMode:
      type: string
      enum:
        - immediate
        - scheduled
        - auto
      x-enum-varnames:
        - ResumeModeImmediate
        - ResumeModeScheduled
        - ResumeModeAuto
      x-speakeasy-name-override: ResumeMode
    EntitlementResponse:
      type: object
      properties:
        addon:
          $ref: '#/components/schemas/AddonResponse'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        display_order:
          type: integer
        end_date:
          type: string
          format: date-time
        entity_id:
          type: string
        entity_type:
          $ref: '#/components/schemas/types.EntitlementEntityType'
        environment_id:
          type: string
        feature:
          $ref: '#/components/schemas/FeatureResponse'
        feature_id:
          type: string
        feature_type:
          $ref: '#/components/schemas/types.FeatureType'
        id:
          type: string
        is_enabled:
          type: boolean
        is_soft_limit:
          type: boolean
        parent_entitlement_id:
          type: string
        plan:
          $ref: '#/components/schemas/PlanResponse'
        plan_id:
          type: string
          description: 'TODO: Remove this once we have a proper entitlement entity type'
        start_date:
          type: string
          format: date-time
        static_value:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
        usage_limit:
          type: integer
        usage_reset_period:
          $ref: '#/components/schemas/types.EntitlementUsageResetPeriod'
    types.CouponCadence:
      type: string
      enum:
        - once
        - repeated
        - forever
      x-enum-varnames:
        - CouponCadenceOnce
        - CouponCadenceRepeated
        - CouponCadenceForever
      x-speakeasy-name-override: CouponCadence
    types.CouponType:
      type: string
      enum:
        - fixed
        - percentage
      x-enum-varnames:
        - CouponTypeFixed
        - CouponTypePercentage
      x-speakeasy-name-override: CouponType
    types.IntegrationEntityType:
      type: string
      enum:
        - customer
        - plan
        - invoice
        - subscription
        - payment
        - credit_note
        - addon
        - item
        - item_price
        - price
      x-enum-varnames:
        - IntegrationEntityTypeCustomer
        - IntegrationEntityTypePlan
        - IntegrationEntityTypeInvoice
        - IntegrationEntityTypeSubscription
        - IntegrationEntityTypePayment
        - IntegrationEntityTypeCreditNote
        - IntegrationEntityTypeAddon
        - IntegrationEntityTypeItem
        - IntegrationEntityTypeItemPrice
        - IntegrationEntityTypePrice
      x-speakeasy-name-override: IntegrationEntityType
    AddonResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementResponse'
        environment_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties: true
        name:
          type: string
        prices:
          type: array
          description: Optional expanded fields
          items:
            $ref: '#/components/schemas/PriceResponse'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.BillingModel:
      type: string
      enum:
        - FLAT_FEE
        - PACKAGE
        - TIERED
      x-enum-varnames:
        - BILLING_MODEL_FLAT_FEE
        - BILLING_MODEL_PACKAGE
        - BILLING_MODEL_TIERED
      x-speakeasy-name-override: BillingModel
    types.PriceEntityType:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
        - ADDON
        - PRICE
        - COSTSHEET
      x-enum-varnames:
        - PRICE_ENTITY_TYPE_PLAN
        - PRICE_ENTITY_TYPE_SUBSCRIPTION
        - PRICE_ENTITY_TYPE_ADDON
        - PRICE_ENTITY_TYPE_PRICE
        - PRICE_ENTITY_TYPE_COSTSHEET
      x-speakeasy-name-override: PriceEntityType
    GroupResponse:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        entity_ids:
          type: array
          items:
            type: string
        entity_type:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        name:
          type: string
        status:
          type: string
        updated_at:
          type: string
          format: date-time
    price.JSONBMetadata:
      type: object
      additionalProperties:
        type: string
    MeterResponse:
      type: object
      properties:
        aggregation:
          $ref: '#/components/schemas/meter.Aggregation'
        created_at:
          type: string
          example: '2024-03-20T15:04:05Z'
          format: date-time
        event_name:
          type: string
          example: api_request
        filters:
          type: array
          items:
            $ref: '#/components/schemas/meter.Filter'
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: API Usage Meter
        reset_usage:
          $ref: '#/components/schemas/types.ResetUsage'
        status:
          type: string
          example: published
        tenant_id:
          type: string
          example: tenant123
        updated_at:
          type: string
          example: '2024-03-20T15:04:05Z'
          format: date-time
    price.PriceTier:
      type: object
      properties:
        flat_amount:
          type: string
          description: >-
            flat_amount is the flat amount for the given tier (optional)

            Applied on top of unit_amount*quantity. Useful for cases like "2.7$
            + 5c"
        unit_amount:
          type: string
          description: unit_amount is the amount per unit for the given tier
        up_to:
          type: integer
          description: >-
            up_to is the quantity up to which this tier applies. It is null for
            the last tier.

            IMPORTANT: Tier boundaries are INCLUSIVE.

            - If up_to is 1000, then quantity less than or equal to 1000 belongs
            to this tier

            - This behavior is consistent across both VOLUME and SLAB tier modes
    types.PriceUnitType:
      type: string
      enum:
        - FIAT
        - CUSTOM
      x-enum-varnames:
        - PRICE_UNIT_TYPE_FIAT
        - PRICE_UNIT_TYPE_CUSTOM
      x-speakeasy-name-override: PriceUnitType
    PriceUnitResponse:
      type: object
      properties:
        base_currency:
          type: string
        code:
          type: string
        conversion_rate:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        environment_id:
          type: string
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        symbol:
          type: string
        tenant_id:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.BillingTier:
      type: string
      enum:
        - VOLUME
        - SLAB
      x-enum-varnames:
        - BILLING_TIER_VOLUME
        - BILLING_TIER_SLAB
      x-speakeasy-name-override: BillingTier
    price.JSONBTransformQuantity:
      type: object
      properties:
        divide_by:
          type: integer
          description: Divide quantity by this number
        round:
          $ref: '#/components/schemas/types.RoundType'
    types.EntitlementEntityType:
      type: string
      enum:
        - PLAN
        - SUBSCRIPTION
        - ADDON
      x-enum-varnames:
        - ENTITLEMENT_ENTITY_TYPE_PLAN
        - ENTITLEMENT_ENTITY_TYPE_SUBSCRIPTION
        - ENTITLEMENT_ENTITY_TYPE_ADDON
      x-speakeasy-name-override: EntitlementEntityType
    FeatureResponse:
      type: object
      properties:
        alert_settings:
          $ref: '#/components/schemas/types.AlertSettings'
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        description:
          type: string
        environment_id:
          type: string
        group:
          $ref: '#/components/schemas/GroupResponse'
        group_id:
          type: string
        id:
          type: string
        lookup_key:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        meter:
          $ref: '#/components/schemas/MeterResponse'
        meter_id:
          type: string
        name:
          type: string
        reporting_unit:
          $ref: '#/components/schemas/types.ReportingUnit'
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        type:
          $ref: '#/components/schemas/types.FeatureType'
        unit_plural:
          type: string
        unit_singular:
          type: string
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
    types.FeatureType:
      type: string
      enum:
        - metered
        - boolean
        - static
      x-enum-varnames:
        - FeatureTypeMetered
        - FeatureTypeBoolean
        - FeatureTypeStatic
      x-speakeasy-name-override: FeatureType
    types.EntitlementUsageResetPeriod:
      type: string
      enum:
        - MONTHLY
        - ANNUAL
        - WEEKLY
        - DAILY
        - QUARTERLY
        - HALF_YEARLY
        - NEVER
      x-enum-varnames:
        - ENTITLEMENT_USAGE_RESET_PERIOD_MONTHLY
        - ENTITLEMENT_USAGE_RESET_PERIOD_ANNUAL
        - ENTITLEMENT_USAGE_RESET_PERIOD_WEEKLY
        - ENTITLEMENT_USAGE_RESET_PERIOD_DAILY
        - ENTITLEMENT_USAGE_RESET_PERIOD_QUARTER
        - ENTITLEMENT_USAGE_RESET_PERIOD_HALF_YEAR
        - ENTITLEMENT_USAGE_RESET_PERIOD_NEVER
      x-speakeasy-name-override: EntitlementUsageResetPeriod
    meter.Aggregation:
      type: object
      properties:
        bucket_size:
          $ref: '#/components/schemas/types.WindowSize'
        expression:
          type: string
          description: >-
            Expression is an optional CEL expression to compute per-event
            quantity from event.properties.

            When set, it replaces Field-based extraction. Property names are
            used directly (e.g., token * duration * pixel).
        field:
          type: string
          description: >-
            Field is the key in $event.properties on which the aggregation is to
            be applied

            For ex if the aggregation type is sum for API usage, the field could
            be "duration_ms"

            Ignored when Expression is set.
        group_by:
          type: string
          description: >-
            GroupBy is the property name in event.properties to group by before
            aggregating.

            Currently only supported for MAX aggregation with bucket_size.

            When set, aggregation is applied per unique value of this property
            within each bucket,

            then the per-group results are summed to produce the bucket total.
        multiplier:
          type: string
          description: >-
            Multiplier is the multiplier for the aggregation

            For ex if the aggregation type is sum_with_multiplier for API usage,
            the multiplier could be 1000

            to scale up by a factor of 1000. If not provided, it will be null.
        type:
          $ref: '#/components/schemas/types.AggregationType'
    meter.Filter:
      type: object
      properties:
        key:
          type: string
          description: >-
            Key is the key for the filter from $event.properties

            Currently we support only first level keys in the properties and not
            nested keys
        values:
          type: array
          description: >-
            Values are the possible values for the filter to be considered for
            the meter

            For ex "model_name" could have values "o1-mini", "gpt-4o" etc
          items:
            type: string
    types.ResetUsage:
      type: string
      enum:
        - BILLING_PERIOD
        - NEVER
      x-enum-varnames:
        - ResetUsageBillingPeriod
        - ResetUsageNever
      x-speakeasy-name-override: ResetUsage
    types.RoundType:
      type: string
      enum:
        - up
        - down
      x-enum-varnames:
        - ROUND_UP
        - ROUND_DOWN
      x-speakeasy-name-override: RoundType
    types.AlertSettings:
      type: object
      properties:
        alert_enabled:
          type: boolean
        critical:
          $ref: '#/components/schemas/types.AlertThreshold'
        info:
          $ref: '#/components/schemas/types.AlertThreshold'
        warning:
          $ref: '#/components/schemas/types.AlertThreshold'
      x-speakeasy-name-override: AlertSettings
    types.ReportingUnit:
      type: object
      properties:
        conversion_rate:
          type: number
          description: >-
            Multiplier: reporting_unit_value = unit_value * conversion_rate;
            must be > 0
        unit_plural:
          type: string
          description: Display unit label, plural (e.g. "seconds")
        unit_singular:
          type: string
          description: Display unit label, singular (e.g. "second")
      x-speakeasy-name-override: ReportingUnit
    types.WindowSize:
      type: string
      enum:
        - MINUTE
        - 15MIN
        - 30MIN
        - HOUR
        - 3HOUR
        - 6HOUR
        - 12HOUR
        - DAY
        - WEEK
        - MONTH
        - MONTH
      x-enum-varnames:
        - WindowSizeMinute
        - WindowSize15Min
        - WindowSize30Min
        - WindowSizeHour
        - WindowSize3Hour
        - WindowSize6Hour
        - WindowSize12Hour
        - WindowSizeDay
        - WindowSizeWeek
        - WindowSizeMonth
        - DefaultWindowSize
      x-speakeasy-name-override: WindowSize
    types.AggregationType:
      type: string
      enum:
        - COUNT
        - SUM
        - AVG
        - COUNT_UNIQUE
        - LATEST
        - SUM_WITH_MULTIPLIER
        - MAX
        - WEIGHTED_SUM
      x-enum-comments:
        AggregationSumWithMultiplier: Sum with a multiplier - [sum(value) * multiplier]
      x-enum-varnames:
        - AggregationCount
        - AggregationSum
        - AggregationAvg
        - AggregationCountUnique
        - AggregationLatest
        - AggregationSumWithMultiplier
        - AggregationMax
        - AggregationWeightedSum
      x-speakeasy-name-override: AggregationType
    types.AlertThreshold:
      type: object
      properties:
        condition:
          $ref: '#/components/schemas/types.AlertCondition'
        threshold:
          type: number
      x-speakeasy-name-override: AlertThreshold
    types.AlertCondition:
      type: string
      enum:
        - above
        - below
      x-enum-varnames:
        - AlertConditionAbove
        - AlertConditionBelow
      x-speakeasy-name-override: AlertCondition
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key <api-key>**
      name: x-api-key
      in: header

````