api/v3/openapi.yaml

openapi: 3.0.0
info:
  title: OpenMeter and Konnect Metering & Billing API
  version: 0.0.1
  description: |-
    OpenMeter is a cloud native usage metering and billing service. The API allows
    you to ingest events, query meter usage, and manage resources.
servers:
  - url: http://localhost:{port}/api/v3
    description: Local
    variables:
      port:
        default: '8888'
  - url: https://{region}.api.konghq.com/v3
    description: Production region
    variables:
      region:
        default: us
        enum:
          - us
          - eu
          - au
          - me
          - in
  - url: https://openmeter.cloud/api/v3
    description: OpenMeter Cloud
    variables: {}
tags:
  - name: OpenMeter Governance
    description: Governance evaluation of customers to check their feature access.
  - name: OpenMeter Defaults
    description: Organization-level default configuration.
  - name: OpenMeter Product Catalog
    description: Product catalog manages plans, add-ons, and their associations for subscription-based billing.
  - name: OpenMeter LLM Cost
    description: LLM cost database providing normalized pricing data for language models across providers. Prices are synced from multiple external sources and auto-confirmed when they agree.
  - name: OpenMeter Features
    description: Features represent product capabilities backed by meters, with optional per-unit cost configuration.
  - name: OpenMeter Tax
    description: Tax codes are used to calculate taxes for customers.
  - name: OpenMeter Currencies
    description: Currencies and cost bases for customers.
  - name: OpenMeter Billing Settings
    description: Billing settings manages the billing profiles and invoices for customers.
  - name: OpenMeter Apps
    description: Apps enable you to extend and customize billing and usage workflows by integrating with external systems and services. Apps can automate and enhance your billing ecosystem by supporting capabilities such as synchronizing usage data with third-party platforms, calculating taxes, generating and delivering invoices, handling payment collection, and other billing-related tasks.
  - name: OpenMeter Entitlements
    description: Entitlements are used to control access to features for customers.
  - name: OpenMeter Subscriptions
    description: Subscriptions are used to track usage of your product or service. Subscriptions can be individuals or organizations that can subscribe to plans and have access to features.
  - name: OpenMeter Customers
    description: Customers are used to track usage of your product or service. Customers can be individuals or organizations that can subscribe to plans and have access to features.
  - name: Metering Events
    description: Metering events are used to track usage of your product or service. Events are processed asynchronously by the meters, so they may not be immediately available for querying.
  - name: Meters
    description: Meters specify how to aggregate events for billing and analytics purposes. Meters can be configured with multiple aggregation methods and groupings. Multiple meters can be created for the same event type, enabling flexible metering scenarios.
paths:
  /openmeter/addons:
    get:
      operationId: list-addons
      summary: List add-ons
      description: List all add-ons.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort add-ons returned in the response. Supported sort attributes are:

            - `id`
            - `key`
            - `name`
            - `created_at` (default)
            - `updated_at`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: Filter add-ons returned in the response.
          schema:
            $ref: '#/components/schemas/ListAddonsParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddonPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    post:
      operationId: create-addon
      summary: Create add-on
      description: Create a new add-on.
      responses:
        '201':
          description: Addon created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Addon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddonRequest'
      x-unstable: true
  /openmeter/addons/{addonId}:
    put:
      operationId: update-addon
      summary: Update add-on
      description: Update an add-on by id.
      parameters:
        - name: addonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Addon upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Addon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertAddonRequest'
      x-unstable: true
    get:
      operationId: get-addon
      summary: Get add-on
      description: Get add-on by id.
      parameters:
        - name: addonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Addon response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Addon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    delete:
      operationId: delete-addon
      summary: Soft delete add-on
      description: Soft delete add-on by id.
      parameters:
        - name: addonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/addons/{addonId}/archive:
    post:
      operationId: archive-addon
      summary: Archive add-on version
      description: Archive an add-on version.
      parameters:
        - name: addonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Addon updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Addon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/addons/{addonId}/publish:
    post:
      operationId: publish-addon
      summary: Publish add-on version
      description: Publish an add-on version.
      parameters:
        - name: addonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Addon updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Addon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/app-catalog:
    get:
      operationId: list-app-catalog
      summary: List app catalog
      description: List available apps.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppCatalogItemPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Apps
  /openmeter/app-catalog/install:
    post:
      operationId: install-app
      summary: Install app from the catalog
      description: Install an app from the catalog.
      responses:
        '201':
          description: InstallAppResponse created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInstallAppResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Apps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingInstallAppRequest'
  /openmeter/app-catalog/{appType}:
    get:
      operationId: get-app-catalog-item
      summary: Get app catalog item by type
      description: Get an app catalog item by type.
      parameters:
        - name: appType
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/BillingAppType'
      responses:
        '200':
          description: AppCatalogItem response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAppCatalogItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Apps
  /openmeter/apps:
    get:
      operationId: list-apps
      summary: List apps
      description: List installed apps.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Apps
  /openmeter/apps/{appId}:
    get:
      operationId: get-app
      summary: Get app
      description: Get an installed app.
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: App response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingApp'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Apps
  /openmeter/billing/invoices:
    get:
      operationId: list-invoices
      summary: List billing invoices
      description: |-
        List billing invoices.

        Returns a page of invoices. Gathering invoices are never included. Use `filter`
        to narrow by status, customer, dates, or service period start. Use `sort` to
        control ordering.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort invoices returned in the response. Supported sort attributes:

            - `issued_at`
            - `created_at` (default)
            - `service_period_start`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter invoices returned in the response.

            Examples:

            - `filter[status][oeq]=draft,issued`
            - `filter[customer_id]=01KPDB8K...`
            - `filter[issued_at][gte]=2024-01-01T00:00:00Z`
          schema:
            $ref: '#/components/schemas/ListInvoicesParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/billing/invoices/{invoiceId}:
    get:
      operationId: get-invoice
      summary: Get a billing invoice
      description: |-
        Get a billing invoice by ID.

        Returns the full invoice resource including line items, status details, totals,
        and workflow configuration snapshot.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Invoice response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
    put:
      operationId: update-invoice
      summary: Update a billing invoice
      description: |-
        Update a billing invoice.

        Only the mutable fields of the invoice can be edited: description, labels,
        supplier, customer, workflow settings, and top-level lines. Top-level lines are
        matched by `id`; lines without an `id` are created, and existing lines omitted
        from `lines` are deleted. Detailed (child) lines are always computed and cannot
        be edited directly. Only invoices in draft status can be updated.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Invoice updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvoiceRequest'
      x-private: true
      x-internal: true
      x-unstable: true
    delete:
      operationId: delete-invoice
      summary: Delete a billing invoice
      description: |-
        Delete a billing invoice.

        Only standard invoices in draft status can be deleted. Deleting an invoice will
        also delete all associated line items and workflow configuration.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/billing/invoices/{invoiceId}/advance:
    post:
      operationId: advance-invoice
      summary: Advance billing invoice's next status
      description: |-
        Advance a billing invoice.

        Advances the invoice to the next workflow state. The next state is determined by
        the invoice's current status and workflow configuration. Only invoices in draft
        or issued status can be advanced.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The updated invoice after advancing to the next state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/billing/invoices/{invoiceId}/approve:
    post:
      operationId: approve-invoice
      summary: Send the invoice to the customer
      description: |-
        Approve a billing invoice.

        This call instantly sends the invoice to the customer using the configured
        billing profile app.

        This call is valid in two invoice statuses:

        - draft: the invoice will be sent to the customer, the invoice state becomes
        issued
        - manual_approval_needed: the invoice will be sent to the customer, the invoice
        state becomes issued
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The updated invoice after sending to the customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/billing/invoices/{invoiceId}/retry:
    post:
      operationId: retry-invoice
      summary: Retry advancing the invoice after a failed attempt
      description: |-
        Retry sending a billing invoice.

        Retry advancing the invoice after a failed attempt.

        The action can be called when the invoice's statusDetails' actions field contain
        the "retry" action.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The updated invoice after retrying the action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/billing/invoices/{invoiceId}/snapshot-quantities:
    post:
      operationId: snapshot-quantities-invoice
      summary: Snapshot quantities for usage based line items
      description: |-
        Snapshot quantities for usage-based line items.

        This call will snapshot the quantities for all usage based line items in the
        invoice.

        This call is only valid in draft.waiting_for_collection status, where the
        collection period can be skipped using this action.
      parameters:
        - name: invoiceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: |-
            The updated invoice with the snapshot quantities for usage based line
            items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingInvoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/currencies:
    get:
      operationId: list-currencies
      summary: List currencies
      description: List currencies supported by the billing system.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort currencies returned in the response. Supported sort attributes are:

            - `code` (default)
            - `name`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter currencies returned in the response.

            To filter currencies by type add the following query param: filter[type]=custom
          schema:
            $ref: '#/components/schemas/ListCurrenciesParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Currencies
      x-internal: true
      x-unstable: true
  /openmeter/currencies/custom:
    post:
      operationId: create-custom-currency
      summary: Create custom currency
      description: |-
        Create a custom currency. This operation allows defining your own custom
        currency for billing purposes.
      responses:
        '201':
          description: CurrencyCustom created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCurrencyCustom'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Currencies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCurrencyCustomRequest'
      x-internal: true
      x-unstable: true
  /openmeter/currencies/custom/{currencyId}/cost-bases:
    get:
      operationId: list-cost-bases
      summary: List cost bases
      description: |-
        List cost bases for a currency. For custom currencies, there can be multiple
        cost bases with different `effective_from` dates.
      parameters:
        - name: currencyId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: filter
          in: query
          required: false
          description: |-
            Filter cost bases returned in the response.

            To filter cost bases by fiat currency code add the following query param:
            filter[fiat_code]=USD
          schema:
            $ref: '#/components/schemas/ListCostBasesParamsFilter'
          style: deepObject
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostBasisPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Currencies
      x-internal: true
      x-unstable: true
    post:
      operationId: create-cost-basis
      summary: Create cost basis
      description: Create a cost basis for a currency.
      parameters:
        - name: currencyId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: CostBasis created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCostBasis'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Currencies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCostBasisRequest'
      x-internal: true
      x-unstable: true
  /openmeter/customers:
    post:
      operationId: create-customer
      summary: Create customer
      responses:
        '201':
          description: Customer created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCustomer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
    get:
      operationId: list-customers
      summary: List customers
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort customers returned in the response. Supported sort attributes are:

            - `id`
            - `name` (default)
            - `created_at`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter customers returned in the response.

            To filter customers by key add the following query param: filter[key]=my-db-id
          schema:
            $ref: '#/components/schemas/ListCustomersParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Customers
  /openmeter/customers/{customerId}:
    get:
      operationId: get-customer
      summary: Get customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Customer response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCustomer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
    put:
      operationId: upsert-customer
      summary: Upsert customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Customer upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCustomer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCustomerRequest'
    delete:
      operationId: delete-customer
      summary: Delete customer
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
  /openmeter/customers/{customerId}/billing:
    get:
      operationId: get-customer-billing
      summary: Get customer billing data
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: CustomerBillingData response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCustomerData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
    put:
      operationId: update-customer-billing
      summary: Update customer billing data
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: CustomerBillingData upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCustomerData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCustomerBillingDataRequest'
  /openmeter/customers/{customerId}/billing/app-data:
    put:
      operationId: update-customer-billing-app-data
      summary: Update customer billing app data
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: AppCustomerData upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAppCustomerData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertAppCustomerDataRequest'
  /openmeter/customers/{customerId}/billing/stripe/checkout-sessions:
    post:
      operationId: create-customer-stripe-checkout-session
      summary: Create Stripe Checkout Session
      description: |-
        Create a [Stripe Checkout Session](https://docs.stripe.com/payments/checkout)
        for the customer.

        Creates a Checkout Session for collecting payment method information from
        customers. The session operates in "setup" mode, which collects payment details
        without charging the customer immediately. The collected payment method can be
        used for future subscription billing.

        For hosted checkout sessions, redirect customers to the returned URL. For
        embedded sessions, use the client_secret to initialize Stripe.js in your
        application.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: CreateStripeCheckoutSessionResult created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingCustomerStripeCreateCheckoutSessionRequest'
  /openmeter/customers/{customerId}/billing/stripe/portal-sessions:
    post:
      operationId: create-customer-stripe-portal-session
      summary: Create Stripe customer portal session
      description: |-
        Create Stripe Customer Portal Session.

        Useful to redirect the customer to the Stripe Customer Portal to manage their
        payment methods, change their billing address and access their invoice history.
        Only returns URL if the customer billing profile is linked to a stripe app and
        customer.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: CreateStripeCustomerPortalSessionResult created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAppStripeCreateCustomerPortalSessionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingCustomerStripeCreateCustomerPortalSessionRequest'
  /openmeter/customers/{customerId}/charges:
    get:
      operationId: list-customer-charges
      summary: List customer charges
      description: |-
        List customer charges.

        Returns the customer's charges that are represented as either flat fee or
        usage-based charges.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: sort
          in: query
          required: false
          description: |-
            Sort charges returned in the response.

            Supported sort attributes are:

            - `id`
            - `created_at`
            - `service_period.from`
            - `billing_period.from`
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter charges.

            To filter charges by status add the following query param:
            `filter[status][oeq]=created,active`
          schema:
            $ref: '#/components/schemas/ListChargesParamsFilter'
          style: deepObject
        - name: expand
          in: query
          required: false
          description: |-
            Expand full objects for referenced entities.

            Supported values are:

            - `real_time_usage`: Expand the charge's real-time usage.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/BillingChargesExpand'
          style: form
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      x-unstable: true
    post:
      operationId: create-customer-charges
      summary: Create customer charge
      description: Create customer charge.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: Charge created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCharge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChargeRequest'
      x-unstable: true
  /openmeter/customers/{customerId}/credits/adjustments:
    post:
      operationId: create-credit-adjustment
      summary: Create a credit adjustment
      description: |-
        A credit adjustment can be used to make manual adjustments to a customer's
        credit balance.

        Supported use-cases:

        - Usage correction
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: CreditAdjustment created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditAdjustment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreditAdjustmentRequest'
      x-unstable: true
  /openmeter/customers/{customerId}/credits/balance:
    get:
      operationId: get-customer-credit-balance
      summary: Get a customer's credit balance
      description: Get a credit balance.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: timestamp
          in: query
          required: false
          description: |-
            Return the credit balance as of this timestamp.

            Defaults to the current time.
          schema:
            $ref: '#/components/schemas/DateTime'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/GetCreditBalanceParamsFilter'
          style: deepObject
      responses:
        '200':
          description: CreditBalances response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditBalances'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      x-unstable: true
  /openmeter/customers/{customerId}/credits/grants:
    post:
      operationId: create-credit-grant
      summary: Create a new credit grant
      description: |-
        Create a new credit grant. A credit grant represents an allocation of prepaid
        credits to a customer.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: CreditGrant created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreditGrantRequest'
      x-unstable: true
    get:
      operationId: list-credit-grants
      summary: List credit grants
      description: List credit grants.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: filter
          in: query
          required: false
          description: Filter credit grants returned in the response.
          schema:
            $ref: '#/components/schemas/ListCreditGrantsParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditGrantPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      x-unstable: true
  /openmeter/customers/{customerId}/credits/grants/{creditGrantId}:
    get:
      operationId: get-credit-grant
      summary: Get a credit grant
      description: Get a credit grant.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: creditGrantId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: CreditGrant response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      x-unstable: true
  /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external:
    post:
      operationId: update-credit-grant-external-settlement
      summary: Update credit grant external settlement status
      description: |-
        Update the payment settlement status of an externally funded credit grant.

        Use this endpoint to synchronize the payment state of an external payment with
        the system so that revenue recognition and credit availability work as expected.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: creditGrantId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: CreditGrant updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCreditGrantExternalSettlementRequest'
      x-unstable: true
  /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/void:
    post:
      operationId: void-credit-grant
      summary: Void credit grant
      description: |-
        Void a credit grant, forfeiting the remaining unused balance.

        Voiding is a forward-looking, irreversible operation. Credits already consumed
        by usage remain unaffected — only the remaining balance is forfeited. The grant
        reads as `voided` status afterwards. Payment state is not adjusted when
        `payment_adjustment` is `none`, so invoice-backed or externally collected
        payments may still collect the original amount. Only `active` grants can be
        voided; voiding a pending, expired, or fully consumed grant returns a conflict.
        Retrying a successful void is an idempotent success.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: creditGrantId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: CreditGrant updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCreditGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Customers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidCreditGrantRequest'
      x-unstable: true
  /openmeter/customers/{customerId}/credits/transactions:
    get:
      operationId: list-credit-transactions
      summary: List credit transactions
      description: |-
        List credit transactions for a customer.

        Returns an immutable, chronological record of credit movements: funded credits
        and consumed credits. Transactions are returned in reverse chronological order
        by default.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - $ref: '#/components/parameters/CursorPaginationQuery'
        - name: filter
          in: query
          required: false
          description: Filter credit transactions returned in the response.
          schema:
            $ref: '#/components/schemas/ListCreditTransactionsParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Cursor paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTransactionPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Customers
      x-unstable: true
  /openmeter/customers/{customerId}/entitlement-access:
    get:
      operationId: list-customer-entitlement-access
      summary: List customer entitlement access
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: List the customer's active features and their access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerEntitlementAccessResponseData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Entitlements
  /openmeter/defaults/tax-codes:
    get:
      operationId: get-organization-default-tax-codes
      summary: Get organization default tax codes
      responses:
        '200':
          description: OrganizationDefaultTaxCodes response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDefaultTaxCodes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Defaults
      x-unstable: true
    put:
      operationId: update-organization-default-tax-codes
      summary: Update organization default tax codes
      responses:
        '200':
          description: OrganizationDefaultTaxCodes upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDefaultTaxCodes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Defaults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationDefaultTaxCodesRequest'
      x-unstable: true
  /openmeter/events:
    get:
      operationId: list-metering-events
      summary: List metering events
      description: List ingested events.
      parameters:
        - $ref: '#/components/parameters/CursorPaginationQuery'
        - name: filter
          in: query
          required: false
          description: |-
            Filter events returned in the response.

            To filter events by subject add the following query param:
            filter[subject][eq]=customer-1
          schema:
            $ref: '#/components/schemas/ListEventsParamsFilter'
          style: deepObject
        - name: sort
          in: query
          required: false
          description: |-
            Sort events returned in the response. Supported sort attributes are:

            - `time` (default)
            - `ingested_at`
            - `stored_at`

            When omitted, events are sorted by `time desc` (most recent first). When a sort
            field is provided without a suffix, it sorts descending. Append the `asc` suffix
            to sort ascending, or the `desc` suffix to sort descending.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
      responses:
        '200':
          description: Cursor paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestedEventPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - Metering Events
      x-unstable: true
    post:
      operationId: ingest-metering-events
      description: Ingests an event or batch of events following the CloudEvents specification.
      summary: Ingest metering events
      responses:
        '202':
          description: The events have been ingested and are being processed asynchronously.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - Metering Events
      requestBody:
        required: true
        content:
          application/cloudevents+json:
            schema:
              $ref: '#/components/schemas/MeteringEvent'
          application/cloudevents-batch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MeteringEvent'
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/MeteringEvent'
                - type: array
                  items:
                    $ref: '#/components/schemas/MeteringEvent'
  /openmeter/features:
    get:
      operationId: list-features
      summary: List features
      description: List all features.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort features returned in the response. Supported sort attributes are:

            - `key`
            - `name`
            - `created_at` (default)
            - `updated_at`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter features returned in the response.

            To filter features by meter_id add the following query param:
            filter[meter_id][oeq]=<id>
          schema:
            $ref: '#/components/schemas/ListFeatureParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Features
      x-unstable: true
    post:
      operationId: create-feature
      summary: Create feature
      description: Create a feature.
      responses:
        '201':
          description: Feature created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Features
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureRequest'
      x-unstable: true
  /openmeter/features/{featureId}:
    get:
      operationId: get-feature
      summary: Get feature
      description: Get a feature by id.
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Feature response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Features
      x-unstable: true
    patch:
      operationId: update-feature
      summary: Update feature
      description: Update a feature by id. Currently only the unit_cost field can be updated.
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Feature updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Features
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureRequest'
      x-unstable: true
    delete:
      operationId: delete-feature
      summary: Delete feature
      description: Delete a feature by id.
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Features
      x-unstable: true
  /openmeter/features/{featureId}/cost/query:
    post:
      operationId: query-feature-cost
      summary: Query feature cost
      description: Query the cost of a feature.
      parameters:
        - name: featureId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCostQueryResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Features
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeterQueryRequest'
      x-unstable: true
  /openmeter/governance/query:
    post:
      operationId: query-governance-access
      summary: Query governance access
      description: |-
        Query feature access for a list of customers.

        The endpoint resolves each provided identifier to a customer and returns the
        access status for the requested features, plus optional credit balance
        availability.

        _Designed to be called on a fixed refresh interval and the query response is
        intended to be cached._
      parameters:
        - $ref: '#/components/parameters/CursorPaginationQuery'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GovernanceQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Governance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GovernanceQueryRequest'
      x-private: true
      x-internal: true
      x-unstable: true
  /openmeter/llm-cost/overrides:
    get:
      operationId: list-llm-cost-overrides
      summary: List LLM cost overrides
      description: List per-namespace price overrides.
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/ListLLMCostPricesParamsFilter'
          style: deepObject
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter LLM Cost
      x-unstable: true
    post:
      operationId: create-llm-cost-override
      summary: Create LLM cost override
      description: Create a per-namespace price override.
      responses:
        '201':
          description: Price created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMCostPrice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter LLM Cost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMCostOverrideCreate'
      x-unstable: true
  /openmeter/llm-cost/overrides/{priceId}:
    delete:
      operationId: delete-llm-cost-override
      summary: Delete LLM cost override
      description: Delete a per-namespace price override.
      parameters:
        - name: priceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter LLM Cost
      x-unstable: true
  /openmeter/llm-cost/prices:
    get:
      operationId: list-llm-cost-prices
      summary: List LLM cost prices
      description: List global LLM cost prices. Returns prices with overrides applied if any.
      parameters:
        - name: filter
          in: query
          required: false
          description: Filter prices.
          schema:
            $ref: '#/components/schemas/ListLLMCostPricesParamsFilter'
          style: deepObject
        - name: sort
          in: query
          required: false
          description: |-
            Sort prices returned in the response. Supported sort attributes are:

            - `id`
            - `provider.id`
            - `model.id` (default)
            - `effective_from`
            - `effective_to`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter LLM Cost
      x-unstable: true
  /openmeter/llm-cost/prices/{priceId}:
    get:
      operationId: get-llm-cost-price
      summary: Get LLM cost price
      description: |-
        Get a specific LLM cost price by ID. Returns the price with overrides applied if
        any.
      parameters:
        - name: priceId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMCostPrice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter LLM Cost
      x-unstable: true
  /openmeter/meters:
    post:
      operationId: create-meter
      summary: Create meter
      description: Create a meter.
      responses:
        '201':
          description: Meter created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - Meters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMeterRequest'
    get:
      operationId: list-meters
      summary: List meters
      description: List meters.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort meters returned in the response. Supported sort attributes are:

            - `key`
            - `name`
            - `aggregation`
            - `created_at` (default)
            - `updated_at`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: |-
            Filter meters returned in the response.

            To filter meters by key add the following query param: filter[key]=my-meter-key
          schema:
            $ref: '#/components/schemas/ListMetersParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeterPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - Meters
  /openmeter/meters/{meterId}:
    get:
      operationId: get-meter
      summary: Get meter
      description: Get a meter by ID.
      parameters:
        - name: meterId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Meter response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Meters
    put:
      operationId: update-meter
      summary: Update meter
      description: Update a meter.
      parameters:
        - name: meterId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Meter updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Meters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMeterRequest'
      x-unstable: true
    delete:
      operationId: delete-meter
      summary: Delete meter
      description: Delete a meter.
      parameters:
        - name: meterId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Meters
  /openmeter/meters/{meterId}/query:
    post:
      operationId: query-meter
      parameters:
        - name: meterId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      description: |-
        Query a meter for usage.

        Set `Accept: application/json` (the default) to get a structured JSON response.
        Set `Accept: text/csv` to download the same data as a CSV file suitable for
        spreadsheets. The CSV columns, in order, are:

        `from, to, [subject,] [customer_id, customer_key, customer_name,] <dimensions...>, value`

        The `subject` column is emitted only when `subject` is in the query's
        `group_by_dimensions`. The three `customer_*` columns are emitted together only
        when `customer_id` is in the query's `group_by_dimensions`.
      summary: Query meter
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeterQueryResult'
            text/csv:
              schema:
                type: string
              examples:
                Grouped by customer and dimensions:
                  summary: Grouped by customer and dimensions
                  value: |-
                    from,to,customer_id,customer_key,customer_name,model,type,value
                    2023-01-01T00:00:00Z,2023-01-01T00:01:00Z,01G65Z755AFWAKHE12NY0CQ9FH,acme-inc,Acme Inc.,gpt-4-turbo,input,12
                    2023-01-01T00:01:00Z,2023-01-01T00:02:00Z,01G65Z755AFWAKHE12NY0CQ9FH,acme-inc,Acme Inc.,gpt-4-turbo,input,20
                    2023-01-01T00:02:00Z,2023-01-01T00:03:00Z,01G65Z755B3YZ1KRA9W8V7PS2D,globex,Globex Corp,gpt-4-turbo,output,4
                No group-by dimensions:
                  summary: No group-by dimensions
                  value: |-
                    from,to,value
                    2023-01-01T00:00:00Z,2023-01-01T00:01:00Z,12
                    2023-01-01T00:01:00Z,2023-01-01T00:02:00Z,20
                    2023-01-01T00:02:00Z,2023-01-01T00:03:00Z,4
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-unstable: true
      tags:
        - Meters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeterQueryRequest'
  /openmeter/plans:
    get:
      operationId: list-plans
      summary: List plans
      description: List all plans.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort plans returned in the response. Supported sort attributes are:

            - `id`
            - `key`
            - `version`
            - `created_at` (default)
            - `updated_at`
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: Filter plans returned in the response.
          schema:
            $ref: '#/components/schemas/ListPlansParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    post:
      operationId: create-plan
      summary: Create plan
      description: Create a new plan.
      responses:
        '201':
          description: Plan created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
      x-unstable: true
  /openmeter/plans/{planId}:
    put:
      operationId: update-plan
      summary: Update plan
      description: Update a plan by id.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Plan upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPlanRequest'
      x-unstable: true
    get:
      operationId: get-plan
      summary: Get plan
      description: Get a plan by id.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Plan response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    delete:
      operationId: delete-plan
      summary: Delete plan
      description: Delete a plan by id.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/plans/{planId}/addons:
    get:
      operationId: list-plan-addons
      summary: List add-ons for plan
      description: List add-ons associated with a plan.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAddonPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    post:
      operationId: create-plan-addon
      summary: Add add-on to plan
      description: Add an add-on to a plan.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: PlanAddon created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAddon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanAddonRequest'
      x-unstable: true
  /openmeter/plans/{planId}/addons/{planAddonId}:
    get:
      operationId: get-plan-addon
      summary: Get add-on association for plan
      description: Get an add-on association for a plan.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: planAddonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: PlanAddon response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAddon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
    put:
      operationId: update-plan-addon
      summary: Update add-on association for plan
      description: Update an add-on association for a plan.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: planAddonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: PlanAddon upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanAddon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPlanAddonRequest'
      x-unstable: true
    delete:
      operationId: delete-plan-addon
      summary: Remove add-on from plan
      description: Remove an add-on from a plan.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: planAddonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/plans/{planId}/archive:
    post:
      operationId: archive-plan
      summary: Archive plan version
      description: Archive a plan version.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Plan updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/plans/{planId}/publish:
    post:
      operationId: publish-plan
      summary: Publish plan version
      description: Publish a plan version.
      parameters:
        - name: planId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Plan updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Product Catalog
      x-unstable: true
  /openmeter/profiles:
    get:
      operationId: list-billing-profiles
      summary: List billing profiles
      description: List billing profiles.
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfilePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Billing Settings
    post:
      operationId: create-billing-profile
      summary: Create a new billing profile
      description: |-
        Create a new billing profile.

        Billing profiles contain the settings for billing and controls invoice
        generation. An organization can have multiple billing profiles defined. A
        billing profile is linked to a specific app. This association is established
        during the billing profile's creation and remains immutable.
      responses:
        '201':
          description: BillingProfile created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Billing Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingProfileRequest'
  /openmeter/profiles/{id}:
    get:
      operationId: get-billing-profile
      summary: Get a billing profile
      description: Get a billing profile.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: BillingProfile response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
    put:
      operationId: update-billing-profile
      summary: Update a billing profile
      description: Update a billing profile.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: BillingProfile updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertBillingProfileRequest'
    delete:
      operationId: delete-billing-profile
      summary: Delete a billing profile
      description: |-
        Delete a billing profile.

        Only such billing profiles can be deleted that are:

        - not the default profile
        - not pinned to any customer using customer overrides
        - only have finalized invoices
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Billing Settings
  /openmeter/subscriptions:
    post:
      operationId: create-subscription
      summary: Create subscription
      responses:
        '201':
          description: Subscription created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingSubscriptionCreate'
    get:
      operationId: list-subscriptions
      summary: List subscriptions
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort subscriptions returned in the response. Supported sort attributes are:

            - `id`
            - `active_from` (default)
            - `active_to`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
        - name: filter
          in: query
          required: false
          description: Filter subscriptions.
          schema:
            $ref: '#/components/schemas/ListSubscriptionsParamsFilter'
          style: deepObject
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Subscriptions
  /openmeter/subscriptions/{subscriptionId}:
    get:
      operationId: get-subscription
      summary: Get subscription
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Subscription response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Subscriptions
  /openmeter/subscriptions/{subscriptionId}/addons:
    post:
      operationId: create-subscription-addon
      summary: Create a new subscription add-on
      description: Add add-on to a subscription.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '201':
          description: SubscriptionAddon created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAddon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionAddonRequest'
      x-internal: true
      x-unstable: true
    get:
      operationId: list-subscription-addons
      summary: List subscription addons
      description: List the add-ons of a subscription.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: sort
          in: query
          required: false
          description: |-
            Sort subscription addons returned in the response. Supported sort attributes
            are:

            - `id`
            - `created_at` (default)
            - `updated_at`

            The `asc` suffix is optional as the default sort order is ascending. The `desc`
            suffix is used to specify a descending order.
          schema:
            $ref: '#/components/schemas/SortQuery'
          explode: false
          style: form
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAddonPagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Subscriptions
      x-unstable: true
  /openmeter/subscriptions/{subscriptionId}/addons/{subscriptionAddonId}:
    get:
      operationId: get-subscription-addon
      summary: Get add-on association for subscription
      description: Get an add-on association for a subscription.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
        - name: subscriptionAddonId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: SubscriptionAddon response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionAddon'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Subscriptions
      x-unstable: true
  /openmeter/subscriptions/{subscriptionId}/cancel:
    post:
      operationId: cancel-subscription
      summary: Cancel subscription
      description: |-
        Cancels the subscription. Will result in a scheduling conflict if there are
        other subscriptions scheduled to start after the cancelation time.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Subscription updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingSubscriptionCancel'
  /openmeter/subscriptions/{subscriptionId}/change:
    post:
      operationId: change-subscription
      summary: Change subscription
      description: |-
        Closes a running subscription and starts a new one according to the
        specification. Can be used for upgrades, downgrades, and plan changes.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSubscriptionChangeResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingSubscriptionChange'
  /openmeter/subscriptions/{subscriptionId}/unschedule-cancelation:
    post:
      operationId: unschedule-cancelation
      summary: Unschedule subscription cancelation
      description: Unschedules the subscription cancelation.
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: Subscription updated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
        - OpenMeter Subscriptions
  /openmeter/tax-codes:
    post:
      operationId: create-tax-code
      summary: Create tax code
      responses:
        '201':
          description: TaxCode created response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingTaxCode'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Tax
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaxCodeRequest'
      x-unstable: true
    get:
      operationId: list-tax-codes
      summary: List tax codes
      parameters:
        - $ref: '#/components/parameters/PagePaginationQuery'
        - name: include_deleted
          in: query
          required: false
          description: Include deleted tax codes in the response.
          schema:
            type: boolean
          explode: false
          style: form
      responses:
        '200':
          description: Page paginated response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxCodePagePaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      tags:
        - OpenMeter Tax
      x-unstable: true
  /openmeter/tax-codes/{taxCodeId}:
    get:
      operationId: get-tax-code
      summary: Get tax code
      parameters:
        - name: taxCodeId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: TaxCode response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingTaxCode'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Tax
      x-unstable: true
    put:
      operationId: upsert-tax-code
      summary: Upsert tax code
      parameters:
        - name: taxCodeId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '200':
          description: TaxCode upsert response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingTaxCode'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
      tags:
        - OpenMeter Tax
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertTaxCodeRequest'
      x-unstable: true
    delete:
      operationId: delete-tax-code
      summary: Delete tax code
      parameters:
        - name: taxCodeId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/ULID'
      responses:
        '204':
          description: Deleted response.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - OpenMeter Tax
      x-unstable: true
components:
  parameters:
    CursorPaginationQuery:
      name: page
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/CursorPaginationQueryPage'
      style: deepObject
    PagePaginationQuery:
      name: page
      in: query
      required: false
      description: Determines which page of the collection to retrieve.
      schema:
        type: object
        properties:
          size:
            type: integer
            description: The number of items to include per page.
          number:
            type: integer
            description: The page number.
        additionalProperties: false
      style: deepObject
  schemas:
    Addon:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
        - version
        - instance_type
        - currency
        - status
        - rate_cards
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: |-
            A key is a semi-unique string that is used to identify the add-on. It is used to
            reference the latest `active` version of the add-on and is unique with the
            version number.
          title: Key
        version:
          type: integer
          minimum: 1
          description: Version of the add-on. Incremented when the add-on is updated.
          title: Version
          default: 1
          readOnly: true
        instance_type:
          allOf:
            - $ref: '#/components/schemas/AddonInstanceType'
          description: The InstanceType of the add-ons. Can be "single" or "multiple".
          title: The InstanceType of the add-ons. Can be "single" or "multiple".
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: The currency code of the add-on.
          title: Currency
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The date and time when the add-on becomes effective. When not specified, the
            add-on is a draft.
          title: Effective start date
          readOnly: true
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The date and time when the add-on is no longer effective. When not specified,
            the add-on is effective indefinitely.
          title: Effective end date
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/AddonStatus'
          description: |-
            The status of the add-on. Computed based on the effective start and end dates:

            - `draft`: `effective_from` is not set.
            - `active`: `effective_from <= now` and (`effective_to` is not set or
            `now < effective_to`).
            - `archived`: `effective_to <= now`.
          title: Status
          readOnly: true
        rate_cards:
          type: array
          items:
            $ref: '#/components/schemas/BillingRateCard'
          description: The rate cards of the add-on.
          title: Rate cards
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalogValidationError'
          description: List of validation errors.
          title: Validation errors
          readOnly: true
      additionalProperties: false
      description: |-
        Add-on allows extending subscriptions with compatible plans with additional
        ratecards.
    AddonInstanceType:
      type: string
      enum:
        - single
        - multiple
      description: |-
        The instanceType of the add-on.

        - `single`: Can be added to a subscription only once.
        - `multiple`: Can be added to a subscription more than once.
    AddonPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Addon'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    AddonReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: Addon reference.
    AddonStatus:
      type: string
      enum:
        - draft
        - active
        - archived
      description: |-
        The status of the add-on defined by the `effective_from` and `effective_to`
        properties.

        - `draft`: The add-on has not yet been published and can be edited.
        - `active`: The add-on is published and available for use.
        - `archived`: The add-on is no longer available for use.
    Address:
      type: object
      properties:
        country:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          description: |-
            Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html)
            alpha-2 format.
          title: Country
        postal_code:
          type: string
          description: Postal code.
          title: Postal Code
        state:
          type: string
          description: State or province.
          title: State
        city:
          type: string
          description: City.
          title: City
        line1:
          type: string
          description: First line of the address.
          title: Line 1
        line2:
          type: string
          description: Second line of the address.
          title: Line 2
        phone_number:
          type: string
          description: Phone number.
          title: Phone Number
      additionalProperties: false
      description: Address
    AppCatalogItemPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingAppCatalogItem'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    AppPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingApp'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    BillingApp:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingAppStripe'
        - $ref: '#/components/schemas/BillingAppSandbox'
        - $ref: '#/components/schemas/BillingAppExternalInvoicing'
      discriminator:
        propertyName: type
        mapping:
          stripe: '#/components/schemas/BillingAppStripe'
          sandbox: '#/components/schemas/BillingAppSandbox'
          external_invoicing: '#/components/schemas/BillingAppExternalInvoicing'
      description: Installed application.
    BillingAppCapability:
      type: object
      required:
        - type
        - key
        - name
        - description
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/BillingAppCapabilityType'
          description: Type of the capability.
        key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: Key of the capability.
        name:
          type: string
          description: Name of the capability.
        description:
          type: string
          description: Description of the capability.
      additionalProperties: false
      description: App capability describes a function that an App can perform.
      example:
        type: collect_payments
        key: stripe_collect_payment
        name: Collect Payments
        description: Stripe payments collects outstanding revenue with Stripe customer's default payment method.
    BillingAppCapabilityType:
      type: string
      enum:
        - report_usage
        - report_events
        - calculate_tax
        - invoice_customers
        - collect_payments
      description: |-
        Supported capability types for an App.

        Each capability defines an integration function that an App can perform.
    BillingAppCatalogItem:
      type: object
      required:
        - type
        - name
        - description
        - capabilities
        - install_methods
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/BillingAppType'
          description: Type of the app.
          readOnly: true
        name:
          type: string
          description: Name of the app.
          readOnly: true
        description:
          type: string
          description: Description of the app.
          readOnly: true
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/BillingAppCapability'
          description: Capabilities of the app.
          readOnly: true
        install_methods:
          type: array
          items:
            $ref: '#/components/schemas/BillingAppInstallMethods'
          description: Available install methods of the app.
          readOnly: true
      additionalProperties: false
      description: |-
        Available apps for billing integrations to connect with third-party services.
        Apps can have various capabilities like syncing data from or to external
        systems, integrating with third-party services for tax calculation, delivery of
        invoices, collection of payments, etc.
      example:
        type: stripe
        name: Stripe
        description: Stripe integration allows you to collect payments with Stripe.
        capabilities:
          - type: calculate_tax
            key: stripe_calculate_tax
            name: Calculate Tax
            description: Stripe Tax calculates tax portion of the invoices.
          - type: invoice_customers
            key: stripe_invoice_customers
            name: Invoice Customers
            description: Stripe invoices customers with due amount.
          - type: collect_payments
            key: stripe_collect_payments
            name: Collect Payments
            description: Stripe payments collects outstanding revenue with Stripe customer's default payment method.
        install_methods:
          - with_oauth2
          - with_api_key
    BillingAppCustomerData:
      type: object
      properties:
        stripe:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerDataStripe'
          description: Used if the customer has a linked Stripe app.
          title: Stripe
        external_invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerDataExternalInvoicing'
          description: Used if the customer has a linked external invoicing app.
          title: External invoicing
      additionalProperties: false
      description: App customer data.
    BillingAppCustomerDataExternalInvoicing:
      type: object
      properties:
        labels:
          allOf:
            - $ref: '#/components/schemas/Labels'
          description: Labels for this external invoicing integration on the customer.
          title: Labels
      additionalProperties: false
      description: External invoicing customer data.
    BillingAppCustomerDataStripe:
      type: object
      properties:
        customer_id:
          type: string
          description: The Stripe customer ID used.
          title: Stripe customer ID
          example: cus_1234567890
        default_payment_method_id:
          type: string
          description: The Stripe default payment method ID.
          title: Stripe default payment method ID
          example: pm_1234567890
        labels:
          allOf:
            - $ref: '#/components/schemas/Labels'
          description: Labels for this Stripe integration on the customer.
          title: Labels
      additionalProperties: false
      description: Stripe customer data.
    BillingAppExternalInvoicing:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - type
        - definition
        - status
        - enable_draft_sync_hook
        - enable_issuing_sync_hook
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        type:
          type: string
          enum:
            - external_invoicing
          description: The app type.
          readOnly: true
        definition:
          allOf:
            - $ref: '#/components/schemas/BillingAppCatalogItem'
          description: The app catalog definition that this installed app is based on.
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingAppStatus'
          description: Status of the app connection.
          readOnly: true
        enable_draft_sync_hook:
          type: boolean
          description: |-
            Enable draft synchronization hook.

            When enabled, invoices will pause at the draft state and wait for the
            integration to call the draft synchronized endpoint before progressing to the
            issuing state. This allows the external system to validate and prepare the
            invoice data.

            When disabled, invoices automatically progress through the draft state based on
            the configured workflow timing.
        enable_issuing_sync_hook:
          type: boolean
          description: |-
            Enable issuing synchronization hook.

            When enabled, invoices will pause at the issuing state and wait for the
            integration to call the issuing synchronized endpoint before progressing to the
            issued state. This ensures the external invoicing system has successfully
            created and finalized the invoice before it is marked as issued.

            When disabled, invoices automatically progress through the issuing state and are
            immediately marked as issued.
      additionalProperties: false
      description: |-
        External Invoicing app enables integration with third-party invoicing or payment
        system.

        The app supports a bi-directional synchronization pattern where OpenMeter
        Billing manages the invoice lifecycle while the external system handles invoice
        presentation and payment collection.

        Integration workflow:

        1. The billing system creates invoices and transitions them through lifecycle
        states (draft → issuing → issued)
        2. The integration receives webhook notifications about invoice state changes
        3. The integration calls back to provide external system IDs and metadata
        4. The integration reports payment events back via the payment status API

        State synchronization is controlled by hooks that pause invoice progression
        until the external system confirms synchronization via API callbacks.
    BillingAppInstallMethods:
      type: string
      enum:
        - with_oauth2
        - with_api_key
        - no_credentials_required
      description: Supported installation methods for an app.
    BillingAppReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The ID of the app.
      additionalProperties: false
      description: App reference.
    BillingAppSandbox:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - type
        - definition
        - status
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        type:
          type: string
          enum:
            - sandbox
          description: The app type.
          readOnly: true
        definition:
          allOf:
            - $ref: '#/components/schemas/BillingAppCatalogItem'
          description: The app catalog definition that this installed app is based on.
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingAppStatus'
          description: Status of the app connection.
          readOnly: true
      additionalProperties: false
      description: Sandbox app can be used for testing billing features.
    BillingAppStatus:
      type: string
      enum:
        - ready
        - unauthorized
      description: Connection status of an installed app.
    BillingAppStripe:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - type
        - definition
        - status
        - account_id
        - livemode
        - masked_api_key
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        type:
          type: string
          enum:
            - stripe
          description: The app type.
          readOnly: true
        definition:
          allOf:
            - $ref: '#/components/schemas/BillingAppCatalogItem'
          description: The app catalog definition that this installed app is based on.
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingAppStatus'
          description: Status of the app connection.
          readOnly: true
        account_id:
          type: string
          description: The Stripe account ID associated with the connected Stripe account.
          readOnly: true
        livemode:
          type: boolean
          description: Indicates whether the app is connected to a live Stripe account.
          readOnly: true
        masked_api_key:
          type: string
          description: The masked Stripe API key that only exposes the first and last few characters.
          readOnly: true
      additionalProperties: false
      description: Stripe app.
    BillingAppStripeCheckoutSessionCustomTextParams:
      type: object
      properties:
        after_submit:
          type: object
          properties:
            message:
              type: string
              maxLength: 1200
              description: The custom message text (max 1200 characters).
          additionalProperties: false
          description: Text displayed after the payment confirmation button.
        shipping_address:
          type: object
          properties:
            message:
              type: string
              maxLength: 1200
              description: The custom message text (max 1200 characters).
          additionalProperties: false
          description: Text displayed alongside shipping address collection.
        submit:
          type: object
          properties:
            message:
              type: string
              maxLength: 1200
              description: The custom message text (max 1200 characters).
          additionalProperties: false
          description: Text displayed alongside the payment confirmation button.
        terms_of_service_acceptance:
          type: object
          properties:
            message:
              type: string
              maxLength: 1200
              description: The custom message text (max 1200 characters).
          additionalProperties: false
          description: Text replacing the default terms of service agreement text.
      additionalProperties: false
      description: Custom text displayed at various stages of the checkout flow.
    BillingAppStripeCheckoutSessionMode:
      type: string
      enum:
        - setup
      description: |-
        Stripe Checkout Session mode.

        Determines the primary purpose of the checkout session.
    BillingAppStripeCheckoutSessionUIMode:
      type: string
      enum:
        - embedded
        - hosted
      description: Checkout Session UI mode.
    BillingAppStripeCreateCheckoutSessionBillingAddressCollection:
      type: string
      enum:
        - auto
        - required
      description: Controls whether Checkout collects the customer's billing address.
    BillingAppStripeCreateCheckoutSessionConsentCollection:
      type: object
      properties:
        payment_method_reuse_agreement:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement'
          description: Controls the visibility of payment method reuse agreement.
        promotions:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionConsentCollectionPromotions'
          description: |-
            Enables collection of promotional communication consent.

            Only available to US merchants. When set to "auto", Checkout determines whether
            to show the option based on the customer's locale.
        terms_of_service:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionConsentCollectionTermsOfService'
          description: |-
            Requires customers to accept terms of service before payment.

            Requires a valid terms of service URL in your Stripe Dashboard settings.
      additionalProperties: false
      description: Checkout Session consent collection configuration.
    BillingAppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement:
      type: object
      properties:
        position:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition'
          description: Position and visibility of the payment method reuse agreement.
      additionalProperties: false
      description: Payment method reuse agreement configuration.
    BillingAppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreementPosition:
      type: string
      enum:
        - auto
        - hidden
      description: Position of payment method reuse agreement in the UI.
    BillingAppStripeCreateCheckoutSessionConsentCollectionPromotions:
      type: string
      enum:
        - auto
        - none
      description: Promotional communication consent collection setting.
    BillingAppStripeCreateCheckoutSessionConsentCollectionTermsOfService:
      type: string
      enum:
        - none
        - required
      description: Terms of service acceptance requirement.
    BillingAppStripeCreateCheckoutSessionCustomerUpdate:
      type: object
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionCustomerUpdateBehavior'
          description: |-
            Whether to save the billing address to customer.address.

            Defaults to "never".
          default: never
        name:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionCustomerUpdateBehavior'
          description: |-
            Whether to save the customer name to customer.name.

            Defaults to "never".
          default: never
        shipping:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionCustomerUpdateBehavior'
          description: |-
            Whether to save shipping information to customer.shipping.

            Defaults to "never".
          default: never
      additionalProperties: false
      description: Controls which customer fields can be updated by the checkout session.
    BillingAppStripeCreateCheckoutSessionCustomerUpdateBehavior:
      type: string
      enum:
        - auto
        - never
      description: Behavior for updating customer fields from checkout session.
    BillingAppStripeCreateCheckoutSessionRedirectOnCompletion:
      type: string
      enum:
        - always
        - if_required
        - never
      description: Redirect behavior for embedded checkout sessions.
    BillingAppStripeCreateCheckoutSessionRequestOptions:
      type: object
      properties:
        billing_address_collection:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionBillingAddressCollection'
          description: |-
            Whether to collect the customer's billing address.

            Defaults to auto, which only collects the address when necessary for tax
            calculation.
          default: auto
        cancel_url:
          type: string
          description: |-
            URL to redirect customers who cancel the checkout session.

            Not allowed when ui_mode is "embedded".
        client_reference_id:
          type: string
          description: |-
            Unique reference string for reconciling sessions with internal systems.

            Can be a customer ID, cart ID, or any other identifier.
        customer_update:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionCustomerUpdate'
          description: Controls which customer fields can be updated by the checkout session.
        consent_collection:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionConsentCollection'
          description: Configuration for collecting customer consent during checkout.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: |-
            Three-letter ISO 4217 currency code in uppercase.

            Required for payment mode sessions. Optional for setup mode sessions.
        custom_text:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCheckoutSessionCustomTextParams'
          description: Custom text to display during checkout at various stages.
        expires_at:
          type: integer
          format: int64
          description: |-
            Unix timestamp when the checkout session expires.

            Can be 30 minutes to 24 hours from creation. Defaults to 24 hours.
        locale:
          type: string
          description: |-
            IETF language tag for the checkout UI locale.

            If blank or "auto", uses the browser's locale. Example: "en", "fr", "de".
        metadata:
          type: object
          additionalProperties:
            type: string
          description: |-
            Set of key-value pairs to attach to the checkout session.

            Useful for storing additional structured information.
        return_url:
          type: string
          description: |-
            Return URL for embedded checkout sessions after payment authentication.

            Required if ui_mode is "embedded" and redirect-based payment methods are
            enabled.
        success_url:
          type: string
          description: |-
            Success URL to redirect customers after completing payment or setup.

            Not allowed when ui_mode is "embedded". See:
            https://docs.stripe.com/payments/checkout/custom-success-page
        ui_mode:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCheckoutSessionUIMode'
          description: |-
            The UI mode for the checkout session.

            "hosted" displays a Stripe-hosted page. "embedded" integrates directly into your
            app. Defaults to "hosted".
          default: hosted
        payment_method_types:
          type: array
          items:
            type: string
          description: |-
            List of payment method types to enable (e.g., "card", "us_bank_account").

            If not specified, Stripe enables all relevant payment methods.
        redirect_on_completion:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionRedirectOnCompletion'
          description: |-
            Redirect behavior for embedded checkout sessions.

            Controls when to redirect users after completion. See:
            https://docs.stripe.com/payments/checkout/custom-success-page?payment-ui=embedded-form
        tax_id_collection:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionTaxIdCollection'
          description: Configuration for collecting tax IDs during checkout.
      additionalProperties: false
      description: |-
        Configuration options for creating a Stripe Checkout Session.

        Based on Stripe's
        [Checkout Session API parameters](https://docs.stripe.com/api/checkout/sessions/create).
    BillingAppStripeCreateCheckoutSessionResult:
      type: object
      required:
        - customer_id
        - stripe_customer_id
        - session_id
        - setup_intent_id
        - created_at
        - mode
      properties:
        customer_id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The customer ID in the billing system.
        stripe_customer_id:
          type: string
          description: The Stripe customer ID.
        session_id:
          type: string
          description: The Stripe checkout session ID.
        setup_intent_id:
          type: string
          description: The setup intent ID created for collecting the payment method.
        client_secret:
          type: string
          description: |-
            Client secret for initializing Stripe.js on the client side.

            Required for embedded checkout sessions. See:
            https://docs.stripe.com/payments/checkout/custom-success-page
        client_reference_id:
          type: string
          description: |-
            The client reference ID provided in the request.

            Useful for reconciling the session with your internal systems.
        customer_email:
          type: string
          description: Customer's email address if provided to Stripe.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency code for the checkout session.
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when the checkout session was created.
        expires_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when the checkout session will expire.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Metadata attached to the checkout session.
        status:
          type: string
          description: |-
            The status of the checkout session.

            See:
            https://docs.stripe.com/api/checkout/sessions/object#checkout_session_object-status
        url:
          type: string
          description: URL to redirect customers to the checkout page (for hosted mode).
        mode:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCheckoutSessionMode'
          description: |-
            Mode of the checkout session.

            Currently only "setup" mode is supported for collecting payment methods.
        cancel_url:
          type: string
          description: The cancel URL where customers are redirected if they cancel.
        success_url:
          type: string
          description: The success URL where customers are redirected after completion.
        return_url:
          type: string
          description: The return URL for embedded sessions after authentication.
      additionalProperties: false
      description: |-
        Result of creating a Stripe Checkout Session.

        Contains all the information needed to redirect customers to the checkout or
        initialize an embedded checkout flow.
    BillingAppStripeCreateCheckoutSessionTaxIdCollection:
      type: object
      properties:
        enabled:
          type: boolean
          description: |-
            Enable tax ID collection during checkout.

            Defaults to false.
          default: false
        required:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionTaxIdCollectionRequired'
          description: |-
            Whether tax ID collection is required.

            Defaults to "never".
          default: never
      additionalProperties: false
      description: Tax ID collection configuration for checkout sessions.
    BillingAppStripeCreateCheckoutSessionTaxIdCollectionRequired:
      type: string
      enum:
        - if_supported
        - never
      description: Tax ID collection requirement level.
    BillingAppStripeCreateCustomerPortalSessionOptions:
      type: object
      properties:
        configuration_id:
          type: string
          description: |-
            The ID of an existing
            [Stripe configuration](https://docs.stripe.com/api/customer_portal/configurations)
            to use for this session, describing its functionality and features. If not
            specified, the session uses the default configuration.
        locale:
          type: string
          description: |-
            The IETF
            [language tag](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-locale)
            of the locale customer portal is displayed in. If blank or `auto`, the
            customer's preferred_locales or browser's locale is used.
        return_url:
          type: string
          description: |-
            The
            [URL to redirect](https://docs.stripe.com/api/customer_portal/sessions/create#create_portal_session-return_url)
            the customer to after they have completed their requested actions.
      additionalProperties: false
      description: Request to create a Stripe Customer Portal Session.
    BillingAppStripeCreateCustomerPortalSessionResult:
      type: object
      required:
        - id
        - stripe_customer_id
        - configuration_id
        - livemode
        - created_at
        - return_url
        - locale
        - url
      properties:
        id:
          type: string
          description: |-
            The ID of the customer portal session.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-id
        stripe_customer_id:
          type: string
          description: The ID of the stripe customer.
        configuration_id:
          type: string
          description: |-
            Configuration used to customize the customer portal.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-configuration
        livemode:
          type: boolean
          description: |-
            Livemode.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-livemode
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            Created at.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-created
        return_url:
          type: string
          description: |-
            Return URL.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-return_url
        locale:
          type: string
          description: |-
            The IETF language tag of the locale customer portal is displayed in.

            See:
            https://docs.stripe.com/api/customer_portal/sessions/object#portal_session_object-locale
        url:
          type: string
          description: |-
            The URL to redirect the customer to after they have completed their requested
            actions.
      additionalProperties: false
      description: |-
        Result of creating a
        [Stripe Customer Portal Session](https://docs.stripe.com/api/customer_portal/sessions/object).

        Contains all the information needed to redirect the customer to the Stripe
        Customer Portal.
    BillingAppType:
      type: string
      enum:
        - sandbox
        - stripe
        - external_invoicing
      description: The type of the app.
    BillingCharge:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingChargeFlatFee'
        - $ref: '#/components/schemas/BillingChargeUsageBased'
      discriminator:
        propertyName: type
        mapping:
          flat_fee: '#/components/schemas/BillingChargeFlatFee'
          usage_based: '#/components/schemas/BillingChargeUsageBased'
      description: Customer charge.
      title: Customer charge
    BillingChargeFlatFee:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - type
        - customer
        - lifecycle_controller
        - currency
        - status
        - invoice_at
        - service_period
        - full_service_period
        - billing_period
        - settlement_mode
        - payment_term
        - proration_configuration
        - amount_after_proration
        - price
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        type:
          type: string
          enum:
            - flat_fee
          description: The type of the charge.
          title: Type
        customer:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerReference'
          description: The customer owning the charge.
          title: Customer
          readOnly: true
        lifecycle_controller:
          allOf:
            - $ref: '#/components/schemas/BillingLifecycleController'
          description: |-
            Indicates whether the charge lifecycle is controlled by OpenMeter or manually
            overridden by the API user.
          title: Lifecycle controller
          readOnly: true
        subscription:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionReference'
          description: |-
            The subscription that originated the charge, when the charge was created from a
            subscription item.
          title: Subscription
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency of the charge.
          title: Currency
        status:
          allOf:
            - $ref: '#/components/schemas/BillingChargeStatus'
          description: The lifecycle status of the charge.
          title: Status
          readOnly: true
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
          readOnly: true
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
          readOnly: true
        advance_after:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The earliest time when the charge should be advanced again by background
            processing.
          title: Advance after
          readOnly: true
        unique_reference_id:
          type: string
          description: Unique reference ID of the charge.
          title: Unique reference ID
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: Settlement mode of the charge.
          title: Settlement mode
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfig'
          description: Tax configuration of the charge.
          title: Tax configuration
        payment_term:
          allOf:
            - $ref: '#/components/schemas/BillingPricePaymentTerm'
          description: Payment term of the flat fee charge.
          title: Payment term
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingChargeFlatFeeDiscounts'
          description: The discounts applied to the charge.
          title: Discounts
        feature_key:
          type: string
          description: The feature associated with the charge, when applicable.
          title: Feature key
        proration_configuration:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardProrationConfiguration'
          description: The proration configuration of the charge.
          title: Proration configuration
        amount_after_proration:
          allOf:
            - $ref: '#/components/schemas/CurrencyAmount'
          description: The amount after proration of the charge.
          title: Amount after proration
          readOnly: true
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price of the charge.
          title: Price
          readOnly: true
        system_intent:
          allOf:
            - $ref: '#/components/schemas/BillingChargeFlatFeeSystemIntent'
          description: |-
            Current intent from the system lifecycle controller for a charge that has an
            active manual override. The top-level charge fields remain the effective
            customer-facing intent.
          title: System intent
          readOnly: true
      additionalProperties: false
      description: A flat fee charge for a customer.
      title: Flat fee charge
    BillingChargeFlatFeeDiscounts:
      type: object
      properties:
        percentage:
          type: number
          minimum: 0
          maximum: 100
          description: Percentage discount applied to the price (0–100).
      additionalProperties: false
      description: |-
        Discounts applicable to flat fee charges.

        This is the same as `ProductCatalog.Discounts` but without the `usage` field,
        which is not applicable to flat fee charges.
      title: Flat fee charge discounts
    BillingChargeFlatFeeSystemIntent:
      type: object
      required:
        - name
        - invoice_at
        - service_period
        - full_service_period
        - billing_period
        - payment_term
        - proration_configuration
        - amount_before_proration
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
          readOnly: true
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
          readOnly: true
        payment_term:
          allOf:
            - $ref: '#/components/schemas/BillingPricePaymentTerm'
          description: Payment term of the flat fee charge.
          title: Payment term
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingChargeFlatFeeDiscounts'
          description: The discounts applied to the charge.
          title: Discounts
        proration_configuration:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardProrationConfiguration'
          description: The proration configuration of the charge.
          title: Proration configuration
        amount_before_proration:
          allOf:
            - $ref: '#/components/schemas/CurrencyAmount'
          description: The amount before proration of the system lifecycle controller flat fee intent.
          title: Amount before proration
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The timestamp when the system lifecycle controller intent was deleted. The
            effective charge can remain visible while a manual override is active.
          title: Deleted at
          readOnly: true
      additionalProperties: false
      description: |-
        Flat fee intent fields from the system lifecycle controller shadowed by a manual
        override.
      title: Flat fee system lifecycle controller charge intent
    BillingChargeReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Unique identifier for the charge.
          title: ID
          readOnly: true
      additionalProperties: false
      description: Reference to a charge associated with an invoice line.
    BillingChargeStatus:
      type: string
      enum:
        - created
        - active
        - final
        - deleted
      description: |-
        Lifecycle status of a charge.

        Values:

        - `created`: The charge has been created but is not active yet.
        - `active`: The charge is active.
        - `final`: The charge is fully finalized and no further changes are expected.
        - `deleted`: The charge has been deleted.
      title: Charge status
    BillingChargeTotals:
      type: object
      required:
        - booked
      properties:
        booked:
          allOf:
            - $ref: '#/components/schemas/BillingTotals'
          description: The amount of the charge already booked to the internal accounting system.
          title: Booked
          readOnly: true
        realtime:
          allOf:
            - $ref: '#/components/schemas/BillingTotals'
          description: |-
            The realtime amount of the charge.

            Requires the `realtime_usage` expand.
          title: Realtime totals
          readOnly: true
      additionalProperties: false
      description: |-
        The totals of a change.

        RealTime is only expanded when the `real_time_usage` expand is used.
    BillingChargeUsageBased:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - type
        - customer
        - lifecycle_controller
        - currency
        - status
        - invoice_at
        - service_period
        - full_service_period
        - billing_period
        - settlement_mode
        - feature_key
        - totals
        - price
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        type:
          type: string
          enum:
            - usage_based
          description: The type of the charge.
          title: Type
        customer:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerReference'
          description: The customer owning the charge.
          title: Customer
          readOnly: true
        lifecycle_controller:
          allOf:
            - $ref: '#/components/schemas/BillingLifecycleController'
          description: |-
            Indicates whether the charge lifecycle is controlled by OpenMeter or manually
            overridden by the API user.
          title: Lifecycle controller
          readOnly: true
        subscription:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionReference'
          description: |-
            The subscription that originated the charge, when the charge was created from a
            subscription item.
          title: Subscription
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency of the charge.
          title: Currency
        status:
          allOf:
            - $ref: '#/components/schemas/BillingChargeStatus'
          description: The lifecycle status of the charge.
          title: Status
          readOnly: true
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
          readOnly: true
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
          readOnly: true
        advance_after:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The earliest time when the charge should be advanced again by background
            processing.
          title: Advance after
          readOnly: true
        unique_reference_id:
          type: string
          description: Unique reference ID of the charge.
          title: Unique reference ID
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: Settlement mode of the charge.
          title: Settlement mode
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfig'
          description: Tax configuration of the charge.
          title: Tax configuration
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardDiscounts'
          description: Discounts applied to the usage-based charge.
          title: Discounts
        feature_key:
          type: string
          description: The feature associated with the charge.
          title: Feature key
        totals:
          allOf:
            - $ref: '#/components/schemas/BillingChargeTotals'
          description: Aggregated booked and realtime totals for the charge.
          title: Totals for the charge
          readOnly: true
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price of the charge.
          title: Price
        system_intent:
          allOf:
            - $ref: '#/components/schemas/BillingChargeUsageBasedSystemIntent'
          description: |-
            Current intent from the system lifecycle controller for a charge that has an
            active manual override. The top-level charge fields remain the effective
            customer-facing intent.
          title: System intent
          readOnly: true
      additionalProperties: false
      description: A usage-based charge for a customer.
      title: Usage-based charge
    BillingChargeUsageBasedSystemIntent:
      type: object
      required:
        - name
        - invoice_at
        - service_period
        - full_service_period
        - billing_period
        - price
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
          readOnly: true
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
          readOnly: true
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardDiscounts'
          description: Discounts applied to the usage-based charge.
          title: Discounts
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price of the charge.
          title: Price
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The timestamp when the system lifecycle controller intent was deleted. The
            effective charge can remain visible while a manual override is active.
          title: Deleted at
          readOnly: true
      additionalProperties: false
      description: |-
        Usage-based intent fields from the system lifecycle controller shadowed by a
        manual override.
      title: Usage-based system lifecycle controller charge intent
    BillingChargesExpand:
      type: string
      enum:
        - real_time_usage
      description: |-
        Expands for customer charges.

        Values:

        - `real_time_usage`: The charge's real-time usage.
      title: Customer charge expands
    BillingCostBasis:
      type: object
      required:
        - id
        - fiat_code
        - rate
        - created_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        fiat_code:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The fiat currency code for the cost basis.
        rate:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The cost rate for the currency.
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            An ISO-8601 timestamp representation of the date from which the cost basis is
            effective. If not provided, it will be effective immediately and will be set to
            `now` by the system.
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            An ISO-8601 timestamp representation of the date until which the cost basis is
            effective. If provided, it must be later than `effective_from`. If not provided,
            it remains effective until superseded.
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
      additionalProperties: false
      description: Describes currency basis supported by billing system.
    BillingCreditAdjustment:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
      additionalProperties: false
      description: |-
        A credit adjustment can be used to make manual adjustments to a customer's
        credit balance.

        Supported use-cases:

        - Usage correction
      title: Credit adjustment
    BillingCreditAvailabilityPolicy:
      type: string
      enum:
        - on_creation
      description: |-
        When credits become available for consumption.

        - `on_creation`: Credits are available as soon as the grant is created.
        - `on_authorization`: Credits are available once the payment is authorized.
        - `on_settlement`: Credits are available once the payment is settled.
      title: Credit availability policy
    BillingCreditBalances:
      type: object
      required:
        - retrieved_at
        - balances
      properties:
        retrieved_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp of the balance retrieval.
          readOnly: true
        balances:
          type: array
          items:
            $ref: '#/components/schemas/CreditBalance'
          description: The balances by currencies.
          readOnly: true
      additionalProperties: false
      description: The balances of the credits of a customer.
      title: Credit balances
    BillingCreditFundingMethod:
      type: string
      enum:
        - none
        - invoice
        - external
      description: |-
        The funding method describes how the grant is funded.

        - `none`: No funding workflow applies, for example promotional grants
        - `invoice`: The grant is funded by an in-system invoice flow
        - `external`: The grant is funded outside the system (e.g., wire transfer,
        external invoice, or manual reconciliation)
      title: Credit funding method
    BillingCreditGrant:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - funding_method
        - currency
        - amount
        - status
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        funding_method:
          allOf:
            - $ref: '#/components/schemas/BillingCreditFundingMethod'
          description: Funding method of the grant.
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: The currency of the granted credits.
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Granted credit amount.
        purchase:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantPurchase'
          description: Present when a funding workflow applies (funding_method is not `none`).
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantTaxConfig'
          description: |-
            Tax configuration for the grant.

            For `invoice` and `external` funding methods, tax configuration should be
            provided to ensure correct revenue recognition. When not provided, the default
            credit grant tax code is applied, if that's not set the global default taxcode
            is used.
        invoice:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantInvoiceReference'
          description: Available when `funding_method` is `invoice`.
          readOnly: true
        filters:
          $ref: '#/components/schemas/BillingCreditGrantFilters'
        priority:
          type: integer
          format: int16
          minimum: 1
          maximum: 1000
          description: Draw-down priority of the grant. Lower values have higher priority.
          default: 10
        effective_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The timestamp when the credit grant becomes effective.

            Defaults to the current date and time.
        key:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceKey'
          description: |-
            Idempotency key for the credit grant creation request.

            When provided, reusing the same key returns an HTTP 409 Conflict instead of
            creating a duplicate grant, which makes create requests safe to retry.
        expires_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The timestamp when the credit grant expires.

            Calculated from the grant effective time and `expires_after` if provided.
          readOnly: true
        voided_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when the grant was voided.
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantStatus'
          description: Current lifecycle status of the grant.
          readOnly: true
      additionalProperties: false
      description: |-
        A credit grant allocates credits to a customer.

        Credits are drawn down against charges according to the settlement mode
        configured on the rate card.
      title: Credit grant
    BillingCreditGrantFilters:
      type: object
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/ResourceKey'
          description: |-
            Limit the credit grant to specific features. If no features are specified, the
            credit grant can be used for any feature.
          example:
            - input_tokens
            - output_tokens
      additionalProperties: false
      description: Filters for the credit grant.
    BillingCreditGrantInvoiceReference:
      type: object
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Identifier of the invoice associated with the grant.
          readOnly: true
        line:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/ULID'
          required:
            - id
          additionalProperties: false
          description: Identifier of the invoice line associated with the grant.
          readOnly: true
      additionalProperties: false
      description: Invoice references for the grant.
    BillingCreditGrantPurchase:
      type: object
      required:
        - currency
        - amount
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency of the purchase amount.
        per_unit_cost_basis:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Cost basis per credit unit used to calculate the purchase amount.

            If `per_unit_cost_basis` is 0.50 and credit amount is $100.00, the total charge
            is $50.00. The value must be greater than 0. If the cost basis is 0, use
            `funding_method=none` instead.

            Defaults to 1.0.
          default: '1.0'
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The purchase amount. Calculated from `per_unit_cost_basis` and credit `amount`.
          readOnly: true
        availability_policy:
          allOf:
            - $ref: '#/components/schemas/BillingCreditAvailabilityPolicy'
          description: |-
            Controls when credits become available for consumption.

            Defaults to `on_creation`.
          default: on_creation
        settlement_status:
          allOf:
            - $ref: '#/components/schemas/BillingCreditPurchasePaymentSettlementStatus'
          description: Current payment settlement status.
          readOnly: true
      additionalProperties: false
      description: Purchase and payment terms of the grant.
    BillingCreditGrantStatus:
      type: string
      enum:
        - pending
        - active
        - expired
        - voided
      description: |-
        Credit grant lifecycle status.

        - `pending`: The credit block has been created but is not yet valid.
        (`effective_at` is in the future or availability_policy is not met)
        - `active`: The credit block is currently valid and eligible for consumption.
        (`effective_at` is in the past, `expires_at` is in the future and
        availability_policy is met)
        - `expired`: The credit block expired with remaining unused balance,
        `expires_at` time has passed.
        - `voided`: The credit block was voided. Remaining balance is forfeited.
      title: Credit grant lifecycle status
    BillingCreditGrantTaxConfig:
      type: object
      properties:
        behavior:
          allOf:
            - $ref: '#/components/schemas/BillingTaxBehavior'
          description: Tax behavior applied to the invoice line item.
        tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: Tax code applied to the invoice line item.
      additionalProperties: false
      description: |-
        Tax configuration for a credit grant.

        Tax configuration should be provided to ensure correct revenue recognition,
        including for externally funded grants.
      title: Tax configuration for a credit grant
    BillingCreditGrantVoidPaymentAdjustment:
      type: string
      enum:
        - none
      description: |-
        Describes how voiding a credit grant adjusts related payment state.

        - `none`: Voiding does not adjust invoices, payment authorization, settlement,
        payment intents, or external collection state.
      title: Credit grant void payment adjustment
    BillingCreditPurchasePaymentSettlementStatus:
      type: string
      enum:
        - pending
        - authorized
        - settled
      description: |-
        Credit purchase payment settlement status.

        - `pending`: Payment has been initiated and is not yet authorized.
        - `authorized`: Payment has been authorized.
        - `settled`: Payment has been settled.
      title: Credit purchase payment settlement status
    BillingCreditTransaction:
      type: object
      required:
        - id
        - name
        - created_at
        - booked_at
        - type
        - currency
        - amount
        - available_balance
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        booked_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The date and time the transaction was booked.
          readOnly: true
        type:
          allOf:
            - $ref: '#/components/schemas/BillingCreditTransactionType'
          description: The type of credit transaction.
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: Currency of the balance affected by the transaction.
          readOnly: true
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Signed amount of the credit movement. Positive values add balance, negative
            values reduce balance.
          readOnly: true
        available_balance:
          type: object
          properties:
            before:
              $ref: '#/components/schemas/Numeric'
            after:
              $ref: '#/components/schemas/Numeric'
          required:
            - before
            - after
          additionalProperties: false
          description: The available balance before and after the transaction.
          readOnly: true
      additionalProperties: false
      description: |-
        A credit transaction represents a single credit movement on the customer's
        balance.

        Credit transactions are immutable.
      title: Credit transaction
    BillingCreditTransactionType:
      type: string
      enum:
        - funded
        - consumed
        - expired
        - voided
      description: |-
        The type of the credit transaction.

        - `funded`: Credit granted and available for consumption.
        - `consumed`: Credit consumed by usage or fees.
        - `expired`: Credit removed because it expired before being used.
        - `voided`: Credit removed because the grant was voided before being used.
    BillingCurrency:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingCurrencyFiat'
        - $ref: '#/components/schemas/BillingCurrencyCustom'
      discriminator:
        propertyName: type
        mapping:
          fiat: '#/components/schemas/BillingCurrencyFiat'
          custom: '#/components/schemas/BillingCurrencyCustom'
      description: Fiat or custom currency.
    BillingCurrencyCode:
      type: string
      allOf:
        - $ref: '#/components/schemas/CurrencyCode'
      description: Fiat or custom currency code.
      x-go-type: string
    BillingCurrencyCodeCustom:
      type: string
      minLength: 3
      maxLength: 24
      description: |-
        Custom currency code. It should be a unique code but not conflicting with any
        existing fiat currency codes.
    BillingCurrencyCustom:
      type: object
      required:
        - type
        - name
        - id
        - code
        - created_at
      properties:
        type:
          type: string
          enum:
            - custom
          description: The type of the currency.
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            The name of the currency. It should be a human-readable string that represents
            the name of the currency, such as "US Dollar" or "Euro".
        symbol:
          type: string
          minLength: 1
          description: |-
            The symbol of the currency. It should be a string that represents the symbol of
            the currency, such as "$" for US Dollar or "€" for Euro.
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        code:
          $ref: '#/components/schemas/BillingCurrencyCodeCustom'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of the custom currency creation date.
          readOnly: true
      additionalProperties: false
      description: Describes custom currency.
    BillingCurrencyFiat:
      type: object
      required:
        - type
        - name
        - code
      properties:
        type:
          type: string
          enum:
            - fiat
          description: The type of the currency.
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            The name of the currency. It should be a human-readable string that represents
            the name of the currency, such as "US Dollar" or "Euro".
        symbol:
          type: string
          minLength: 1
          description: |-
            The symbol of the currency. It should be a string that represents the symbol of
            the currency, such as "$" for US Dollar or "€" for Euro.
        code:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          readOnly: true
      additionalProperties: false
      description: Currency describes a currency supported by the billing system.
    BillingCurrencyType:
      type: string
      enum:
        - fiat
        - custom
      description: |-
        Currency type for custom currencies. It should be a unique code but not
        conflicting with any existing standard currency codes.
    BillingCustomer:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          $ref: '#/components/schemas/ExternalResourceKey'
        usage_attribution:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerUsageAttribution'
          description: Mapping to attribute metered usage to the customer by the event subject.
          title: Usage Attribution
        primary_email:
          type: string
          description: The primary email address of the customer.
          title: Primary Email
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency of the customer. Used for billing, tax and invoicing.
          title: Currency
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: The billing address of the customer. Used for tax and invoicing.
          title: Billing Address
      additionalProperties: false
      description: |-
        Customers can be individuals or organizations that can subscribe to plans and
        have access to features.
    BillingCustomerData:
      type: object
      properties:
        billing_profile:
          allOf:
            - $ref: '#/components/schemas/BillingProfileReference'
          description: |-
            The billing profile for the customer.

            If not provided, the default billing profile will be used.
          title: Billing profile
        app_data:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerData'
          description: App customer data.
          title: App customer data
      additionalProperties: false
      description: Billing customer data.
    BillingCustomerReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The ID of the customer.
      additionalProperties: false
      description: Customer reference.
    BillingCustomerStripeCreateCheckoutSessionRequest:
      type: object
      required:
        - stripe_options
      properties:
        stripe_options:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCheckoutSessionRequestOptions'
          description: |-
            Options for configuring the Stripe Checkout Session.

            These options are passed directly to Stripe's
            [checkout session creation API](https://docs.stripe.com/api/checkout/sessions/create).
      additionalProperties: false
      description: |-
        Request to create a Stripe Checkout Session for the customer.

        Checkout Sessions are used to collect payment method information from customers
        in a secure, Stripe-hosted interface. This integration uses setup mode to
        collect payment methods that can be charged later for subscription billing.
    BillingCustomerStripeCreateCustomerPortalSessionRequest:
      type: object
      required:
        - stripe_options
      properties:
        stripe_options:
          allOf:
            - $ref: '#/components/schemas/BillingAppStripeCreateCustomerPortalSessionOptions'
          description: Options for configuring the Stripe Customer Portal Session.
      additionalProperties: false
      description: |-
        Request to create a Stripe Customer Portal Session for the customer.

        Useful to redirect the customer to the Stripe Customer Portal to manage their
        payment methods, change their billing address and access their invoice history.
        Only returns URL if the customer billing profile is linked to a stripe app and
        customer.
    BillingCustomerUsageAttribution:
      type: object
      required:
        - subject_keys
      properties:
        subject_keys:
          type: array
          items:
            $ref: '#/components/schemas/UsageAttributionSubjectKey'
          minItems: 0
          description: |-
            The subjects that are attributed to the customer. Can be empty when no usage
            event subjects are associated with the customer.
          title: Subject Keys
      additionalProperties: false
      description: |-
        Mapping to attribute metered usage to the customer. One customer can have zero
        or more subjects, but one subject can only belong to one customer.
    BillingEntitlementAccessResult:
      type: object
      required:
        - type
        - feature_key
        - has_access
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/BillingEntitlementType'
          description: The type of the entitlement.
          example: static
          readOnly: true
        feature_key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The feature key of the entitlement.
          example: available_models
          readOnly: true
        has_access:
          type: boolean
          description: |-
            Whether the customer has access to the feature. Always true for `boolean` and
            `static` entitlements. Depends on balance for `metered` entitlements.
          example: true
          readOnly: true
        config:
          type: string
          description: |-
            Only available for static entitlements. Config is the JSON parsable
            configuration of the entitlement. Useful to describe per customer configuration.
          example: '{ "availableModels": ["gpt-5", "gpt-4o"] }'
          readOnly: true
      additionalProperties: false
      description: Entitlement access result.
    BillingEntitlementType:
      type: string
      enum:
        - metered
        - static
        - boolean
      description: The type of the entitlement.
    BillingFeatureLLMTokenType:
      type: string
      enum:
        - input
        - output
        - cache_read
        - cache_write
        - reasoning
        - request
        - response
      description: Token type for LLM cost lookup.
    BillingFeatureLLMUnitCost:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - llm
          description: The type discriminator for LLM unit cost.
        provider_property:
          type: string
          description: |-
            Meter group-by property that holds the LLM provider. Use this when the meter has
            a group-by dimension for provider. Mutually exclusive with `provider`.
          title: Provider property
        provider:
          type: string
          description: |-
            Static LLM provider value (e.g., "openai", "anthropic"). Use this when the
            feature tracks a single provider. Mutually exclusive with `provider_property`.
          title: Provider
        model_property:
          type: string
          description: |-
            Meter group-by property that holds the model ID. Use this when the meter has a
            group-by dimension for model. Mutually exclusive with `model`.
          title: Model property
        model:
          type: string
          description: |-
            Static model ID value (e.g., "gpt-4", "claude-3-5-sonnet"). Use this when the
            feature tracks a single model. Mutually exclusive with `model_property`.
          title: Model
        token_type_property:
          type: string
          description: |-
            Meter group-by property that holds the token type. Use this when the meter has a
            group-by dimension for token type. Mutually exclusive with `token_type`.
          title: Token type property
        token_type:
          allOf:
            - $ref: '#/components/schemas/BillingFeatureLLMTokenType'
          description: |-
            Static token type value. Use this when the feature tracks a single token type
            (e.g., only input tokens). `request` is an alias for `input`, `response` is an
            alias for `output`. Mutually exclusive with `token_type_property`.
          title: Token type
        pricing:
          allOf:
            - $ref: '#/components/schemas/BillingFeatureLLMUnitCostPricing'
          description: |-
            Resolved per-token pricing from the LLM cost database. Populated in responses
            when the provider and model can be determined, either from static values or from
            meter group-by filters with exact matches.
          title: Resolved pricing
          readOnly: true
      additionalProperties: false
      description: |-
        LLM cost lookup configuration. Each dimension (provider, model, token type) can
        be specified as either a static value or a meter group-by property name
        (mutually exclusive).
    BillingFeatureLLMUnitCostPricing:
      type: object
      required:
        - input_per_token
        - output_per_token
      properties:
        input_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cost per input token in USD.
          title: Input per token
        output_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cost per output token in USD.
          title: Output per token
        cache_read_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cost per cache read token in USD.
          title: Cache read per token
        reasoning_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cost per reasoning token in USD.
          title: Reasoning per token
        cache_write_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cost per cache write token in USD.
          title: Cache write per token
      additionalProperties: false
      description: Resolved per-token pricing from the LLM cost database.
    BillingFeatureManualUnitCost:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          enum:
            - manual
          description: The type discriminator for manual unit cost.
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Fixed per-unit cost amount in USD.
      additionalProperties: false
      description: A fixed per-unit cost amount.
    BillingFeatureUnitCost:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingFeatureManualUnitCost'
        - $ref: '#/components/schemas/BillingFeatureLLMUnitCost'
      discriminator:
        propertyName: type
        mapping:
          manual: '#/components/schemas/BillingFeatureManualUnitCost'
          llm: '#/components/schemas/BillingFeatureLLMUnitCost'
      description: |-
        Per-unit cost configuration for a feature. Either a fixed manual amount or a
        dynamic LLM cost lookup.
    BillingInstallAppExternalInvoicing:
      type: object
      required:
        - type
        - name
        - create_billing_profile
      properties:
        type:
          type: string
          enum:
            - external_invoicing
          description: Type of the app.
        name:
          type: string
          description: Name of the app.
        create_billing_profile:
          type: boolean
          description: |-
            If true, a billing profile will be created for the app. The Stripe app will be
            also set as the default billing profile if the current default is a Sandbox app.
      additionalProperties: false
      description: Base model for installing an app from the catalog.
    BillingInstallAppRequest:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingInstallAppStripeWithApiKey'
        - $ref: '#/components/schemas/BillingInstallAppSandbox'
        - $ref: '#/components/schemas/BillingInstallAppExternalInvoicing'
      discriminator:
        propertyName: type
        mapping:
          stripe: '#/components/schemas/BillingInstallAppStripeWithApiKey'
          sandbox: '#/components/schemas/BillingInstallAppSandbox'
          external_invoicing: '#/components/schemas/BillingInstallAppExternalInvoicing'
      description: Request to install an app from the catalog.
    BillingInstallAppResponse:
      type: object
      required:
        - app
        - default_for_capability_types
      properties:
        app:
          allOf:
            - $ref: '#/components/schemas/BillingApp'
          readOnly: true
        default_for_capability_types:
          type: array
          items:
            $ref: '#/components/schemas/BillingAppCapabilityType'
          readOnly: true
      additionalProperties: false
      description: Response of the app install.
    BillingInstallAppSandbox:
      type: object
      required:
        - type
        - name
        - create_billing_profile
      properties:
        type:
          type: string
          enum:
            - sandbox
          description: Type of the app.
        name:
          type: string
          description: Name of the app.
        create_billing_profile:
          type: boolean
          description: |-
            If true, a billing profile will be created for the app. The Stripe app will be
            also set as the default billing profile if the current default is a Sandbox app.
      additionalProperties: false
      description: Base model for installing an app from the catalog.
    BillingInstallAppStripeWithApiKey:
      type: object
      required:
        - type
        - name
        - create_billing_profile
        - api_key
      properties:
        type:
          type: string
          enum:
            - stripe
          description: Type of the app.
        name:
          type: string
          description: Name of the app.
        create_billing_profile:
          type: boolean
          description: |-
            If true, a billing profile will be created for the app. The Stripe app will be
            also set as the default billing profile if the current default is a Sandbox app.
        api_key:
          type: string
          description: API key for the app.
      additionalProperties: false
      description: Model for installing an app from the catalog with an API key.
    BillingInvoice:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingInvoiceStandard'
      discriminator:
        propertyName: type
        mapping:
          standard: '#/components/schemas/BillingInvoiceStandard'
      description: |-
        An invoice issued to a customer.

        The `type` field determines the concrete variant:

        - `standard`: a standard invoice for charges owed.
    BillingInvoiceAvailableActionDetails:
      type: object
      required:
        - resulting_state
      properties:
        resulting_state:
          type: string
          description: The extended status the invoice will transition to after performing this action.
          title: Resulting state
          readOnly: true
      additionalProperties: false
      description: Details about an available invoice action including the resulting state.
    BillingInvoiceAvailableActions:
      type: object
      properties:
        advance:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActionDetails'
          description: Advance the invoice to the next workflow step.
          title: Advance
          readOnly: true
        approve:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActionDetails'
          description: Approve the invoice for issuance.
          title: Approve
          readOnly: true
        delete:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActionDetails'
          description: Delete the invoice.
          title: Delete
          readOnly: true
        retry:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActionDetails'
          description: Retry a failed workflow step.
          title: Retry
          readOnly: true
        snapshot_quantities:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActionDetails'
          description: Snapshot the current usage quantities.
          title: Snapshot quantities
          readOnly: true
      additionalProperties: false
      description: |-
        The set of state-transition actions available for an invoice in its current
        status.

        A field is present only when that action is permitted from the current state.
    BillingInvoiceCustomer:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        usage_attribution:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerUsageAttribution'
          description: Mapping to attribute metered usage to the customer by the event subject.
          title: Usage Attribution
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: The billing address of the customer. Used for tax and invoicing.
          title: Billing Address
        id:
          $ref: '#/components/schemas/ULID'
        key:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceKey'
          description: |-
            Optional external resource key for the customer.

            Omitted when the customer was created without a key. Unlike on the customer
            resource itself, the key is optional here because the invoice snapshot may
            predate or omit it.
      additionalProperties: false
      description: Snapshot of the customer's information at the time the invoice was issued.
    BillingInvoiceDetailedLine:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - service_period
        - totals
        - category
        - quantity
        - unit_price
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The service period covered by this detailed line.
          title: Service period
          readOnly: true
        totals:
          allOf:
            - $ref: '#/components/schemas/BillingTotals'
          description: Aggregated financial totals for the detailed line.
          title: Totals
          readOnly: true
        category:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceDetailedLineCostCategory'
          description: The cost category of this detailed line.
          title: Category
          default: regular
          readOnly: true
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineDiscounts'
          description: Discounts applied to this detailed line.
          title: Discounts
          readOnly: true
        credits_applied:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceLineCreditsApplied'
          description: Credit applied to this detailed line.
          title: Credit applied
          readOnly: true
        external_references:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineExternalReferences'
          description: External identifiers for this detailed line.
          title: External references
          readOnly: true
        quantity:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The quantity of the detailed line.
          title: Quantity
          readOnly: true
        unit_price:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The unit price of the detailed line.
          title: Unit Price
          readOnly: true
      additionalProperties: false
      description: |-
        A detailed (child) sub-line belonging to a parent invoice line.

        Detailed lines represent the individual flat-fee components that make up a
        usage-based parent line after quantity snapshotting.
    BillingInvoiceDetailedLineCostCategory:
      type: string
      enum:
        - regular
        - commitment
      description: Cost category of a detailed invoice line item.
    BillingInvoiceDiscountReason:
      type: string
      enum:
        - maximum_spend
        - ratecard_percentage
        - ratecard_usage
      description: The reason a discount was applied to an invoice line.
    BillingInvoiceExternalReferences:
      type: object
      properties:
        invoicing_id:
          type: string
          description: The ID assigned by the external invoicing app (e.g. Stripe invoice ID).
          title: Invoicing ID
          readOnly: true
        payment_id:
          type: string
          description: The ID assigned by the external payment app (e.g. Stripe payment intent ID).
          title: Payment ID
          readOnly: true
      additionalProperties: false
      description: External identifiers assigned to an invoice by third-party systems.
    BillingInvoiceLine:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingInvoiceStandardLine'
      discriminator:
        propertyName: type
        mapping:
          standard_line: '#/components/schemas/BillingInvoiceStandardLine'
      description: |-
        A top-level line item on an invoice.

        Each line represents a single charge, typically associated with a rate card from
        a subscription. Detailed (child) lines are nested under `detailed_lines` when
        present.
    BillingInvoiceLineAmountDiscount:
      type: object
      required:
        - id
        - reason
        - amount
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Unique identifier for the discount.
          title: ID
          readOnly: true
        reason:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceDiscountReason'
          description: The reason this discount was applied.
          title: Reason
          readOnly: true
        description:
          type: string
          description: Optional human-readable description of the discount.
          title: Description
          readOnly: true
        external_references:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineExternalReferences'
          description: External identifiers for this discount.
          title: External references
          readOnly: true
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The monetary amount deducted.
          title: Amount
          readOnly: true
      additionalProperties: false
      description: A monetary amount discount applied to an invoice line item.
    BillingInvoiceLineCreditsApplied:
      type: object
      required:
        - amount
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The monetary amount credited.
          title: Amount
          readOnly: true
        description:
          type: string
          description: Optional human-readable description of the credit allocation.
          title: Description
          readOnly: true
      additionalProperties: false
      description: A credit allocation applied to an invoice line item.
    BillingInvoiceLineDiscounts:
      type: object
      properties:
        amount:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceLineAmountDiscount'
          description: Monetary amount discounts (e.g. from maximum spend commitments).
          title: Amount discounts
          readOnly: true
        usage:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceLineUsageDiscount'
          description: Usage quantity discounts (e.g. free tier usage allowances).
          title: Usage discounts
          readOnly: true
      additionalProperties: false
      description: Discounts applied to an invoice line item.
    BillingInvoiceLineExternalReferences:
      type: object
      properties:
        invoicing_id:
          type: string
          description: The ID assigned by the external invoicing app.
          title: Invoicing ID
          readOnly: true
      additionalProperties: false
      description: External identifiers for an invoice line item assigned by third-party systems.
    BillingInvoiceLineRateCard:
      type: object
      required:
        - price
      properties:
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price definition used to calculate charges for this line.
          title: Price
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardTaxConfig'
          description: Tax configuration snapshot for this line.
          title: Tax config
        feature_key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The feature key associated with this line's rate card.
          title: Feature key
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardDiscounts'
          description: Discount configuration from the rate card.
          title: Discounts
      additionalProperties: false
      description: Rate card configuration snapshot for a usage-based invoice line.
    BillingInvoiceLineUsageDiscount:
      type: object
      required:
        - id
        - reason
        - quantity
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Unique identifier for the discount.
          title: ID
          readOnly: true
        reason:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceDiscountReason'
          description: The reason this discount was applied.
          title: Reason
          readOnly: true
        description:
          type: string
          description: Optional human-readable description of the discount.
          title: Description
          readOnly: true
        external_references:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineExternalReferences'
          description: External identifiers for this discount.
          title: External references
          readOnly: true
        quantity:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The usage quantity deducted (in billing units).
          title: Quantity
          readOnly: true
      additionalProperties: false
      description: A usage quantity discount applied to an invoice line item.
    BillingInvoiceNumber:
      type: string
      minLength: 1
      maxLength: 256
      description: |-
        InvoiceNumber is a unique identifier for the invoice, generated by the invoicing
        app.

        The uniqueness depends on a lot of factors:

        - app setting (unique per app or unique per customer)
        - multiple app scenarios (multiple apps generating invoices with the same
        prefix)
      example: INV-2024-01-01-01
    BillingInvoiceStandard:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - number
        - currency
        - supplier
        - customer
        - totals
        - service_period
        - type
        - status
        - status_details
        - workflow
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        number:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceNumber'
          description: Human-readable invoice number generated by the invoicing app.
          title: Number
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Three-letter ISO 4217 currency code for the invoice.
          title: Currency
          readOnly: true
        supplier:
          allOf:
            - $ref: '#/components/schemas/BillingSupplier'
          description: |-
            Snapshot of the supplier's contact information at the time the invoice was
            issued.
          title: Supplier
        customer:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceCustomer'
          description: Snapshot of the customer's information at the time the invoice was issued.
          title: Customer
        totals:
          allOf:
            - $ref: '#/components/schemas/BillingTotals'
          description: Aggregated financial totals for the invoice.
          title: Totals
          readOnly: true
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: |-
            The service period covered by this invoice.

            For flat fee the service period can be empty which means `from` will be equals
            to `to`. In other cases those fields will be filled with the actual service
            period.
          title: Service period
          readOnly: true
        validation_issues:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceValidationIssue'
          description: |-
            Validation issues found during invoice processing.

            Present only when there are one or more validation findings. An empty list is
            omitted.
          title: Validation issues
          readOnly: true
        external_references:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceExternalReferences'
          description: External identifiers assigned to this invoice by third-party systems.
          title: External references
          readOnly: true
        type:
          type: string
          enum:
            - standard
          description: Discriminator field identifying this as a standard invoice.
          title: Type
        status:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceStandardStatus'
          description: Current lifecycle status of the invoice.
          title: Status
          readOnly: true
        status_details:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceStatusDetails'
          description: Detailed status information including available actions and workflow state.
          title: Status details
          readOnly: true
        issued_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when the invoice was issued to the customer.
          title: Issued at
          readOnly: true
        draft_until:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            Timestamp until which the invoice remains in draft state.

            The invoice advances automatically once this time is reached.
          title: Draft until
          readOnly: true
        quantity_snapshotted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when usage quantities were last snapshotted for this invoice.
          title: Quantity snapshotted at
          readOnly: true
        collection_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when collection was initiated for this invoice.
          title: Collection at
          readOnly: true
        due_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when payment is due.
          title: Due at
          readOnly: true
        sent_to_customer_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp when the invoice was sent to the customer.
          title: Sent to customer at
          readOnly: true
        workflow:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceWorkflowSettings'
          description: Workflow configuration snapshot captured at invoice creation time.
          title: Workflow
        lines:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceLine'
          description: |-
            Line items on this invoice.

            Always returned on single-resource GET; omitted on list endpoints unless
            explicitly expanded. Editable via update: existing lines are matched by `id`,
            lines without an `id` are created, and lines present on the invoice but omitted
            from the update request are deleted. Detailed (child) lines are always computed
            and cannot be edited directly.
          title: Lines
      additionalProperties: false
      description: A standard invoice for charges owed by the customer.
    BillingInvoiceStandardLine:
      type: object
      required:
        - name
        - created_at
        - updated_at
        - type
        - lifecycle_controller
        - service_period
        - totals
        - rate_card
        - detailed_lines
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: |-
            ID of the line.

            Optional on update: omit to create a new line, or supply the ID of an existing
            line to edit it. Existing lines omitted from an update's `lines` array are
            deleted.
          title: ID
        type:
          type: string
          enum:
            - standard_line
          description: The type of charge this line item represents.
          title: Type
        lifecycle_controller:
          allOf:
            - $ref: '#/components/schemas/BillingLifecycleController'
          description: |-
            Indicates whether this line item's lifecycle is controlled by OpenMeter or
            manually overridden by the API user.
          title: Lifecycle controller
          readOnly: true
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: |-
            The service period covered by this invoice, spanning the earliest line start to
            the latest line end across all of its lines.

            For an invoice with no lines the period is empty, which means `from` will be
            equal to `to`.
          title: Service period
        totals:
          allOf:
            - $ref: '#/components/schemas/BillingTotals'
          description: Aggregated financial totals for the line item.
          title: Totals
          readOnly: true
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineDiscounts'
          description: Discounts applied to this line item.
          title: Discounts
          readOnly: true
        credits_applied:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceLineCreditsApplied'
          description: Credit applied to this line item.
          title: Credit applied
          readOnly: true
        external_references:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineExternalReferences'
          description: External identifiers for this line item assigned by third-party systems.
          title: External references
          readOnly: true
        subscription:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionReference'
          description: Reference to the subscription item that generated this line.
          title: Subscription reference
          readOnly: true
        rate_card:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceLineRateCard'
          description: The rate card configuration snapshot used to price this line item.
          title: Rate card
        detailed_lines:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoiceDetailedLine'
          description: |-
            Detailed sub-lines that this line has been broken down into.

            Present when line has individual details.
          title: Detailed lines
          readOnly: true
        charge:
          allOf:
            - $ref: '#/components/schemas/BillingChargeReference'
          description: Reference to the charge associated with this line item.
          title: Charge
          readOnly: true
      additionalProperties: false
      description: |-
        A top-level line item on an invoice.

        Each line represents a single charge, typically associated with a rate card from
        a subscription. Detailed (child) lines are nested under `detailed_lines` when
        present.
    BillingInvoiceStandardStatus:
      type: string
      enum:
        - draft
        - issuing
        - issued
        - payment_processing
        - overdue
        - paid
        - uncollectible
        - voided
      description: Lifecycle status of a standard invoice.
    BillingInvoiceStatusDetails:
      type: object
      required:
        - immutable
        - failed
        - extended_status
        - available_actions
      properties:
        immutable:
          type: boolean
          description: Whether the invoice is immutable (i.e. cannot be modified or deleted).
          title: Immutable
          readOnly: true
        failed:
          type: boolean
          description: Whether the invoice is in a failed state.
          title: Failed
          readOnly: true
        extended_status:
          type: string
          description: |-
            Fine-grained internal status string providing additional workflow detail beyond
            the top-level status enum.
          title: Extended status
          readOnly: true
        available_actions:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceAvailableActions'
          description: The set of state-transition actions currently available for this invoice.
          title: Available actions
          readOnly: true
      additionalProperties: false
      description: Detailed status information for a standard invoice.
    BillingInvoiceValidationIssue:
      type: object
      required:
        - code
        - message
        - severity
      properties:
        code:
          type: string
          description: Machine-readable error code.
          title: Code
          readOnly: true
        message:
          type: string
          description: Human-readable description of the error.
          title: Message
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          description: Additional structured context.
          title: Attributes
          readOnly: true
        severity:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceValidationIssueSeverity'
          description: Severity of the validation issue.
          title: Severity
          readOnly: true
        field:
          type: string
          description: |-
            JSON path to the field that caused this validation issue, if applicable.

            For example: `lines/0/rate_card/price`.
          title: Field path
          readOnly: true
      additionalProperties: false
      description: |-
        A validation issue found during invoice processing.

        Converges on the same structure used by plan and subscription validation errors:
        a machine-readable `code`, a human-readable `message`, optional structured
        `attributes`, plus a `severity` and optional `field` path.
    BillingInvoiceValidationIssueSeverity:
      type: string
      enum:
        - critical
        - warning
      description: Severity level of an invoice validation issue.
    BillingInvoiceWorkflow:
      type: object
      properties:
        invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceWorkflowInvoicingSettings'
          description: Invoicing settings for this invoice.
          title: Invoicing settings
        payment:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowPaymentSettings'
          description: Payment settings for this invoice.
          title: Payment settings
      additionalProperties: false
      description: |-
        Invoice-level snapshot of the workflow configuration.

        Contains only the settings that are meaningful for an already-created invoice:
        invoicing behaviour and payment settings. Collection alignment and tax policy
        are gather-time / profile-wide concerns and are not included.
    BillingInvoiceWorkflowAppsReferences:
      type: object
      required:
        - tax
        - invoicing
        - payment
      properties:
        tax:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The tax app used for this workflow
          readOnly: true
        invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The invoicing app used for this workflow
          readOnly: true
        payment:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The payment app used for this workflow
          readOnly: true
      additionalProperties: false
      description: |-
        BillingInvoiceWorkflowAppsReferences represents the references (id) to the apps
        used by a billing profile
    BillingInvoiceWorkflowInvoicingSettings:
      type: object
      properties:
        auto_advance:
          type: boolean
          description: Whether to automatically issue the invoice after the draft_period has passed.
          default: true
        draft_period:
          type: string
          format: ISO8601
          description: The period for the invoice to be kept in draft status for manual reviews.
          example: P1D
          default: P0D
        due_after:
          type: string
          format: ISO8601
          description: The period after which the invoice is considered overdue if not paid.
          example: P30D
          readOnly: true
      additionalProperties: false
      description: |-
        Invoice-level invoicing settings.

        A subset of BillingWorkflowInvoicingSettings limited to fields that are
        meaningful per-invoice. progressive_billing is omitted as it is a gather-time /
        profile-level decision.
    BillingInvoiceWorkflowSettings:
      type: object
      required:
        - source_billing_profile
        - workflow
      properties:
        apps:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceWorkflowAppsReferences'
          description: The apps that will be used to orchestrate the invoice's workflow.
          title: Application that generated the invoice
          readOnly: true
        source_billing_profile:
          allOf:
            - $ref: '#/components/schemas/BillingProfileReference'
          description: The billing profile that was the source of this workflow snapshot.
          title: Source billing profile
          readOnly: true
        workflow:
          allOf:
            - $ref: '#/components/schemas/BillingInvoiceWorkflow'
          description: |-
            The workflow configuration that was active when the invoice was created.

            Only the fields that are meaningful at the per-invoice level are included:
            invoicing behaviour (auto-advance, draft period) and payment settings
            (collection method, due date). Profile-wide settings such as collection
            alignment, progressive billing, and tax policy are omitted.
          title: Workflow config
      additionalProperties: false
      description: Snapshot of the billing workflow configuration captured at invoice creation.
    BillingLifecycleController:
      type: string
      enum:
        - system
        - manual
      description: |-
        Identifies whether a resource lifecycle is controlled by OpenMeter or manually
        overridden by the API user.

        Values:

        - `system`: The resource lifecycle is controlled by OpenMeter.
        - `manual`: The resource lifecycle was manually overridden by the API user.
      title: Lifecycle controller
    BillingParty:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the party.
          readOnly: true
        key:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceKey'
          description: An optional unique key of the party.
        name:
          type: string
          description: Legal name or representation of the party.
        tax_id:
          allOf:
            - $ref: '#/components/schemas/BillingPartyTaxIdentity'
          description: |-
            The entity's legal identification used for tax purposes. They may have other
            numbers, but we're only interested in those valid for tax purposes.
        addresses:
          allOf:
            - $ref: '#/components/schemas/BillingPartyAddresses'
          description: Address for where information should be sent if needed.
      additionalProperties: false
      description: Party represents a person or business entity.
    BillingPartyAddresses:
      type: object
      required:
        - billing_address
      properties:
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: Billing address.
      additionalProperties: false
      description: A collection of addresses for the party.
    BillingPartyTaxIdentity:
      type: object
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/BillingTaxIdentificationCode'
          description: Normalized tax identification code shown on the original identity document.
      additionalProperties: false
      description: |-
        Identity stores the details required to identify an entity for tax purposes in a
        specific country.
    BillingPlan:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
        - version
        - currency
        - billing_cadence
        - status
        - phases
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: |-
            A key is a semi-unique string that is used to identify the plan. It is used to
            reference the latest `active` version of the plan and is unique with the version
            number.
          title: Key
        version:
          type: integer
          minimum: 1
          description: |-
            Plans are versioned to allow you to make changes without affecting running
            subscriptions.
          title: Version
          default: 1
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency code of the plan.
          title: Currency
        billing_cadence:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: The billing cadence for subscriptions using this plan.
          title: Billing cadence
        pro_rating_enabled:
          type: boolean
          description: Whether pro-rating is enabled for this plan.
          title: Pro-rating enabled
          default: true
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The date and time when the plan becomes `active`. When not specified, the plan
            is in `draft` status.
          title: Effective start date
          readOnly: true
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            A scheduled date and time when the plan becomes `archived`. When not specified,
            the plan is in `active` status indefinitely.
          title: Effective end date
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingPlanStatus'
          description: |-
            The status of the plan. Computed based on the effective start and end dates:

            - `draft`: `effective_from` is not set.
            - `scheduled`: `now < effective_from`.
            - `active`: `effective_from <= now` and (`effective_to` is not set or
            `now < effective_to`).
            - `archived`: `effective_to <= now`.
          title: Status
          readOnly: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanPhase'
          minItems: 1
          description: |-
            The plan phases define the pricing ramp for a subscription. A phase switch
            occurs only at the end of a billing period. At least one phase is required.
          title: Plan phases
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: |-
            Settlement mode for plan.

            Values:

            - `credit_then_invoice`: Credits are applied first, then any remainder is
            invoiced.
            - `credit_only`: Usage is settled exclusively against credits.
          title: Settlement Mode
          default: credit_then_invoice
          readOnly: true
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalogValidationError'
          description: |-
            List of validation errors in `draft` state that prevent the plan from being
            published.
          title: Validation errors
          readOnly: true
      additionalProperties: false
      description: Plans provide a template for subscriptions.
    BillingPlanPhase:
      type: object
      required:
        - name
        - key
        - rate_cards
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ResourceKey'
        duration:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: |-
            The duration of the phase. When not specified, the phase runs indefinitely. Only
            the last phase may omit the duration.
          title: Duration
        rate_cards:
          type: array
          items:
            $ref: '#/components/schemas/BillingRateCard'
          description: The rate cards of the plan.
          title: Rate cards
      additionalProperties: false
      description: |-
        The plan phase or pricing ramp allows changing a plan's rate cards over time as
        a subscription progresses.
    BillingPlanStatus:
      type: string
      enum:
        - draft
        - active
        - archived
        - scheduled
      description: |-
        The status of a plan.

        - `draft`: The plan has not yet been published and can be edited.
        - `active`: The plan is published and can be used in subscriptions.
        - `archived`: The plan is no longer available for use.
        - `scheduled`: The plan is scheduled to be published at a future date.
    BillingPrice:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingPriceFree'
        - $ref: '#/components/schemas/BillingPriceFlat'
        - $ref: '#/components/schemas/BillingPriceUnit'
        - $ref: '#/components/schemas/BillingPriceGraduated'
        - $ref: '#/components/schemas/BillingPriceVolume'
      discriminator:
        propertyName: type
        mapping:
          free: '#/components/schemas/BillingPriceFree'
          flat: '#/components/schemas/BillingPriceFlat'
          unit: '#/components/schemas/BillingPriceUnit'
          graduated: '#/components/schemas/BillingPriceGraduated'
          volume: '#/components/schemas/BillingPriceVolume'
      description: Price.
    BillingPriceFlat:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          enum:
            - flat
          description: The type of the price.
          title: Type
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The amount of the flat price.
          title: Amount
      additionalProperties: false
      description: Flat price.
    BillingPriceFree:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - free
          description: The type of the price.
          title: Type
      additionalProperties: false
      description: Free price.
    BillingPriceGraduated:
      type: object
      required:
        - type
        - tiers
      properties:
        type:
          type: string
          enum:
            - graduated
          description: The type of the price.
          title: Type
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/BillingPriceTier'
          minItems: 1
          description: The tiers of the graduated price. At least one tier is required.
          title: Tiers
      additionalProperties: false
      description: |-
        Graduated tiered price.

        Each tier's rate applies only to the usage within that tier. Pricing can change
        as cumulative usage crosses tier boundaries.

        When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
        expressed in converted billing units.
    BillingPricePaymentTerm:
      type: string
      enum:
        - in_advance
        - in_arrears
      description: The payment term of a flat price.
    BillingPriceTier:
      type: object
      properties:
        up_to_amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Up to and including this quantity will be contained in the tier. If undefined,
            the tier is open-ended (the last tier).
          title: Up to quantity
        flat_price:
          allOf:
            - $ref: '#/components/schemas/BillingPriceFlat'
          description: The flat price component of the tier. Charged once when the tier is entered.
          title: Flat price component
        unit_price:
          allOf:
            - $ref: '#/components/schemas/BillingPriceUnit'
          description: The unit price component of the tier. Charged per billing unit within the tier.
          title: Unit price component
      additionalProperties: false
      description: |-
        A price tier used in graduated and volume pricing.

        At least one price component (flat_price or unit_price) must be set. When
        UnitConfig is present on the rate card, up_to_amount is expressed in converted
        billing units.
    BillingPriceUnit:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          enum:
            - unit
          description: The type of the price.
          title: Type
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The amount of the unit price.
          title: Amount
      additionalProperties: false
      description: |-
        Unit price.

        Charges a fixed rate per billing unit. When UnitConfig is present on the rate
        card, billing units are the converted quantities (e.g. GB instead of bytes).
    BillingPriceVolume:
      type: object
      required:
        - type
        - tiers
      properties:
        type:
          type: string
          enum:
            - volume
          description: The type of the price.
          title: Type
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/BillingPriceTier'
          minItems: 1
          description: The tiers of the volume price. At least one tier is required.
          title: Tiers
      additionalProperties: false
      description: |-
        Volume tiered price.

        The maximum quantity within a period determines the per-unit price for all units
        in that period.

        When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
        expressed in converted billing units.
    BillingProfile:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - supplier
        - workflow
        - apps
        - default
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        supplier:
          allOf:
            - $ref: '#/components/schemas/BillingParty'
          description: |-
            The name and contact information for the supplier this billing profile
            represents
        workflow:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflow'
          description: The billing workflow settings for this profile
        apps:
          allOf:
            - $ref: '#/components/schemas/BillingProfileAppReferences'
          description: The applications used by this billing profile.
        default:
          type: boolean
          description: Whether this is the default profile.
      additionalProperties: false
      description: |-
        Billing profiles contain the settings for billing and controls invoice
        generation.
    BillingProfileAppReferences:
      type: object
      required:
        - tax
        - invoicing
        - payment
      properties:
        tax:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The tax app used for this workflow.
        invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The invoicing app used for this workflow.
        payment:
          allOf:
            - $ref: '#/components/schemas/BillingAppReference'
          description: The payment app used for this workflow.
      additionalProperties: false
      description: References to the applications used by a billing profile.
    BillingProfilePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingProfile'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    BillingProfileReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The ID of the billing profile.
      additionalProperties: false
      description: Billing profile reference.
    BillingRateCard:
      type: object
      required:
        - name
        - key
        - price
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ResourceKey'
        feature:
          allOf:
            - $ref: '#/components/schemas/FeatureReference'
          description: The feature associated with the rate card.
          title: Feature reference
        billing_cadence:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: |-
            The billing cadence of the rate card. When null, the charge is one-time
            (non-recurring). Only valid for flat prices.
          title: Billing cadence
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price of the rate card.
          title: Price
        unit_config:
          allOf:
            - $ref: '#/components/schemas/BillingUnitConfig'
          description: |-
            Unit conversion configuration for the rate card.

            Synthesized on read for plans authored with v1 dynamic or package prices:
            dynamic prices map to a unit price with a multiply unit config, and package
            prices map to a unit price with a divide unit config.

            Accepted on create and update only when the UnitConfig feature is enabled on the
            deployment; otherwise rejected.
          title: Unit config
        payment_term:
          allOf:
            - $ref: '#/components/schemas/BillingPricePaymentTerm'
          description: |-
            The payment term of the rate card. In advance payment term can only be used for
            flat prices.
          title: Payment term
          default: in_arrears
        commitments:
          allOf:
            - $ref: '#/components/schemas/BillingSpendCommitments'
          description: |-
            Spend commitments for this rate card. Only applicable to usage-based prices
            (unit, graduated, volume).
          title: Commitments
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardDiscounts'
          description: The discounts of the rate card.
          title: Discounts
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardTaxConfig'
          description: The tax config of the rate card.
          title: Tax config
        entitlement:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardEntitlement'
          description: |-
            The entitlement template granted to subscribers of a plan or addon containing
            this rate card. Requires `feature` to be set.
          title: Entitlement template
      additionalProperties: false
      description: A rate card defines the pricing and entitlement of a feature or service.
    BillingRateCardBooleanEntitlement:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - boolean
          description: The type of the entitlement template.
          title: Type
      additionalProperties: false
      description: The entitlement template of a boolean entitlement.
    BillingRateCardDiscounts:
      type: object
      properties:
        percentage:
          type: number
          minimum: 0
          maximum: 100
          description: Percentage discount applied to the price (0–100).
        usage:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Number of usage units granted free before billing starts. Only applies to
            usage-based lines (not flat fees). Usage is treated as zero until this amount is
            exhausted.
      additionalProperties: false
      description: Discount configuration for a rate card.
    BillingRateCardEntitlement:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingRateCardMeteredEntitlement'
        - $ref: '#/components/schemas/BillingRateCardStaticEntitlement'
        - $ref: '#/components/schemas/BillingRateCardBooleanEntitlement'
      discriminator:
        propertyName: type
        mapping:
          metered: '#/components/schemas/BillingRateCardMeteredEntitlement'
          static: '#/components/schemas/BillingRateCardStaticEntitlement'
          boolean: '#/components/schemas/BillingRateCardBooleanEntitlement'
      description: |-
        Entitlement template configured on a rate card. The feature is taken from the
        rate card itself, so it is omitted here.
    BillingRateCardMeteredEntitlement:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - metered
          description: The type of the entitlement template.
          title: Type
        is_soft_limit:
          type: boolean
          description: |-
            If soft limit is true, the subject can use the feature even if the entitlement
            is exhausted; access remains granted.
          title: Soft limit
          default: false
        limit:
          type: number
          format: double
          minimum: 0
          description: |-
            The amount of usage granted each usage period, in the feature's unit. Usage is
            counted against this allowance and the balance resets every usage period. When
            `is_soft_limit` is true the subject keeps access after the limit is reached;
            otherwise access is denied once the allowance is exhausted.
          title: Usage limit
        usage_period:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: |-
            The reset interval of the metered entitlement in ISO8601 format. Defaults to the
            billing cadence of the rate card.
          title: Usage period
      additionalProperties: false
      description: The entitlement template of a metered entitlement.
    BillingRateCardProrationConfiguration:
      type: object
      required:
        - mode
      properties:
        mode:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardProrationMode'
          description: The proration mode of the rate card.
          title: Proration mode
      additionalProperties: false
      description: The proration configuration of the rate card.
    BillingRateCardProrationMode:
      type: string
      enum:
        - no_proration
        - prorate_prices
      description: |-
        The proration mode of the rate card.

        Values:

        - `no_proration`: No proration.
        - `prorate_prices`: Prorate the price based on the time remaining in the billing
        period.
    BillingRateCardStaticEntitlement:
      type: object
      required:
        - type
        - config
      properties:
        type:
          type: string
          enum:
            - static
          description: The type of the entitlement template.
          title: Type
        config:
          description: |-
            The entitlement config as a JSON object. Returned when checking entitlement
            access; useful for configuring fine-grained access settings implemented in your
            own system.
          title: Config
      additionalProperties: false
      description: The entitlement template of a static entitlement.
    BillingRateCardTaxConfig:
      type: object
      required:
        - code
      properties:
        behavior:
          $ref: '#/components/schemas/BillingTaxBehavior'
        code:
          $ref: '#/components/schemas/TaxCodeReference'
      additionalProperties: false
      description: The tax config of the rate card.
    BillingSettlementMode:
      type: string
      enum:
        - credit_then_invoice
        - credit_only
      description: |-
        Settlement mode for billing.

        Values:

        - `credit_then_invoice`: Credits are applied first, then any remainder is
        invoiced.
        - `credit_only`: Usage is settled exclusively against credits.
      title: Settlement mode
    BillingSpendCommitments:
      type: object
      properties:
        minimum_amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The customer is committed to spend at least the amount.
          title: Minimum amount
        maximum_amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The customer is limited to spend at most the amount.
          title: Maximum amount
      additionalProperties: false
      description: |-
        Spend commitments for a rate card. The customer is committed to spend at least
        the minimum amount and at most the maximum amount.
    BillingSubscription:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - customer_id
        - billing_anchor
        - status
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        customer_id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The customer ID of the subscription.
          title: Customer ID
          readOnly: true
        plan_id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The plan ID of the subscription. Set if subscription is created from a plan.
          title: Plan ID
          readOnly: true
        billing_anchor:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            A billing anchor is the fixed point in time that determines the subscription's
            recurring billing cycle. It affects when charges occur and how prorations are
            calculated. Common anchors:

            - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
            - Subscription anniversary (day customer signed up)
            - Custom date (customer-specified day)
          title: Billing anchor
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionStatus'
          description: The status of the subscription.
          title: Status
          readOnly: true
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: |-
            Settlement mode for billing.

            Values:

            - `credit_then_invoice`: Credits are applied first, then any remainder is
            invoiced.
            - `credit_only`: Usage is settled exclusively against credits.
          title: Settlement Mode
      additionalProperties: false
      description: Subscription.
    BillingSubscriptionCancel:
      type: object
      properties:
        timing:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionEditTiming'
          description: If not provided the subscription is canceled immediately.
          default: immediate
      additionalProperties: false
      description: Request for canceling a subscription.
    BillingSubscriptionChange:
      type: object
      required:
        - customer
        - plan
        - timing
      properties:
        labels:
          $ref: '#/components/schemas/Labels'
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: |-
            Settlement mode for billing.

            Values:

            - `credit_then_invoice`: Credits are applied first, then any remainder is
            invoiced.
            - `credit_only`: Usage is settled exclusively against credits.
          title: Settlement Mode
        customer:
          type: object
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: |-
                The ID of the customer to create the subscription for.

                Either customer ID or customer key must be provided. If both are provided, the
                ID will be used.
              title: Customer ID
            key:
              allOf:
                - $ref: '#/components/schemas/ExternalResourceKey'
              description: |-
                The key of the customer to create the subscription for.

                Either customer ID or customer key must be provided. If both are provided, the
                ID will be used.
              title: Customer Key
          additionalProperties: false
          description: The customer to create the subscription for.
        plan:
          type: object
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: |-
                The plan ID of the subscription. Set if subscription is created from a plan.

                ID or Key of the plan is required if creating a subscription from a plan. If
                both are provided, the ID will be used.
              title: Plan ID
            key:
              allOf:
                - $ref: '#/components/schemas/ResourceKey'
              description: |-
                The plan Key of the subscription, if any. Set if subscription is created from a
                plan.

                ID or Key of the plan is required if creating a subscription from a plan. If
                both are provided, the ID will be used.
              title: Plan Key
            version:
              type: integer
              description: |-
                The plan version of the subscription, if any. If not provided, the latest
                version of the plan will be used.
              title: Plan Version
          additionalProperties: false
          description: The plan reference of the subscription.
        billing_anchor:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            A billing anchor is the fixed point in time that determines the subscription's
            recurring billing cycle. It affects when charges occur and how prorations are
            calculated. Common anchors:

            - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
            - Subscription anniversary (day customer signed up)
            - Custom date (customer-specified day)

            If not provided, the subscription will be created with the subscription's
            creation time as the billing anchor.
          title: Billing anchor
        timing:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionEditTiming'
          description: |-
            Timing configuration for the change, when the change should take effect. For
            changing a subscription, the accepted values depend on the subscription
            configuration.
      additionalProperties: false
      description: Request for changing a subscription.
    BillingSubscriptionChangeResponse:
      type: object
      required:
        - current
        - next
      properties:
        current:
          allOf:
            - $ref: '#/components/schemas/BillingSubscription'
          description: The current subscription before the change.
        next:
          allOf:
            - $ref: '#/components/schemas/BillingSubscription'
          description: The new state of the subscription after the change.
      additionalProperties: false
      description: Response for changing a subscription.
    BillingSubscriptionCreate:
      type: object
      required:
        - customer
        - plan
      properties:
        labels:
          $ref: '#/components/schemas/Labels'
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: |-
            Settlement mode for billing.

            Values:

            - `credit_then_invoice`: Credits are applied first, then any remainder is
            invoiced.
            - `credit_only`: Usage is settled exclusively against credits.
          title: Settlement Mode
        customer:
          type: object
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: |-
                The ID of the customer to create the subscription for.

                Either customer ID or customer key must be provided. If both are provided, the
                ID will be used.
              title: Customer ID
            key:
              allOf:
                - $ref: '#/components/schemas/ExternalResourceKey'
              description: |-
                The key of the customer to create the subscription for.

                Either customer ID or customer key must be provided. If both are provided, the
                ID will be used.
              title: Customer Key
          additionalProperties: false
          description: The customer to create the subscription for.
        plan:
          type: object
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: |-
                The plan ID of the subscription. Set if subscription is created from a plan.

                ID or Key of the plan is required if creating a subscription from a plan. If
                both are provided, the ID will be used.
              title: Plan ID
            key:
              allOf:
                - $ref: '#/components/schemas/ResourceKey'
              description: |-
                The plan Key of the subscription, if any. Set if subscription is created from a
                plan.

                ID or Key of the plan is required if creating a subscription from a plan. If
                both are provided, the ID will be used.
              title: Plan Key
            version:
              type: integer
              description: |-
                The plan version of the subscription, if any. If not provided, the latest
                version of the plan will be used.
              title: Plan Version
          additionalProperties: false
          description: The plan reference of the subscription.
        billing_anchor:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            A billing anchor is the fixed point in time that determines the subscription's
            recurring billing cycle. It affects when charges occur and how prorations are
            calculated. Common anchors:

            - Calendar month (1st of each month): `2025-01-01T00:00:00Z`
            - Subscription anniversary (day customer signed up)
            - Custom date (customer-specified day)

            If not provided, the subscription will be created with the subscription's
            creation time as the billing anchor.
          title: Billing anchor
      additionalProperties: false
      description: Subscription create request.
    BillingSubscriptionEditTiming:
      oneOf:
        - $ref: '#/components/schemas/BillingSubscriptionEditTimingEnum'
        - $ref: '#/components/schemas/DateTime'
      description: |-
        Subscription edit timing defined when the changes should take effect. If the
        provided configuration is not supported by the subscription, an error will be
        returned.
      example: immediate
    BillingSubscriptionEditTimingEnum:
      type: string
      enum:
        - immediate
        - next_billing_cycle
      description: |-
        Subscription edit timing. When immediate, the requested changes take effect
        immediately. When next_billing_cycle, the requested changes take effect at the
        next billing cycle.
    BillingSubscriptionReference:
      type: object
      required:
        - id
        - phase
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The ID of the subscription.
          title: Subscription ID
          readOnly: true
        phase:
          type: object
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: The ID of the phase.
              title: Phase ID
              readOnly: true
            item:
              type: object
              properties:
                id:
                  allOf:
                    - $ref: '#/components/schemas/ULID'
                  description: The ID of the item.
                  title: Item ID
                  readOnly: true
              required:
                - id
              additionalProperties: false
              description: The item of the phase.
              title: Item ID
              readOnly: true
          required:
            - id
            - item
          additionalProperties: false
          description: The phase of the subscription.
          title: Phase ID
          readOnly: true
      additionalProperties: false
      description: |-
        Subscription reference represents a reference to the specific subscription item
        this entity represents.
    BillingSubscriptionStatus:
      type: string
      enum:
        - active
        - inactive
        - canceled
        - scheduled
      description: Subscription status.
    BillingSupplier:
      type: object
      properties:
        name:
          type: string
          description: Legal name or representation of the party.
        tax_id:
          allOf:
            - $ref: '#/components/schemas/BillingPartyTaxIdentity'
          description: |-
            The entity's legal identification used for tax purposes. They may have other
            numbers, but we're only interested in those valid for tax purposes.
        addresses:
          allOf:
            - $ref: '#/components/schemas/BillingPartyAddresses'
          description: Address for where information should be sent if needed.
        id:
          type: string
          description: Unique identifier for the party.
      additionalProperties: false
      description: |-
        Snapshot of the supplier's information at the time the invoice was issued.

        Structurally a read-only subset of `BillingParty` (the type configured on the
        billing profile), so the snapshot stays aligned with the source. `key` is
        omitted because it is not part of the snapshotted supplier data.
    BillingTaxBehavior:
      type: string
      enum:
        - inclusive
        - exclusive
      description: |-
        Tax behavior.

        This enum is used to specify whether tax is included in the price or excluded
        from the price.
    BillingTaxCode:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
        - app_mappings
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          $ref: '#/components/schemas/ResourceKey'
        app_mappings:
          type: array
          items:
            $ref: '#/components/schemas/BillingTaxCodeAppMapping'
          description: Mapping of app types to tax codes.
          title: App type to tax code mappings
      additionalProperties: false
      description: Tax codes by provider.
    BillingTaxCodeAppMapping:
      type: object
      required:
        - app_type
        - tax_code
      properties:
        app_type:
          allOf:
            - $ref: '#/components/schemas/BillingAppType'
          description: The app type that the tax code is associated with.
          title: App type
        tax_code:
          type: string
          description: Tax code.
          title: Tax code
      additionalProperties: false
      description: Mapping of app types to tax codes.
    BillingTaxConfig:
      type: object
      properties:
        behavior:
          allOf:
            - $ref: '#/components/schemas/BillingTaxBehavior'
          description: |-
            Tax behavior.

            If not specified the billing profile is used to determine the tax behavior. If
            not specified in the billing profile, the provider's default behavior is used.
          title: Tax behavior
        stripe:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfigStripe'
          description: Stripe tax config.
          title: Stripe tax config
          deprecated: true
        external_invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfigExternalInvoicing'
          description: External invoicing tax config.
          title: External invoicing tax config
          deprecated: true
        tax_code_id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Tax code ID.
          title: Tax code ID
          deprecated: true
        tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: |-
            Tax code reference.

            When both `tax_code` and `tax_code_id` are provided, `tax_code` takes
            precedence. When `stripe.code` is also provided, `tax_code` still wins and
            `stripe.code` is ignored.
          title: Tax code
      additionalProperties: false
      description: Set of provider specific tax configs.
    BillingTaxConfigExternalInvoicing:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          maxLength: 64
          description: The tax code should be interpreted by the external invoicing provider.
          title: Tax code
      additionalProperties: false
      description: External invoicing tax config.
    BillingTaxConfigStripe:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          pattern: ^txcd_\d{8}$
          description: Product [tax code](https://docs.stripe.com/tax/tax-codes).
          title: Tax code
          example: txcd_10000000
      additionalProperties: false
      description: The tax config for Stripe.
    BillingTaxIdentificationCode:
      type: string
      minLength: 1
      maxLength: 32
      description: |-
        Tax identifier code is a normalized tax code shown on the original identity
        document.
    BillingTotals:
      type: object
      required:
        - amount
        - taxes_total
        - taxes_inclusive_total
        - taxes_exclusive_total
        - charges_total
        - discounts_total
        - credits_total
        - total
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total value of the resource before taxes, discounts and commitments.
          title: Amount
          readOnly: true
        taxes_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total tax amount applied to the resource.
          title: Taxes total
          readOnly: true
        taxes_inclusive_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total tax amount already included in the resource amount.
          title: Inclusive taxes total
          readOnly: true
        taxes_exclusive_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total tax amount added on top of the resource amount.
          title: Exclusive taxes total
          readOnly: true
        charges_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total amount contributed by additional charges.
          title: Charges total
          readOnly: true
        discounts_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total amount deducted through discounts.
          title: Discounts total
          readOnly: true
        credits_total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The total amount deducted through credits before taxes are applied.
          title: Credits total
          readOnly: true
        total:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The final total value of the resource after taxes, discounts and commitments.
          title: Total
          readOnly: true
      additionalProperties: false
      description: Totals contains the summaries of all calculations for a billing resource.
    BillingUnitConfig:
      type: object
      required:
        - operation
        - conversion_factor
      properties:
        operation:
          allOf:
            - $ref: '#/components/schemas/BillingUnitConfigOperation'
          description: The arithmetic operation to apply to the raw metered quantity.
          title: Conversion operation
        conversion_factor:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            The factor used in the conversion operation.

            - For `divide`: `converted = raw / conversionFactor`.
            - For `multiply`: `converted = raw × conversionFactor`.

            Must be a positive non-zero value.
          title: Conversion factor
        rounding:
          allOf:
            - $ref: '#/components/schemas/BillingUnitConfigRoundingMode'
          description: |-
            The rounding mode applied to the converted quantity for invoicing.

            Defaults to none (no rounding). Entitlement checks always use the precise
            (unrounded) value.
          title: Rounding mode
          default: none
        precision:
          type: integer
          description: |-
            The number of decimal places to retain after rounding.

            Only meaningful when rounding is not "none". Defaults to 0 (round to whole
            numbers).
          title: Rounding precision (decimal places)
          default: 0
        display_unit:
          type: string
          description: |-
            A human-readable label for the converted unit shown on invoices and in the
            customer portal (e.g., "GB", "hours", "M tokens").

            Optional. When omitted, no unit label is rendered.
          title: Display unit label
      additionalProperties: false
      description: |-
        Unit conversion configuration.

        Transforms raw metered quantities into billing-ready units before pricing and
        entitlement evaluation. Applied at the rate card level so the same feature can
        be billed in different units across plans.

        Examples:

        - Meter bytes, bill GB: operation=divide, conversionFactor=1e9,
        rounding=ceiling, displayUnit="GB"
        - Meter seconds, bill hours: operation=divide, conversionFactor=3600,
        rounding=ceiling, displayUnit="hours"
        - Cost + 20% margin: operation=multiply, conversionFactor=1.2
        - Bill per million tokens: operation=divide, conversionFactor=1e6,
        rounding=ceiling, displayUnit="M"

        v1 equivalents:

        - DynamicPrice(multiplier): operation=multiply, conversionFactor=multiplier +
        UnitPrice(amount=1)
        - PackagePrice(amount, quantityPerPkg): operation=divide,
        conversionFactor=quantityPerPkg, rounding=ceiling + UnitPrice(amount)
    BillingUnitConfigOperation:
      type: string
      enum:
        - divide
        - multiply
      description: |-
        The arithmetic operation used to convert raw metered units into billing units.

        - `divide`: Divide the metered quantity by the conversion factor (e.g., bytes ÷
        1e9 = GB).
        - `multiply`: Multiply the metered quantity by the conversion factor (e.g., cost
        × 1.2 = cost + 20% margin).
    BillingUnitConfigRoundingMode:
      type: string
      enum:
        - ceiling
        - floor
        - half_up
        - none
      description: |-
        The rounding mode applied to the converted quantity for invoicing.

        Rounding is applied only to the invoiced quantity. Entitlement balance checks
        use the precise decimal value after conversion.

        - `ceiling`: Round up to the next integer (typical for package-style billing).
        - `floor`: Round down to the previous integer.
        - `half_up`: Round to the nearest integer, with 0.5 rounding up.
        - `none`: No rounding; the converted value is used as-is.
    BillingWorkflow:
      type: object
      properties:
        collection:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowCollectionSettings'
          description: The collection settings for this workflow
        invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowInvoicingSettings'
          description: The invoicing settings for this workflow
        payment:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowPaymentSettings'
          description: The payment settings for this workflow
        tax:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowTaxSettings'
          description: The tax settings for this workflow
      additionalProperties: false
      description: Billing workflow settings.
    BillingWorkflowCollectionAlignment:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingWorkflowCollectionAlignmentSubscription'
        - $ref: '#/components/schemas/BillingWorkflowCollectionAlignmentAnchored'
      discriminator:
        propertyName: type
        mapping:
          subscription: '#/components/schemas/BillingWorkflowCollectionAlignmentSubscription'
          anchored: '#/components/schemas/BillingWorkflowCollectionAlignmentAnchored'
      description: |-
        The alignment for collecting the pending line items into an invoice.

        Defaults to subscription, which means that we are to create a new invoice every
        time the a subscription period starts (for in advance items) or ends (for in
        arrears items).
    BillingWorkflowCollectionAlignmentAnchored:
      type: object
      required:
        - type
        - recurring_period
      properties:
        type:
          type: string
          enum:
            - anchored
          description: The type of alignment.
        recurring_period:
          allOf:
            - $ref: '#/components/schemas/RecurringPeriod'
          description: The recurring period for the alignment.
      additionalProperties: false
      description: |-
        BillingWorkflowCollectionAlignmentAnchored specifies the alignment for
        collecting the pending line items into an invoice.
    BillingWorkflowCollectionAlignmentSubscription:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - subscription
          description: The type of alignment.
      additionalProperties: false
      description: |-
        BillingWorkflowCollectionAlignmentSubscription specifies the alignment for
        collecting the pending line items into an invoice.
    BillingWorkflowCollectionSettings:
      type: object
      properties:
        alignment:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowCollectionAlignment'
          description: The alignment for collecting the pending line items into an invoice.
          default:
            type: subscription
        interval:
          type: string
          format: ISO8601
          description: |-
            This grace period can be used to delay the collection of the pending line items
            specified in alignment.

            This is useful, in case of multiple subscriptions having slightly different
            billing periods.
          example: P1D
          default: PT1H
      additionalProperties: false
      description: |-
        Workflow collection specifies how to collect the pending line items for an
        invoice.
      title: Workflow collection settings
    BillingWorkflowInvoicingSettings:
      type: object
      properties:
        auto_advance:
          type: boolean
          description: Whether to automatically issue the invoice after the draftPeriod has passed.
          default: true
        draft_period:
          type: string
          format: ISO8601
          description: The period for the invoice to be kept in draft status for manual reviews.
          example: P1D
          default: P0D
        progressive_billing:
          type: boolean
          description: Should progressive billing be allowed for this workflow?
          default: true
        subscription_end_proration_mode:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflowInvoicingSubscriptionEndProrationMode'
          description: Controls how subscription-ending shortened service periods are billed.
          default: bill_actual_period
      additionalProperties: false
      description: Invoice settings for a billing workflow.
      title: Workflow invoice settings
    BillingWorkflowInvoicingSubscriptionEndProrationMode:
      type: string
      enum:
        - bill_full_period
        - bill_actual_period
      description: Billing workflow subscription end proration mode.
    BillingWorkflowPaymentChargeAutomaticallySettings:
      type: object
      required:
        - collection_method
      properties:
        collection_method:
          type: string
          enum:
            - charge_automatically
          description: The collection method for the invoice.
      additionalProperties: false
      description: |-
        Payment settings for a billing workflow when the collection method is charge
        automatically.
    BillingWorkflowPaymentSendInvoiceSettings:
      type: object
      required:
        - collection_method
      properties:
        collection_method:
          type: string
          enum:
            - send_invoice
          description: The collection method for the invoice.
        due_after:
          type: string
          format: ISO8601
          description: |-
            The period after which the invoice is due. With some payment solutions it's only
            applicable for manual collection method.
          example: P30D
          default: P30D
      additionalProperties: false
      description: |-
        Payment settings for a billing workflow when the collection method is send
        invoice.
    BillingWorkflowPaymentSettings:
      type: object
      oneOf:
        - $ref: '#/components/schemas/BillingWorkflowPaymentChargeAutomaticallySettings'
        - $ref: '#/components/schemas/BillingWorkflowPaymentSendInvoiceSettings'
      discriminator:
        propertyName: collection_method
        mapping:
          charge_automatically: '#/components/schemas/BillingWorkflowPaymentChargeAutomaticallySettings'
          send_invoice: '#/components/schemas/BillingWorkflowPaymentSendInvoiceSettings'
      description: Payment settings for a billing workflow.
    BillingWorkflowTaxSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: |-
            Enable automatic tax calculation when tax is supported by the app. For example,
            with Stripe Invoicing when enabled, tax is calculated via Stripe Tax.
          default: true
        enforced:
          type: boolean
          description: |-
            Enforce tax calculation when tax is supported by the app. When enabled, the
            billing system will not allow to create an invoice without tax calculation.
            Enforcement is different per apps, for example, Stripe app requires customer to
            have a tax location when starting a paid subscription.
          default: false
        default_tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfig'
          description: |-
            Default tax configuration to apply to the invoices for line items.

            Setting a tax code (`stripe.code` / `taxCodeId`) on a profile's default tax
            config is deprecated and can no longer be added or changed: the organization
            default tax code is used instead. Existing tax-code values may still be removed,
            and `behavior` remains fully supported.
      additionalProperties: false
      description: Tax settings for a billing workflow.
      title: Workflow tax settings
    ChargePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCharge'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    ClosedPeriod:
      type: object
      required:
        - from
        - to
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The start of the period.

            The period is inclusive at the start.
          title: Start
          example: '2023-01-01T01:01:01.001Z'
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The end of the period.

            The period is exclusive at the end.
          title: End
          example: '2023-01-01T01:01:01.001Z'
      additionalProperties: false
      description: |-
        A period with defined start and end dates.

        The period is always inclusive at the start and exclusive at the end.
    CostBasisPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCostBasis'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    CountryCode:
      type: string
      minLength: 2
      maxLength: 2
      pattern: ^[A-Z]{2}$
      description: |-
        [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country
        code. Custom two-letter country codes are also supported for convenience.
      example: US
    CreateAddonRequest:
      type: object
      required:
        - name
        - key
        - instance_type
        - currency
        - rate_cards
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: |-
            A key is a semi-unique string that is used to identify the add-on. It is used to
            reference the latest `active` version of the add-on and is unique with the
            version number.
          title: Key
        instance_type:
          allOf:
            - $ref: '#/components/schemas/AddonInstanceType'
          description: The InstanceType of the add-ons. Can be "single" or "multiple".
          title: The InstanceType of the add-ons. Can be "single" or "multiple".
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: The currency code of the add-on.
          title: Currency
        rate_cards:
          type: array
          items:
            $ref: '#/components/schemas/BillingRateCard'
          description: The rate cards of the add-on.
          title: Rate cards
      additionalProperties: false
      description: Addon create request.
    CreateBillingProfileRequest:
      type: object
      required:
        - name
        - supplier
        - workflow
        - apps
        - default
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        supplier:
          allOf:
            - $ref: '#/components/schemas/BillingParty'
          description: |-
            The name and contact information for the supplier this billing profile
            represents
        workflow:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflow'
          description: The billing workflow settings for this profile
        apps:
          allOf:
            - $ref: '#/components/schemas/BillingProfileAppReferences'
          description: The applications used by this billing profile.
        default:
          type: boolean
          description: Whether this is the default profile.
      additionalProperties: false
      description: BillingProfile create request.
    CreateChargeFlatFeeRequest:
      type: object
      required:
        - name
        - type
        - currency
        - invoice_at
        - service_period
        - settlement_mode
        - payment_term
        - proration_configuration
        - amount_before_proration
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        type:
          type: string
          enum:
            - flat_fee
          description: The type of the charge.
          title: Type
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency of the charge.
          title: Currency
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        unique_reference_id:
          type: string
          description: Unique reference ID of the charge.
          title: Unique reference ID
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: Settlement mode of the charge.
          title: Settlement mode
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfig'
          description: Tax configuration of the charge.
          title: Tax configuration
        payment_term:
          allOf:
            - $ref: '#/components/schemas/BillingPricePaymentTerm'
          description: Payment term of the flat fee charge.
          title: Payment term
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingChargeFlatFeeDiscounts'
          description: The discounts applied to the charge.
          title: Discounts
        feature_key:
          type: string
          description: The feature associated with the charge, when applicable.
          title: Feature key
        proration_configuration:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardProrationConfiguration'
          description: The proration configuration of the charge.
          title: Proration configuration
        amount_before_proration:
          allOf:
            - $ref: '#/components/schemas/CurrencyAmount'
          description: The amount before proration of the charge.
          title: Amount before proration
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
      additionalProperties: false
      description: Flat fee charge create request.
    CreateChargeRequest:
      type: object
      oneOf:
        - $ref: '#/components/schemas/CreateChargeFlatFeeRequest'
        - $ref: '#/components/schemas/CreateChargeUsageBasedRequest'
      discriminator:
        propertyName: type
        mapping:
          flat_fee: '#/components/schemas/CreateChargeFlatFeeRequest'
          usage_based: '#/components/schemas/CreateChargeUsageBasedRequest'
      description: Customer charge.
      title: Customer charge create request.
    CreateChargeUsageBasedRequest:
      type: object
      required:
        - name
        - type
        - currency
        - invoice_at
        - service_period
        - settlement_mode
        - feature_key
        - price
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        type:
          type: string
          enum:
            - usage_based
          description: The type of the charge.
          title: Type
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency of the charge.
          title: Currency
        invoice_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The timestamp when the charge is intended to be invoiced.
          title: Invoice at
        service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The effective service period covered by the charge.
          title: Service period
        unique_reference_id:
          type: string
          description: Unique reference ID of the charge.
          title: Unique reference ID
        settlement_mode:
          allOf:
            - $ref: '#/components/schemas/BillingSettlementMode'
          description: Settlement mode of the charge.
          title: Settlement mode
        tax_config:
          allOf:
            - $ref: '#/components/schemas/BillingTaxConfig'
          description: Tax configuration of the charge.
          title: Tax configuration
        discounts:
          allOf:
            - $ref: '#/components/schemas/BillingRateCardDiscounts'
          description: Discounts applied to the usage-based charge.
          title: Discounts
        feature_key:
          type: string
          description: The feature associated with the charge.
          title: Feature key
        price:
          allOf:
            - $ref: '#/components/schemas/BillingPrice'
          description: The price of the charge.
          title: Price
        full_service_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The full, unprorated service period of the charge.
          title: Full service period
        billing_period:
          allOf:
            - $ref: '#/components/schemas/ClosedPeriod'
          description: The billing period the charge belongs to.
          title: Billing period
      additionalProperties: false
      description: Usage-based charge create request.
    CreateCostBasisRequest:
      type: object
      required:
        - fiat_code
        - rate
      properties:
        fiat_code:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The fiat currency code for the cost basis.
        rate:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The cost rate for the currency.
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            An ISO-8601 timestamp representation of the date from which the cost basis is
            effective. If not provided, it will be effective immediately and will be set to
            `now` by the system.
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            An ISO-8601 timestamp representation of the date until which the cost basis is
            effective. If provided, it must be later than `effective_from`. If not provided,
            it remains effective until superseded.
      additionalProperties: false
      description: CostBasis create request.
    CreateCreditAdjustmentRequest:
      type: object
      required:
        - name
        - currency
        - amount
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: The currency of the granted credits.
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Granted credit amount.
      additionalProperties: false
      description: CreditAdjustment create request.
    CreateCreditGrantFilters:
      type: object
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/ResourceKey'
          description: |-
            Limit the credit grant to specific features. If no features are specified, the
            credit grant can be used for any feature.
          example:
            - input_tokens
            - output_tokens
      additionalProperties: false
      description: Filters for the credit grant.
    CreateCreditGrantPurchase:
      type: object
      required:
        - currency
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency of the purchase amount.
        per_unit_cost_basis:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Cost basis per credit unit used to calculate the purchase amount.

            If `per_unit_cost_basis` is 0.50 and credit amount is $100.00, the total charge
            is $50.00. The value must be greater than 0. If the cost basis is 0, use
            `funding_method=none` instead.

            Defaults to 1.0.
          default: '1.0'
        availability_policy:
          allOf:
            - $ref: '#/components/schemas/BillingCreditAvailabilityPolicy'
          description: |-
            Controls when credits become available for consumption.

            Defaults to `on_creation`.
          default: on_creation
      additionalProperties: false
      description: Purchase and payment terms of the grant.
    CreateCreditGrantRequest:
      type: object
      required:
        - name
        - funding_method
        - currency
        - amount
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        funding_method:
          allOf:
            - $ref: '#/components/schemas/BillingCreditFundingMethod'
          description: Funding method of the grant.
        currency:
          allOf:
            - $ref: '#/components/schemas/CreateCurrencyCode'
          description: The currency of the granted credits.
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Granted credit amount.
        purchase:
          allOf:
            - $ref: '#/components/schemas/CreateCreditGrantPurchase'
          description: Present when a funding workflow applies (funding_method is not `none`).
        tax_config:
          allOf:
            - $ref: '#/components/schemas/CreateCreditGrantTaxConfig'
          description: |-
            Tax configuration for the grant.

            For `invoice` and `external` funding methods, tax configuration should be
            provided to ensure correct revenue recognition. When not provided, the default
            credit grant tax code is applied, if that's not set the global default taxcode
            is used.
        filters:
          $ref: '#/components/schemas/CreateCreditGrantFilters'
        priority:
          type: integer
          format: int16
          minimum: 1
          maximum: 1000
          description: Draw-down priority of the grant. Lower values have higher priority.
          default: 10
        effective_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The timestamp when the credit grant becomes effective.

            Defaults to the current date and time.
        expires_after:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: |-
            The duration after which the credit grant expires.

            Defaults to never expiring.
        key:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceKey'
          description: |-
            Idempotency key for the credit grant creation request.

            When provided, reusing the same key returns an HTTP 409 Conflict instead of
            creating a duplicate grant, which makes create requests safe to retry.
      additionalProperties: false
      description: CreditGrant create request.
    CreateCreditGrantTaxConfig:
      type: object
      properties:
        behavior:
          allOf:
            - $ref: '#/components/schemas/BillingTaxBehavior'
          description: Tax behavior applied to the invoice line item.
        tax_code:
          allOf:
            - $ref: '#/components/schemas/CreateResourceReference'
          description: Tax code applied to the invoice line item.
      additionalProperties: false
      description: |-
        Tax configuration for a credit grant.

        Tax configuration should be provided to ensure correct revenue recognition,
        including for externally funded grants.
      title: Tax configuration for a credit grant
    CreateCurrencyCode:
      type: string
      allOf:
        - $ref: '#/components/schemas/CurrencyCode'
      description: Fiat or custom currency code.
      x-go-type: string
    CreateCurrencyCustomRequest:
      type: object
      required:
        - name
        - code
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            The name of the currency. It should be a human-readable string that represents
            the name of the currency, such as "US Dollar" or "Euro".
        symbol:
          type: string
          minLength: 1
          description: |-
            The symbol of the currency. It should be a string that represents the symbol of
            the currency, such as "$" for US Dollar or "€" for Euro.
        code:
          $ref: '#/components/schemas/BillingCurrencyCodeCustom'
      additionalProperties: false
      description: CurrencyCustom create request.
    CreateCustomerRequest:
      type: object
      required:
        - name
        - key
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ExternalResourceKey'
        usage_attribution:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerUsageAttribution'
          description: Mapping to attribute metered usage to the customer by the event subject.
          title: Usage Attribution
        primary_email:
          type: string
          description: The primary email address of the customer.
          title: Primary Email
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency of the customer. Used for billing, tax and invoicing.
          title: Currency
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: The billing address of the customer. Used for tax and invoicing.
          title: Billing Address
      additionalProperties: false
      description: Customer create request.
    CreateFeatureRequest:
      type: object
      required:
        - name
        - key
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ResourceKey'
        meter:
          allOf:
            - $ref: '#/components/schemas/FeatureMeterReference'
          description: |-
            The meter that the feature is associated with and based on which usage is
            calculated. If not specified, the feature is static.
          title: Meter reference
        unit_cost:
          allOf:
            - $ref: '#/components/schemas/BillingFeatureUnitCost'
          description: |-
            Optional per-unit cost configuration. Use "manual" for a fixed per-unit cost, or
            "llm" to look up cost from the LLM cost database based on meter group-by
            properties.
          title: Unit cost
      additionalProperties: false
      description: Feature create request.
    CreateMeterRequest:
      type: object
      required:
        - name
        - key
        - aggregation
        - event_type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ResourceKey'
        aggregation:
          allOf:
            - $ref: '#/components/schemas/MeterAggregation'
          description: The aggregation type to use for the meter.
        event_type:
          type: string
          minLength: 1
          description: The event type to include in the aggregation.
          example: prompt
        events_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The date since the meter should include events. Useful to skip old events. If
            not specified, all historical events are included.
        value_property:
          type: string
          minLength: 1
          description: |-
            JSONPath expression to extract the value from the ingested event's data
            property.

            The ingested value for sum, avg, min, and max aggregations is a number or a
            string that can be parsed to a number.

            For unique_count aggregation, the ingested value must be a string. For count
            aggregation the value_property is ignored.
          example: $.tokens
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: |-
            Named JSONPath expressions to extract the group by values from the event data.

            Keys must be unique and consist only alphanumeric and underscore characters.
          example:
            type: $.type
      additionalProperties: false
      description: Meter create request.
    CreatePlanAddonRequest:
      type: object
      required:
        - name
        - addon
        - from_plan_phase
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        addon:
          allOf:
            - $ref: '#/components/schemas/AddonReference'
          description: The add-on associated with the plan.
          title: Add-on
        from_plan_phase:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The key of the plan phase from which the add-on becomes available for purchase.
          title: From plan phase
        max_quantity:
          type: integer
          minimum: 1
          description: |-
            The maximum number of times the add-on can be purchased for the plan. For
            single-instance add-ons this field must be omitted. For multi-instance add-ons
            when omitted, unlimited quantity can be purchased.
          title: Max quantity
      additionalProperties: false
      description: PlanAddon create request.
    CreatePlanRequest:
      type: object
      required:
        - name
        - key
        - currency
        - billing_cadence
        - phases
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: |-
            A key is a semi-unique string that is used to identify the plan. It is used to
            reference the latest `active` version of the plan and is unique with the version
            number.
          title: Key
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency code of the plan.
          title: Currency
        billing_cadence:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: The billing cadence for subscriptions using this plan.
          title: Billing cadence
        pro_rating_enabled:
          type: boolean
          description: Whether pro-rating is enabled for this plan.
          title: Pro-rating enabled
          default: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanPhase'
          minItems: 1
          description: |-
            The plan phases define the pricing ramp for a subscription. A phase switch
            occurs only at the end of a billing period. At least one phase is required.
          title: Plan phases
      additionalProperties: false
      description: Plan create request.
    CreateResourceReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: TaxCode reference.
    CreateSubscriptionAddonRequest:
      type: object
      required:
        - addon
        - quantity
        - timing
      properties:
        labels:
          $ref: '#/components/schemas/Labels'
        addon:
          allOf:
            - $ref: '#/components/schemas/AddonReference'
          description: The add-on associated with the subscription.
          title: Add-on
        quantity:
          type: integer
          minimum: 1
          description: The quantity of the add-on. Always 1 for single instance add-ons.
          title: Quantity
        timing:
          allOf:
            - $ref: '#/components/schemas/BillingSubscriptionEditTiming'
          description: |-
            The timing of the operation. After the create or update, a new entry will be
            created in the timeline.
          title: Timing
      additionalProperties: false
      description: SubscriptionAddon create request.
    CreateTaxCodeRequest:
      type: object
      required:
        - name
        - key
        - app_mappings
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        key:
          $ref: '#/components/schemas/ResourceKey'
        app_mappings:
          type: array
          items:
            $ref: '#/components/schemas/BillingTaxCodeAppMapping'
          description: Mapping of app types to tax codes.
          title: App type to tax code mappings
      additionalProperties: false
      description: TaxCode create request.
    CreditBalance:
      type: object
      required:
        - currency
        - live
        - settled
        - pending
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          readOnly: true
        live:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Credits available after applying currently live charge impacts.
          example: '200.00'
          readOnly: true
        settled:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Credits that have been booked on the ledger as of the balance timestamp.
          example: '150.00'
          readOnly: true
        pending:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Credits that have been granted but are not yet written to the ledger, or are
            written to the ledger with a future booked time.
          example: '50.00'
          readOnly: true
      additionalProperties: false
      description: The credit balance by currency.
      title: Credit balance
    CreditGrantPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCreditGrant'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    CreditTransactionPaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCreditTransaction'
        meta:
          $ref: '#/components/schemas/CursorMeta'
      additionalProperties: false
      description: Cursor paginated response.
    CurrencyAmount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Numeric'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
      additionalProperties: false
      description: Monetary amount in a specific currency.
    CurrencyCode:
      type: string
      minLength: 3
      maxLength: 3
      pattern: ^[A-Z]{3}$
      description: |-
        Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html)
        currency code. Custom three-letter currency codes are also supported for
        convenience.
      example: USD
    CurrencyPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCurrency'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    CursorPaginationQueryPage:
      type: object
      properties:
        size:
          type: integer
          description: The number of items to include per page.
        after:
          type: string
          description: Request the next page of data, starting with the item after this parameter.
        before:
          type: string
          description: Request the previous page of data, starting with the item before this parameter.
      additionalProperties: false
      description: Determines which page of the collection to retrieve.
    CustomerPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingCustomer'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    CustomerReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: Customer reference.
    DateTime:
      type: string
      format: date-time
      description: |-
        [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in
        UTC.
      title: RFC3339 Date-Time
      example: '2023-01-01T01:01:01.001Z'
    DateTimeFieldFilter:
      anyOf:
        - $ref: '#/components/schemas/DateTime'
        - type: object
          properties:
            eq:
              allOf:
                - $ref: '#/components/schemas/DateTime'
              description: Value strictly equals given RFC-3339 formatted timestamp in UTC.
            lt:
              allOf:
                - $ref: '#/components/schemas/DateTime'
              description: Value is less than the given RFC-3339 formatted timestamp in UTC.
            lte:
              allOf:
                - $ref: '#/components/schemas/DateTime'
              description: Value is less than or equal to the given RFC-3339 formatted timestamp in UTC.
            gt:
              allOf:
                - $ref: '#/components/schemas/DateTime'
              description: Value is greater than the given RFC-3339 formatted timestamp in UTC.
            gte:
              allOf:
                - $ref: '#/components/schemas/DateTime'
              description: Value is greater than or equal to the given RFC-3339 formatted timestamp in UTC.
          additionalProperties: false
      description: |-
        Filters on the given datetime (RFC-3339) field value. All properties are
        optional; provide exactly one to specify the comparison.
      title: DateTime Field Filter
      x-go-type-import:
        path: github.com/openmeterio/openmeter/api/v3/filters
      x-go-type: filters.FilterDateTime
    ExternalResourceKey:
      type: string
      minLength: 1
      maxLength: 256
      description: |-
        ExternalResourceKey is a unique string that is used to identify a resource in an
        external system.
      title: External Resource Key
      example: 019ae40f-4258-7f15-9491-842f42a7d6ac
    Feature:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          $ref: '#/components/schemas/ResourceKey'
        meter:
          allOf:
            - $ref: '#/components/schemas/FeatureMeterReference'
          description: |-
            The meter that the feature is associated with and based on which usage is
            calculated. If not specified, the feature is static.
          title: Meter reference
        unit_cost:
          allOf:
            - $ref: '#/components/schemas/BillingFeatureUnitCost'
          description: |-
            Optional per-unit cost configuration. Use "manual" for a fixed per-unit cost, or
            "llm" to look up cost from the LLM cost database based on meter group-by
            properties.
          title: Unit cost
      additionalProperties: false
      description: A capability or billable dimension offered by a provider.
    FeatureCostQueryResult:
      type: object
      required:
        - data
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Start of the queried period.
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: End of the queried period.
        data:
          type: array
          items:
            $ref: '#/components/schemas/FeatureCostQueryRow'
          description: The cost data rows.
      additionalProperties: false
      description: Result of a feature cost query.
    FeatureCostQueryRow:
      type: object
      required:
        - usage
        - cost
        - currency
        - from
        - to
        - dimensions
      properties:
        usage:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The metered usage value for the period.
        cost:
          type: string
          allOf:
            - $ref: '#/components/schemas/Numeric'
          nullable: true
          description: |-
            The computed cost amount (usage × unit cost). Null when pricing is not available
            for the given combination of dimensions.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: The currency code of the cost amount.
        detail:
          type: string
          description: |-
            Detail message when cost amount is null, explaining why the cost could not be
            resolved.
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The start of the time bucket the value is aggregated over.
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The end of the time bucket the value is aggregated over.
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: |-
            The dimensions the value is aggregated over. `subject` and `customer_id` are
            reserved dimensions.
      additionalProperties: false
      description: A row in the result of a feature cost query.
    FeatureMeterReference:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: The ID of the meter to associate with this feature.
          title: Meter ID
        filters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/QueryFilterStringMapItem'
          maxProperties: 10
          description: Filters to apply to the dimensions of the meter.
          title: Meter dimensions filters
      additionalProperties: false
      description: Reference to a meter associated with a feature.
    FeaturePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    FeatureReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: Feature reference.
    GetCreditBalanceParamsFilter:
      type: object
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilterExact'
          description: Filter credit balance by currency.
        feature_key:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: |-
            Filter credit balance by feature key. Omit to return the total portfolio value.
            Use `exists=false` to return only unrestricted balance.
      additionalProperties: false
      description: Filter options for getting a credit balance.
    GovernanceFeatureAccess:
      type: object
      required:
        - has_access
      properties:
        has_access:
          type: boolean
          description: |-
            Whether the customer currently has access to the feature.

            `true` for boolean and static entitlements that are available, and for metered
            entitlements with remaining balance. `false` when the feature is unavailable,
            the usage limit has been reached, or (when applicable) credits have been
            exhausted.
          title: Has access
          readOnly: true
        reason:
          allOf:
            - $ref: '#/components/schemas/GovernanceFeatureAccessReason'
          description: |-
            Optional reason when the customer does not have access to the feature. Populated
            when `has_access` is `false`.
          title: Reason
          readOnly: true
      additionalProperties: false
      description: Access status for a single feature.
    GovernanceFeatureAccessReason:
      type: object
      required:
        - code
        - message
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/GovernanceFeatureAccessReasonCode'
          description: Machine-readable error code.
          title: Code
          readOnly: true
        message:
          type: string
          description: Human-readable description of the error.
          title: Message
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          description: Additional structured context.
          title: Attributes
          readOnly: true
      additionalProperties: false
      description: Reason a feature is not accessible to a customer.
    GovernanceFeatureAccessReasonCode:
      type: string
      enum:
        - unknown
        - usage_limit_reached
        - feature_unavailable
        - feature_not_found
        - no_credit_available
      description: Machine-readable reason code for denied feature access.
    GovernanceQueryError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/GovernanceQueryErrorCode'
          description: Machine-readable error code.
          title: Code
          readOnly: true
        message:
          type: string
          description: Human-readable description of the error.
          title: Message
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          description: Additional structured context.
          title: Attributes
          readOnly: true
        customer:
          type: string
          description: The customer identifier from the request that produced this error.
          title: Customer identifier
          readOnly: true
      additionalProperties: false
      description: Query error within a partially successful governance query response.
    GovernanceQueryErrorCode:
      type: string
      enum:
        - unknown
        - customer_not_found
      description: Error code for a governance query failure.
    GovernanceQueryRequest:
      type: object
      required:
        - customer
      properties:
        include_credits:
          type: boolean
          description: |-
            Whether to include credit balance availability for each resolved customer. When
            true, each feature evaluation includes credit balance checks.

            Defaults to `false`.
          title: Include credits
          default: false
        customer:
          allOf:
            - $ref: '#/components/schemas/GovernanceQueryRequestCustomers'
          title: Customer
        feature:
          allOf:
            - $ref: '#/components/schemas/GovernanceQueryRequestFeatures'
          title: Feature
      additionalProperties: false
      description: Query to evaluate feature access for a list of customers.
    GovernanceQueryRequestCustomers:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: |-
            Each entry can be a customer `key` or a usage-attribution subject `key`.
            Identifiers that cannot be resolved to a customer are reported in the response
            `errors` array.
          title: Customer keys and usage-attribution subjects
      additionalProperties: false
      description: List of customer identifiers to evaluate access for.
    GovernanceQueryRequestFeatures:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: List of feature keys to evaluate access for.
          title: Feature Keys
      additionalProperties: false
      description: |-
        Optional list of feature keys to evaluate access for. If omitted, all features
        available in the organization are returned. Providing this list is recommended
        to reduce the response size and the load on the backend services.
    GovernanceQueryResponse:
      type: object
      required:
        - data
        - errors
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceQueryResult'
          description: Access evaluation results, one entry per resolved customer.
          title: Data
          readOnly: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GovernanceQueryError'
          description: Partial errors encountered while processing the request.
          title: Errors
          readOnly: true
        meta:
          allOf:
            - $ref: '#/components/schemas/CursorMeta'
          description: |-
            Pagination metadata. The endpoint may return a partial response if the full
            response would exceed server-side limits.
          title: Meta
          readOnly: true
      additionalProperties: false
      description: Response of the governance query.
    GovernanceQueryResult:
      type: object
      required:
        - matched
        - customer
        - features
        - updated_at
      properties:
        matched:
          type: array
          items:
            type: string
          description: |-
            The list of identifiers from the request that resolved to this customer. Each
            entry is either the customer `key` or one of its usage-attribution subject
            `key`s.

            Duplicate or aliased identifiers that resolve to the same customer collapse to a
            single result entry, with every requested identifier listed here.
          title: Matched identifiers
          readOnly: true
        customer:
          allOf:
            - $ref: '#/components/schemas/BillingCustomer'
          description: The customer the matched identifiers resolved to.
          title: Customer
          readOnly: true
        features:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GovernanceFeatureAccess'
          description: |-
            Map of features with their access status.

            Map keys are the feature keys requested in `feature.keys`, or every feature
            `key` available in the organization when the feature filter was omitted.
          title: Features
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            Timestamp of the most recent change to the customer's access state reflected in
            this result.
          title: Updated at
          readOnly: true
      additionalProperties: false
      description: Access evaluation result for a single resolved customer.
    ISO8601Duration:
      type: string
      pattern: ^P(?:\d+(?:\.\d+)?Y)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?W)?(?:\d+(?:\.\d+)?D)?(?:T(?:\d+(?:\.\d+)?H)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?S)?)?$
      description: |-
        [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm)
        string.
      title: ISO 8601 Duration
      example: P1Y
      format: ISO8601
    IngestedEventPaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MeteringIngestedEvent'
        meta:
          $ref: '#/components/schemas/CursorMeta'
      additionalProperties: false
      description: Cursor paginated response.
    InvoicePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingInvoice'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    LLMCostModel:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Identifier of the model, e.g., "gpt-4", "claude-3-5-sonnet".
        name:
          type: string
          description: Name of the model, e.g., "GPT-4", "Claude 3.5 Sonnet".
      additionalProperties: false
      description: LLM Model
    LLMCostModelPricing:
      type: object
      required:
        - input_per_token
        - output_per_token
      properties:
        input_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Input price per token (USD).
        output_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Output price per token (USD).
        cache_read_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cache read price per token (USD).
        cache_write_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Cache write price per token (USD).
        reasoning_per_token:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: Reasoning output price per token (USD).
      additionalProperties: false
      description: Token pricing for an LLM model, denominated per token.
    LLMCostOverrideCreate:
      type: object
      required:
        - provider
        - model_id
        - pricing
        - currency
        - effective_from
      properties:
        provider:
          type: string
          description: Provider/vendor of the model.
        model_id:
          type: string
          description: Canonical model identifier.
        model_name:
          type: string
          description: Human-readable model name.
        pricing:
          allOf:
            - $ref: '#/components/schemas/LLMCostModelPricing'
          description: Token pricing data.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency code.
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: When this override becomes effective.
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: When this override expires.
      additionalProperties: false
      description: |-
        Input for creating a per-namespace price override. Unique per provider, model
        and currency. If an override already exists for the given provider, model and
        currency, it will be updated. If an override does not exist, it will be created.
    LLMCostPrice:
      type: object
      required:
        - id
        - provider
        - model
        - pricing
        - currency
        - source
        - effective_from
        - created_at
        - updated_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: Unique identifier.
          readOnly: true
        provider:
          allOf:
            - $ref: '#/components/schemas/LLMCostProvider'
          description: Provider of the model.
          readOnly: true
        model:
          allOf:
            - $ref: '#/components/schemas/LLMCostModel'
          description: The model.
          readOnly: true
        pricing:
          allOf:
            - $ref: '#/components/schemas/LLMCostModelPricing'
          description: Token pricing data.
          readOnly: true
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency code (currently always "USD").
          readOnly: true
        source:
          allOf:
            - $ref: '#/components/schemas/LLMCostPriceSource'
          description: Where this price came from.
          readOnly: true
        effective_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: When this price becomes effective.
          readOnly: true
        effective_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: When this price expires. Omitted when the price is currently effective.
          readOnly: true
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Creation timestamp.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Last update timestamp.
          readOnly: true
      additionalProperties: false
      description: |-
        An LLM cost price record, representing the cost per token for a specific model
        from a specific provider.
    LLMCostPriceSource:
      type: string
      enum:
        - manual
        - system
      description: Identifies where an LLM cost price came from.
    LLMCostProvider:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Identifier of the provider, e.g., "openai", "anthropic".
        name:
          type: string
          description: Name of the provider, e.g., "OpenAI", "Anthropic".
      additionalProperties: false
      description: LLM Provider
    ListAddonsParamsFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ULIDFieldFilter'
        key:
          $ref: '#/components/schemas/StringFieldFilter'
        name:
          $ref: '#/components/schemas/StringFieldFilter'
        status:
          $ref: '#/components/schemas/StringFieldFilterExact'
        currency:
          $ref: '#/components/schemas/StringFieldFilterExact'
      additionalProperties: false
      description: Filter options for listing add-ons.
    ListChargesParamsFilter:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilterExact'
          description: |-
            Filter charges by status.

            Supported statuses are:

            - `created`
            - `active`
            - `final`
            - `deleted`

            If omitted, all statuses are returned except for `deleted`.
      additionalProperties: false
      description: Filter options for listing charges.
    ListCostBasesParamsFilter:
      type: object
      properties:
        fiat_code:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Filter cost bases by fiat currency code.
      additionalProperties: false
      description: Filter options for listing cost bases.
    ListCreditGrantsParamsFilter:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantStatus'
          description: Filter credit grants by status.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Filter credit grants by currency.
        key:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter credit grants by key.
      additionalProperties: false
      description: Filter options for listing credit grants.
    ListCreditTransactionsParamsFilter:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/BillingCreditTransactionType'
          description: Filter credit transactions by type.
        currency:
          allOf:
            - $ref: '#/components/schemas/BillingCurrencyCode'
          description: Filter credit transactions by currency.
        feature_key:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: |-
            Filter credit transactions by feature key. Omit to return all credit
            transactions. Use `exists=false` to return only unrestricted credit
            transactions.
      additionalProperties: false
      description: Filter options for listing credit transactions.
    ListCurrenciesParamsFilter:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/BillingCurrencyType'
        code:
          $ref: '#/components/schemas/StringFieldFilter'
      additionalProperties: false
      description: Filter options for listing currencies.
    ListCustomerEntitlementAccessResponseData:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingEntitlementAccessResult'
          description: The list of entitlement access results.
          readOnly: true
      additionalProperties: false
      description: List customer entitlement access response data.
    ListCustomersParamsFilter:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/StringFieldFilter'
        name:
          $ref: '#/components/schemas/StringFieldFilter'
        primary_email:
          $ref: '#/components/schemas/StringFieldFilter'
        usage_attribution_subject_key:
          $ref: '#/components/schemas/StringFieldFilter'
        plan_key:
          $ref: '#/components/schemas/StringFieldFilter'
        billing_profile_id:
          $ref: '#/components/schemas/ULIDFieldFilter'
      additionalProperties: false
      description: Filter options for listing customers.
    ListEventsParamsFilter:
      type: object
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter events by ID.
        source:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter events by source.
        subject:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter events by subject.
        type:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter events by type.
        customer_id:
          allOf:
            - $ref: '#/components/schemas/ULIDFieldFilter'
          description: Filter events by the associated customer ID.
        time:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter events by event time.
        ingested_at:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter events by the time the event was ingested.
        stored_at:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter events by the time the event was stored.
      additionalProperties: false
      description: Filter options for listing ingested events.
    ListFeatureParamsFilter:
      type: object
      properties:
        meter_id:
          $ref: '#/components/schemas/ULIDFieldFilter'
        key:
          $ref: '#/components/schemas/StringFieldFilter'
        name:
          $ref: '#/components/schemas/StringFieldFilter'
      additionalProperties: false
      description: Filter options for listing features.
    ListInvoicesParamsFilter:
      type: object
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilterExact'
          description: Filter by invoice status.
        customer_id:
          allOf:
            - $ref: '#/components/schemas/ULIDFieldFilter'
          description: Filter by customer ID.
        issued_at:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter by the time the invoice was issued.
        service_period_start:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter by service period start.
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTimeFieldFilter'
          description: Filter by invoice creation time.
      additionalProperties: false
      description: Filter options for listing invoices.
    ListLLMCostPricesParamsFilter:
      type: object
      properties:
        provider:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter by provider. e.g. ?filter[provider][eq]=openai
        model_id:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter by model ID. e.g. ?filter[model_id][eq]=gpt-4
        model_name:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter by model name. e.g. ?filter[model_name][contains]=gpt
        currency:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter by currency code. e.g. ?filter[currency][eq]=USD
        source:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter by source. e.g. ?filter[source][eq]=system
      additionalProperties: false
      description: Filter options for listing LLM cost prices.
    ListMetersParamsFilter:
      type: object
      properties:
        key:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter meters by key.
        name:
          allOf:
            - $ref: '#/components/schemas/StringFieldFilter'
          description: Filter meters by name.
      additionalProperties: false
      description: Filter options for listing meters.
    ListPlansParamsFilter:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/StringFieldFilter'
        name:
          $ref: '#/components/schemas/StringFieldFilter'
        status:
          $ref: '#/components/schemas/StringFieldFilterExact'
        currency:
          $ref: '#/components/schemas/StringFieldFilterExact'
      additionalProperties: false
      description: Filter options for listing plans.
    ListSubscriptionsParamsFilter:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ULIDFieldFilter'
        customer_id:
          $ref: '#/components/schemas/ULIDFieldFilter'
        status:
          $ref: '#/components/schemas/StringFieldFilterExact'
        plan_id:
          $ref: '#/components/schemas/ULIDFieldFilter'
        plan_key:
          $ref: '#/components/schemas/StringFieldFilterExact'
      additionalProperties: false
      description: Filter options for listing subscriptions.
    Meter:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - key
        - aggregation
        - event_type
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        key:
          $ref: '#/components/schemas/ResourceKey'
        aggregation:
          allOf:
            - $ref: '#/components/schemas/MeterAggregation'
          description: The aggregation type to use for the meter.
        event_type:
          type: string
          minLength: 1
          description: The event type to include in the aggregation.
          example: prompt
        events_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The date since the meter should include events. Useful to skip old events. If
            not specified, all historical events are included.
        value_property:
          type: string
          minLength: 1
          description: |-
            JSONPath expression to extract the value from the ingested event's data
            property.

            The ingested value for sum, avg, min, and max aggregations is a number or a
            string that can be parsed to a number.

            For unique_count aggregation, the ingested value must be a string. For count
            aggregation the value_property is ignored.
          example: $.tokens
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: |-
            Named JSONPath expressions to extract the group by values from the event data.

            Keys must be unique and consist only alphanumeric and underscore characters.
          example:
            type: $.type
      additionalProperties: false
      description: A meter is a configuration that defines how to match and aggregate events.
      example:
        id: 01G65Z755AFWAKHE12NY0CQ9FH
        key: tokens_total
        name: Tokens Total
        description: AI Token Usage
        aggregation: sum
        event_type: prompt
        value_property: $.tokens
        dimensions:
          model: $.model
          type: $.type
        created_at: '2024-01-01T01:01:01.001Z'
        updated_at: '2024-01-01T01:01:01.001Z'
    MeterAggregation:
      type: string
      enum:
        - sum
        - count
        - unique_count
        - avg
        - min
        - max
        - latest
      description: The aggregation type to use for the meter.
    MeterPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Meter'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    MeterQueryFilters:
      type: object
      properties:
        dimensions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/QueryFilterStringMapItem'
          maxProperties: 10
          description: |-
            Filters to apply to the dimensions of the query. For `subject` and `customer_id`
            only equals ("eq", "in") comparisons are supported.
      additionalProperties: false
      description: Filters to apply to a meter query.
    MeterQueryGranularity:
      type: string
      enum:
        - PT1M
        - PT1H
        - P1D
        - P1M
      description: |-
        The granularity of the time grouping. Time durations are specified in ISO 8601
        format.
    MeterQueryRequest:
      type: object
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The start of the period the usage is queried from.
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The end of the period the usage is queried to.
        granularity:
          allOf:
            - $ref: '#/components/schemas/MeterQueryGranularity'
          description: |-
            The size of the time buckets to group the usage into. If not specified, the
            usage is aggregated over the entire period.
        time_zone:
          type: string
          description: |-
            The value is the name of the time zone as defined in the IANA Time Zone Database
            (http://www.iana.org/time-zones). The time zone is used to determine the start
            and end of the time buckets. If not specified, the UTC timezone will be used.
          default: UTC
        group_by_dimensions:
          type: array
          items:
            type: string
          maxItems: 100
          description: The dimensions to group the results by.
          example:
            - model
            - type
        filters:
          allOf:
            - $ref: '#/components/schemas/MeterQueryFilters'
          description: Filters to apply to the query.
      additionalProperties: false
      description: A meter query request.
      example:
        from: '2023-01-01T00:00:00Z'
        to: '2023-01-02T00:00:00Z'
        granularity: P1D
        time_zone: UTC
    MeterQueryResult:
      type: object
      required:
        - data
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The start of the period the usage is queried from.
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The end of the period the usage is queried to.
        data:
          type: array
          items:
            $ref: '#/components/schemas/MeterQueryRow'
          description: The usage data. If no data is available, an empty array is returned.
      additionalProperties: false
      description: Meter query result.
      example:
        from: '2023-01-01T00:00:00Z'
        to: '2023-01-02T00:00:00Z'
        data:
          - value: '12.3456'
            from: '2023-01-01T00:00:00Z'
            to: '2023-01-02T00:00:00Z'
            dimensions:
              customer_id: 01G65Z755AFWAKHE12NY0CQ9FH
              model: gpt-4-turbo
              type: input
    MeterQueryRow:
      type: object
      required:
        - value
        - from
        - to
        - dimensions
      properties:
        value:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The aggregated value.
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The start of the time bucket the value is aggregated over.
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The end of the time bucket the value is aggregated over.
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: |-
            The dimensions the value is aggregated over. `subject` and `customer_id` are
            reserved dimensions.
      additionalProperties: false
      description: A row in the result of a meter query.
      example:
        value: '12.3456'
        from: '2023-01-01T00:00:00Z'
        to: '2023-01-02T00:00:00Z'
        dimensions:
          customer_id: 01G65Z755AFWAKHE12NY0CQ9FH
          model: gpt-4-turbo
          type: input
    MeteringEvent:
      type: object
      required:
        - id
        - source
        - specversion
        - type
        - subject
      properties:
        id:
          type: string
          minLength: 1
          description: Identifies the event.
          example: 5c10fade-1c9e-4d6c-8275-c52c36731d3c
        source:
          type: string
          minLength: 1
          format: uri-reference
          description: Identifies the context in which an event happened.
          example: service-name
        specversion:
          type: string
          minLength: 1
          description: The version of the CloudEvents specification which the event uses.
          example: '1.0'
          default: '1.0'
        type:
          type: string
          minLength: 1
          description: |-
            Contains a value describing the type of event related to the originating
            occurrence.
          example: com.example.someevent
        datacontenttype:
          type: string
          enum:
            - application/json
          nullable: true
          description: |-
            Content type of the CloudEvents data value. Only the value "application/json" is
            allowed over HTTP.
          example: application/json
        dataschema:
          type: string
          format: uri
          nullable: true
          minLength: 1
          description: Identifies the schema that data adheres to.
        subject:
          type: string
          minLength: 1
          description: |-
            Describes the subject of the event in the context of the event producer
            (identified by source).
          example: customer-id
        time:
          type: string
          allOf:
            - $ref: '#/components/schemas/DateTime'
          nullable: true
          description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
          example: '2023-01-01T01:01:01.001Z'
        data:
          type: object
          additionalProperties: {}
          nullable: true
          description: The event payload. Optional, if present it must be a JSON object.
      additionalProperties: false
      description: Metering event following the CloudEvents specification.
      title: Metering Event
      example:
        specversion: '1.0'
        id: 5c10fade-1c9e-4d6c-8275-c52c36731d3c
        source: service-name
        type: prompt
        subject: customer-id
        time: '2023-01-01T01:01:01.001Z'
        data:
          prompt: Hello, world!
          tokens: 100
          model: gpt-4o
          type: input
    MeteringIngestedEvent:
      type: object
      required:
        - event
        - ingested_at
        - stored_at
      properties:
        event:
          allOf:
            - $ref: '#/components/schemas/MeteringEvent'
          description: The original event ingested.
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerReference'
          description: The customer if the event is associated with a customer.
        ingested_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The date and time the event was ingested and its processing started.
        stored_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: The date and time the event was stored in the database.
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/MeteringIngestedEventValidationError'
          description: The validation errors of the ingested event.
      additionalProperties: false
      description: An ingested metering event with ingestion metadata.
      title: Ingested Event
      example:
        event:
          id: 5c10fade-1c9e-4d6c-8275-c52c36731d3c
          source: service-name
          specversion: '1.0'
          type: prompt
          subject: customer_key
          time: '2023-01-01T01:01:01.001Z'
        customer:
          id: 01G65Z755AFWAKHE12NY0CQ9FH
        ingested_at: '2023-01-01T01:01:01.001Z'
        stored_at: '2023-01-01T01:01:02.001Z'
    MeteringIngestedEventValidationError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: The machine readable code of the error.
          title: Code
          readOnly: true
        message:
          type: string
          description: The human readable description of the error.
          title: Message
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          description: Additional attributes.
          title: Attributes
          readOnly: true
      additionalProperties: false
      description: Event validation errors.
    Numeric:
      type: string
      pattern: ^\-?[0-9]+(\.[0-9]+)?$
      description: Numeric represents an arbitrary precision number.
    OrganizationDefaultTaxCodes:
      type: object
      required:
        - invoicing_tax_code
        - credit_grant_tax_code
        - created_at
        - updated_at
      properties:
        invoicing_tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: Default tax code for invoicing.
          title: Invoicing tax code
        credit_grant_tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: Default tax code for credit grants.
          title: Credit grant tax code
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp of creation.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: Timestamp of last update.
          readOnly: true
      additionalProperties: false
      description: |-
        Organization-level default tax code references.

        Stores the default tax codes applied to specific billing contexts for this
        organization. Provisioned automatically when the organization is created.
    PlanAddon:
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - addon
        - from_plan_phase
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        addon:
          allOf:
            - $ref: '#/components/schemas/AddonReference'
          description: The add-on associated with the plan.
          title: Add-on
        from_plan_phase:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The key of the plan phase from which the add-on becomes available for purchase.
          title: From plan phase
        max_quantity:
          type: integer
          minimum: 1
          description: |-
            The maximum number of times the add-on can be purchased for the plan. For
            single-instance add-ons this field must be omitted. For multi-instance add-ons
            when omitted, unlimited quantity can be purchased.
          title: Max quantity
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/ProductCatalogValidationError'
          description: List of validation errors.
          title: Validation errors
          readOnly: true
      additionalProperties: false
      description: |-
        PlanAddon represents an association between a plan and an add-on, controlling
        which add-ons are available for purchase within a plan.
    PlanAddonPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PlanAddon'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    PlanPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlan'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    PricePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LLMCostPrice'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    ProductCatalogValidationError:
      type: object
      required:
        - code
        - message
        - field
      properties:
        code:
          type: string
          description: Machine-readable error code.
          title: Code
          readOnly: true
        message:
          type: string
          description: Human-readable description of the error.
          title: Message
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          description: Additional structured context.
          title: Attributes
          readOnly: true
        field:
          type: string
          description: The path to the field.
          title: Field
          example: addons/pro/ratecards/token/featureKey
          readOnly: true
      additionalProperties: false
      description: Validation errors providing detailed description of the issue.
    QueryFilterString:
      type: object
      properties:
        eq:
          type: string
          description: The attribute equals the provided value.
        neq:
          type: string
          description: The attribute does not equal the provided value.
        in:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: The attribute is one of the provided values.
        nin:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: The attribute is not one of the provided values.
        contains:
          type: string
          description: The attribute contains the provided value.
        ncontains:
          type: string
          description: The attribute does not contain the provided value.
        and:
          minItems: 1
          maxItems: 10
          description: Combines the provided filters with a logical AND.
          type: array
          items:
            $ref: '#/components/schemas/QueryFilterString'
        or:
          minItems: 1
          maxItems: 10
          description: Combines the provided filters with a logical OR.
          type: array
          items:
            $ref: '#/components/schemas/QueryFilterString'
      additionalProperties: false
      description: |-
        A query filter for a string attribute. Operators are mutually exclusive, only
        one operator is allowed at a time.
      title: Query String Filter
    QueryFilterStringMapItem:
      type: object
      properties:
        exists:
          type: boolean
          description: The attribute exists.
        eq:
          type: string
          description: The attribute equals the provided value.
        neq:
          type: string
          description: The attribute does not equal the provided value.
        in:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: The attribute is one of the provided values.
        nin:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
          description: The attribute is not one of the provided values.
        contains:
          type: string
          description: The attribute contains the provided value.
        ncontains:
          type: string
          description: The attribute does not contain the provided value.
        and:
          type: array
          items:
            $ref: '#/components/schemas/QueryFilterString'
          minItems: 1
          maxItems: 10
          description: Combines the provided filters with a logical AND.
        or:
          type: array
          items:
            $ref: '#/components/schemas/QueryFilterString'
          minItems: 1
          maxItems: 10
          description: Combines the provided filters with a logical OR.
      additionalProperties: false
      description: |-
        A query filter for an item in a string map attribute. Operators are mutually
        exclusive, only one operator is allowed at a time.
      title: Query String Map Item Filter
    RecurringPeriod:
      type: object
      required:
        - anchor
        - interval
      properties:
        anchor:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: A date-time anchor to base the recurring period on.
          title: Anchor time
          example: '2023-01-01T01:01:01.001Z'
        interval:
          allOf:
            - $ref: '#/components/schemas/ISO8601Duration'
          description: The interval duration in ISO 8601 format.
          title: Interval in ISO 8601 duration format
          example: P1M
      additionalProperties: false
      description: Recurring period with an anchor and an interval.
    ResourceKey:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
      description: A key is a unique string that is used to identify a resource.
      title: Resource Key
      example: resource_key
    StringFieldFilter:
      anyOf:
        - type: string
        - type: object
          properties:
            eq:
              type: string
              description: Value strictly equals the given string value.
            neq:
              type: string
              description: Value does not equal the given string value.
            contains:
              type: string
              description: Value contains the given string value (fuzzy match).
            ocontains:
              type: string
              description: |-
                Returns entities that fuzzy-match any of the comma-delimited phrases in the
                filter string.
            oeq:
              type: string
              description: |-
                Returns entities that exact match any of the comma-delimited phrases in the
                filter string.
            gt:
              type: string
              description: Value is greater than the given string value (lexicographic compare).
            gte:
              type: string
              description: |-
                Value is greater than or equal to the given string value (lexicographic
                compare).
            lt:
              type: string
              description: Value is less than the given string value (lexicographic compare).
            lte:
              type: string
              description: Value is less than or equal to the given string value (lexicographic compare).
            exists:
              type: boolean
              description: |-
                When true, the field must be present (non-null); when false, the field must be
                absent (null).
          additionalProperties: false
      description: |-
        Filters on the given string field value by either exact or fuzzy match. All
        properties are optional; provide exactly one to specify the comparison.
      x-go-type-import:
        path: github.com/openmeterio/openmeter/api/v3/filters
      x-go-type: filters.FilterString
    StringFieldFilterExact:
      anyOf:
        - type: string
        - type: object
          properties:
            eq:
              type: string
              description: Value strictly equals the given string value.
            oeq:
              type: string
              description: |-
                Returns entities that exact match any of the comma-delimited phrases in the
                filter string.
            neq:
              type: string
              description: Value does not equal the given string value.
          additionalProperties: false
      description: |-
        Filters on the given string field value by exact match. All properties are
        optional; provide exactly one to specify the comparison.
      title: String Field Filter Exact
      x-go-type-import:
        path: github.com/openmeterio/openmeter/api/v3/filters
      x-go-type: filters.FilterStringExact
    SubscriptionAddon:
      type: object
      required:
        - id
        - created_at
        - updated_at
        - name
        - addon
        - quantity
        - quantity_at
        - active_from
        - timeline
        - rate_cards
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          readOnly: true
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity creation date.
          readOnly: true
        updated_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity last update date.
          readOnly: true
        deleted_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of entity deletion date.
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
          readOnly: true
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
          readOnly: true
        addon:
          allOf:
            - $ref: '#/components/schemas/AddonReference'
          description: The add-on associated with the subscription.
          title: Add-on
        quantity:
          type: integer
          minimum: 1
          description: The quantity of the add-on. Always 1 for single instance add-ons.
          title: Quantity
        quantity_at:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            An ISO-8601 timestamp representation of which point in time the quantity was
            resolved to.
          readOnly: true
        active_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of the cadence start of the resource.
          readOnly: true
        active_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of the cadence end of the resource.
          readOnly: true
        timeline:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAddonTimelineSegment'
          description: The timeline of the add-on. The returned periods are sorted and continuous.
          title: Timeline
          example:
            - quantity: 1
              active_from: '2025-01-01T00:00:00Z'
              active_to: '2025-01-02T00:00:00Z'
            - quantity: 0
              active_from: '2025-01-02T00:00:00Z'
              active_to: '2025-01-03T00:00:00Z'
            - quantity: 1
              active_from: '2025-01-03T00:00:00Z'
          readOnly: true
        rate_cards:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAddonRateCard'
          description: The rate cards of the add-on.
          title: Rate cards
          readOnly: true
      additionalProperties: false
      description: Addon purchased with a subscription.
    SubscriptionAddonPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAddon'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    SubscriptionAddonRateCard:
      type: object
      required:
        - rate_card
        - affected_subscription_item_ids
      properties:
        rate_card:
          allOf:
            - $ref: '#/components/schemas/BillingRateCard'
          description: The rate card.
          title: Rate card
        affected_subscription_item_ids:
          type: array
          items:
            $ref: '#/components/schemas/ULID'
          description: The IDs of the subscription items that this rate card belongs to.
          title: Affected subscription item IDs
          readOnly: true
      additionalProperties: false
      description: A rate card for a subscription add-on.
    SubscriptionAddonTimelineSegment:
      type: object
      required:
        - active_from
        - quantity
      properties:
        active_from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of the cadence start of the resource.
          readOnly: true
        active_to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: An ISO-8601 timestamp representation of the cadence end of the resource.
          readOnly: true
        quantity:
          type: integer
          minimum: 0
          description: The quantity of the add-on for the given period.
          title: Quantity
          example: 1
          readOnly: true
      additionalProperties: false
      description: A subscription add-on event.
    SubscriptionPagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingSubscription'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    TaxCodePagePaginatedResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingTaxCode'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      additionalProperties: false
      description: Page paginated response.
    TaxCodeReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: TaxCode reference.
    ULID:
      type: string
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      description: ULID (Universally Unique Lexicographically Sortable Identifier).
      title: ULID
      example: 01G65Z755AFWAKHE12NY0CQ9FH
    ULIDFieldFilter:
      anyOf:
        - $ref: '#/components/schemas/ULID'
        - type: object
          properties:
            eq:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: Value strictly equals the given ULID value.
            oeq:
              type: string
              description: |-
                Returns entities that exact match any of the comma-delimited ULIDs in the filter
                string.
            neq:
              allOf:
                - $ref: '#/components/schemas/ULID'
              description: Value does not equal the given ULID value.
          additionalProperties: false
      description: |-
        Filters on the given ULID field value by exact match. All properties are
        optional; provide exactly one to specify the comparison.
      title: ULID Field Filter
      x-go-type-import:
        path: github.com/openmeterio/openmeter/api/v3/filters
      x-go-type: filters.FilterULID
    UpdateAddress:
      type: object
      properties:
        country:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          description: |-
            Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html)
            alpha-2 format.
          title: Country
        postal_code:
          type: string
          description: Postal code.
          title: Postal Code
        state:
          type: string
          description: State or province.
          title: State
        city:
          type: string
          description: City.
          title: City
        line1:
          type: string
          description: First line of the address.
          title: Line 1
        line2:
          type: string
          description: Second line of the address.
          title: Line 2
        phone_number:
          type: string
          description: Phone number.
          title: Phone Number
      additionalProperties: false
      description: Address
    UpdateBillingInvoiceWorkflow:
      type: object
      properties:
        invoicing:
          allOf:
            - $ref: '#/components/schemas/UpdateBillingInvoiceWorkflowInvoicingSettings'
          description: Invoicing settings for this invoice.
          title: Invoicing settings
        payment:
          allOf:
            - $ref: '#/components/schemas/UpdateBillingWorkflowPaymentSettings'
          description: Payment settings for this invoice.
          title: Payment settings
      additionalProperties: false
      description: |-
        Invoice-level snapshot of the workflow configuration.

        Contains only the settings that are meaningful for an already-created invoice:
        invoicing behaviour and payment settings. Collection alignment and tax policy
        are gather-time / profile-wide concerns and are not included.
    UpdateBillingInvoiceWorkflowInvoicingSettings:
      type: object
      properties:
        auto_advance:
          type: boolean
          description: Whether to automatically issue the invoice after the draft_period has passed.
          default: true
        draft_period:
          type: string
          format: ISO8601
          description: The period for the invoice to be kept in draft status for manual reviews.
          example: P1D
          default: P0D
      additionalProperties: false
      description: |-
        Invoice-level invoicing settings.

        A subset of BillingWorkflowInvoicingSettings limited to fields that are
        meaningful per-invoice. progressive_billing is omitted as it is a gather-time /
        profile-level decision.
    UpdateBillingPartyAddresses:
      type: object
      required:
        - billing_address
      properties:
        billing_address:
          allOf:
            - $ref: '#/components/schemas/UpdateAddress'
          description: Billing address.
      additionalProperties: false
      description: A collection of addresses for the party.
    UpdateBillingPartyTaxIdentity:
      type: object
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/BillingTaxIdentificationCode'
          description: Normalized tax identification code shown on the original identity document.
      additionalProperties: false
      description: |-
        Identity stores the details required to identify an entity for tax purposes in a
        specific country.
    UpdateBillingWorkflowPaymentChargeAutomaticallySettings:
      type: object
      required:
        - collection_method
      properties:
        collection_method:
          type: string
          enum:
            - charge_automatically
          description: The collection method for the invoice.
      additionalProperties: false
      description: |-
        Payment settings for a billing workflow when the collection method is charge
        automatically.
    UpdateBillingWorkflowPaymentSendInvoiceSettings:
      type: object
      required:
        - collection_method
      properties:
        collection_method:
          type: string
          enum:
            - send_invoice
          description: The collection method for the invoice.
        due_after:
          type: string
          format: ISO8601
          description: |-
            The period after which the invoice is due. With some payment solutions it's only
            applicable for manual collection method.
          example: P30D
          default: P30D
      additionalProperties: false
      description: |-
        Payment settings for a billing workflow when the collection method is send
        invoice.
    UpdateBillingWorkflowPaymentSettings:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UpdateBillingWorkflowPaymentChargeAutomaticallySettings'
        - $ref: '#/components/schemas/UpdateBillingWorkflowPaymentSendInvoiceSettings'
      discriminator:
        propertyName: collection_method
        mapping:
          charge_automatically: '#/components/schemas/UpdateBillingWorkflowPaymentChargeAutomaticallySettings'
          send_invoice: '#/components/schemas/UpdateBillingWorkflowPaymentSendInvoiceSettings'
      description: Payment settings for a billing workflow.
    UpdateClosedPeriod:
      type: object
      required:
        - from
        - to
      properties:
        from:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The start of the period.

            The period is inclusive at the start.
          title: Start
          example: '2023-01-01T01:01:01.001Z'
        to:
          allOf:
            - $ref: '#/components/schemas/DateTime'
          description: |-
            The end of the period.

            The period is exclusive at the end.
          title: End
          example: '2023-01-01T01:01:01.001Z'
      additionalProperties: false
      description: |-
        A period with defined start and end dates.

        The period is always inclusive at the start and exclusive at the end.
    UpdateCreditGrantExternalSettlementRequest:
      type: object
      required:
        - status
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/BillingCreditPurchasePaymentSettlementStatus'
          description: The new payment settlement status.
      additionalProperties: false
      description: |-
        Request body for updating the external payment settlement status of a credit
        grant.
    UpdateCustomerUsageAttribution:
      type: object
      required:
        - subject_keys
      properties:
        subject_keys:
          type: array
          items:
            $ref: '#/components/schemas/UsageAttributionSubjectKey'
          minItems: 0
          description: |-
            The subjects that are attributed to the customer. Can be empty when no usage
            event subjects are associated with the customer.
          title: Subject Keys
      additionalProperties: false
      description: |-
        Mapping to attribute metered usage to the customer. One customer can have zero
        or more subjects, but one subject can only belong to one customer.
    UpdateDiscounts:
      type: object
      properties:
        percentage:
          type: number
          minimum: 0
          maximum: 100
          description: Percentage discount applied to the price (0–100).
        usage:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Number of usage units granted free before billing starts. Only applies to
            usage-based lines (not flat fees). Usage is treated as zero until this amount is
            exhausted.
      additionalProperties: false
      description: Discount configuration for a rate card.
    UpdateFeatureRequest:
      type: object
      properties:
        unit_cost:
          allOf:
            - $ref: '#/components/schemas/BillingFeatureUnitCost'
          nullable: true
          description: |-
            Optional per-unit cost configuration. Use "manual" for a fixed per-unit cost, or
            "llm" to look up cost from the LLM cost database based on meter group-by
            properties. Set to `null` to clear the existing unit cost; omit to leave it
            unchanged.
          title: Unit cost
      additionalProperties: false
      description: |-
        Request body for updating a feature. Currently only the unit_cost field can be
        updated.
    UpdateInvoiceCustomer:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        usage_attribution:
          allOf:
            - $ref: '#/components/schemas/UpdateCustomerUsageAttribution'
          description: Mapping to attribute metered usage to the customer by the event subject.
          title: Usage Attribution
        billing_address:
          allOf:
            - $ref: '#/components/schemas/UpdateAddress'
          description: The billing address of the customer. Used for tax and invoicing.
          title: Billing Address
        id:
          $ref: '#/components/schemas/ULID'
        key:
          allOf:
            - $ref: '#/components/schemas/ExternalResourceKey'
          description: |-
            Optional external resource key for the customer.

            Omitted when the customer was created without a key. Unlike on the customer
            resource itself, the key is optional here because the invoice snapshot may
            predate or omit it.
      additionalProperties: false
      description: Snapshot of the customer's information at the time the invoice was issued.
    UpdateInvoiceLine:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UpdateInvoiceStandardLine'
      discriminator:
        propertyName: type
        mapping:
          standard_line: '#/components/schemas/UpdateInvoiceStandardLine'
      description: |-
        A top-level line item on an invoice.

        Each line represents a single charge, typically associated with a rate card from
        a subscription. Detailed (child) lines are nested under `detailed_lines` when
        present.
    UpdateInvoiceLineRateCard:
      type: object
      required:
        - price
      properties:
        price:
          allOf:
            - $ref: '#/components/schemas/UpdatePrice'
          description: The price definition used to calculate charges for this line.
          title: Price
        tax_config:
          allOf:
            - $ref: '#/components/schemas/UpdateRateCardTaxConfig'
          description: Tax configuration snapshot for this line.
          title: Tax config
        feature_key:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The feature key associated with this line's rate card.
          title: Feature key
        discounts:
          allOf:
            - $ref: '#/components/schemas/UpdateDiscounts'
          description: Discount configuration from the rate card.
          title: Discounts
      additionalProperties: false
      description: Rate card configuration snapshot for a usage-based invoice line.
    UpdateInvoiceRequest:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UpdateInvoiceStandardRequest'
      discriminator:
        propertyName: type
        mapping:
          standard: '#/components/schemas/UpdateInvoiceStandardRequest'
      description: UpdateInvoiceRequest update request.
    UpdateInvoiceStandardLine:
      type: object
      required:
        - name
        - type
        - service_period
        - rate_card
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        id:
          allOf:
            - $ref: '#/components/schemas/ULID'
          description: |-
            ID of the line.

            Optional on update: omit to create a new line, or supply the ID of an existing
            line to edit it. Existing lines omitted from an update's `lines` array are
            deleted.
          title: ID
        type:
          type: string
          enum:
            - standard_line
          description: The type of charge this line item represents.
          title: Type
        service_period:
          allOf:
            - $ref: '#/components/schemas/UpdateClosedPeriod'
          description: |-
            The service period covered by this invoice, spanning the earliest line start to
            the latest line end across all of its lines.

            For an invoice with no lines the period is empty, which means `from` will be
            equal to `to`.
          title: Service period
        rate_card:
          allOf:
            - $ref: '#/components/schemas/UpdateInvoiceLineRateCard'
          description: The rate card configuration snapshot used to price this line item.
          title: Rate card
      additionalProperties: false
      description: |-
        A top-level line item on an invoice.

        Each line represents a single charge, typically associated with a rate card from
        a subscription. Detailed (child) lines are nested under `detailed_lines` when
        present.
    UpdateInvoiceStandardRequest:
      type: object
      required:
        - supplier
        - customer
        - type
        - workflow
      properties:
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        supplier:
          allOf:
            - $ref: '#/components/schemas/UpdateSupplier'
          description: |-
            Snapshot of the supplier's contact information at the time the invoice was
            issued.
          title: Supplier
        customer:
          allOf:
            - $ref: '#/components/schemas/UpdateInvoiceCustomer'
          description: Snapshot of the customer's information at the time the invoice was issued.
          title: Customer
        type:
          type: string
          enum:
            - standard
          description: Discriminator field identifying this as a standard invoice.
          title: Type
        workflow:
          allOf:
            - $ref: '#/components/schemas/UpdateInvoiceWorkflowSettings'
          description: Workflow configuration snapshot captured at invoice creation time.
          title: Workflow
        lines:
          type: array
          items:
            $ref: '#/components/schemas/UpdateInvoiceLine'
          description: |-
            Line items on this invoice.

            Always returned on single-resource GET; omitted on list endpoints unless
            explicitly expanded. Editable via update: existing lines are matched by `id`,
            lines without an `id` are created, and lines present on the invoice but omitted
            from the update request are deleted. Detailed (child) lines are always computed
            and cannot be edited directly.
          title: Lines
      additionalProperties: false
      description: InvoiceStandard update request.
    UpdateInvoiceWorkflowSettings:
      type: object
      required:
        - workflow
      properties:
        workflow:
          allOf:
            - $ref: '#/components/schemas/UpdateBillingInvoiceWorkflow'
          description: |-
            The workflow configuration that was active when the invoice was created.

            Only the fields that are meaningful at the per-invoice level are included:
            invoicing behaviour (auto-advance, draft period) and payment settings
            (collection method, due date). Profile-wide settings such as collection
            alignment, progressive billing, and tax policy are omitted.
          title: Workflow config
      additionalProperties: false
      description: Snapshot of the billing workflow configuration captured at invoice creation.
    UpdateMeterRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        dimensions:
          type: object
          additionalProperties:
            type: string
          description: |-
            Named JSONPath expressions to extract the group by values from the event data.

            Keys must be unique and consist only alphanumeric and underscore characters.
          example:
            type: $.type
      additionalProperties: false
      description: Meter update request.
    UpdateOrganizationDefaultTaxCodesRequest:
      type: object
      properties:
        invoicing_tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: Default tax code for invoicing.
          title: Invoicing tax code
        credit_grant_tax_code:
          allOf:
            - $ref: '#/components/schemas/TaxCodeReference'
          description: Default tax code for credit grants.
          title: Credit grant tax code
      additionalProperties: false
      description: OrganizationDefaultTaxCodes update request.
    UpdatePrice:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UpdatePriceFree'
        - $ref: '#/components/schemas/UpdatePriceFlat'
        - $ref: '#/components/schemas/UpdatePriceUnit'
        - $ref: '#/components/schemas/UpdatePriceGraduated'
        - $ref: '#/components/schemas/UpdatePriceVolume'
      discriminator:
        propertyName: type
        mapping:
          free: '#/components/schemas/UpdatePriceFree'
          flat: '#/components/schemas/UpdatePriceFlat'
          unit: '#/components/schemas/UpdatePriceUnit'
          graduated: '#/components/schemas/UpdatePriceGraduated'
          volume: '#/components/schemas/UpdatePriceVolume'
      description: Price.
    UpdatePriceFlat:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          enum:
            - flat
          description: The type of the price.
          title: Type
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The amount of the flat price.
          title: Amount
      additionalProperties: false
      description: Flat price.
    UpdatePriceFree:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - free
          description: The type of the price.
          title: Type
      additionalProperties: false
      description: Free price.
    UpdatePriceGraduated:
      type: object
      required:
        - type
        - tiers
      properties:
        type:
          type: string
          enum:
            - graduated
          description: The type of the price.
          title: Type
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/UpdatePriceTier'
          minItems: 1
          description: The tiers of the graduated price. At least one tier is required.
          title: Tiers
      additionalProperties: false
      description: |-
        Graduated tiered price.

        Each tier's rate applies only to the usage within that tier. Pricing can change
        as cumulative usage crosses tier boundaries.

        When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
        expressed in converted billing units.
    UpdatePriceTier:
      type: object
      properties:
        up_to_amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: |-
            Up to and including this quantity will be contained in the tier. If undefined,
            the tier is open-ended (the last tier).
          title: Up to quantity
        flat_price:
          allOf:
            - $ref: '#/components/schemas/UpdatePriceFlat'
          description: The flat price component of the tier. Charged once when the tier is entered.
          title: Flat price component
        unit_price:
          allOf:
            - $ref: '#/components/schemas/UpdatePriceUnit'
          description: The unit price component of the tier. Charged per billing unit within the tier.
          title: Unit price component
      additionalProperties: false
      description: |-
        A price tier used in graduated and volume pricing.

        At least one price component (flat_price or unit_price) must be set. When
        UnitConfig is present on the rate card, up_to_amount is expressed in converted
        billing units.
    UpdatePriceUnit:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          enum:
            - unit
          description: The type of the price.
          title: Type
        amount:
          allOf:
            - $ref: '#/components/schemas/Numeric'
          description: The amount of the unit price.
          title: Amount
      additionalProperties: false
      description: |-
        Unit price.

        Charges a fixed rate per billing unit. When UnitConfig is present on the rate
        card, billing units are the converted quantities (e.g. GB instead of bytes).
    UpdatePriceVolume:
      type: object
      required:
        - type
        - tiers
      properties:
        type:
          type: string
          enum:
            - volume
          description: The type of the price.
          title: Type
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/UpdatePriceTier'
          minItems: 1
          description: The tiers of the volume price. At least one tier is required.
          title: Tiers
      additionalProperties: false
      description: |-
        Volume tiered price.

        The maximum quantity within a period determines the per-unit price for all units
        in that period.

        When UnitConfig is present on the rate card, tier boundaries (up_to_amount) are
        expressed in converted billing units.
    UpdateRateCardTaxConfig:
      type: object
      required:
        - code
      properties:
        behavior:
          $ref: '#/components/schemas/BillingTaxBehavior'
        code:
          $ref: '#/components/schemas/UpdateResourceReference'
      additionalProperties: false
      description: The tax config of the rate card.
    UpdateResourceReference:
      type: object
      required:
        - id
      properties:
        id:
          $ref: '#/components/schemas/ULID'
      additionalProperties: false
      description: TaxCode reference.
    UpdateSupplier:
      type: object
      properties:
        name:
          type: string
          description: Legal name or representation of the party.
        tax_id:
          allOf:
            - $ref: '#/components/schemas/UpdateBillingPartyTaxIdentity'
          description: |-
            The entity's legal identification used for tax purposes. They may have other
            numbers, but we're only interested in those valid for tax purposes.
        addresses:
          allOf:
            - $ref: '#/components/schemas/UpdateBillingPartyAddresses'
          description: Address for where information should be sent if needed.
        id:
          type: string
          description: Unique identifier for the party.
      additionalProperties: false
      description: |-
        Snapshot of the supplier's information at the time the invoice was issued.

        Structurally a read-only subset of `BillingParty` (the type configured on the
        billing profile), so the snapshot stays aligned with the source. `key` is
        omitted because it is not part of the snapshotted supplier data.
    UpsertAddonRequest:
      type: object
      required:
        - name
        - instance_type
        - rate_cards
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        instance_type:
          allOf:
            - $ref: '#/components/schemas/AddonInstanceType'
          description: The InstanceType of the add-ons. Can be "single" or "multiple".
          title: The InstanceType of the add-ons. Can be "single" or "multiple".
        rate_cards:
          type: array
          items:
            $ref: '#/components/schemas/BillingRateCard'
          description: The rate cards of the add-on.
          title: Rate cards
      additionalProperties: false
      description: Addon upsert request.
    UpsertAppCustomerDataRequest:
      type: object
      properties:
        stripe:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerDataStripe'
          description: Used if the customer has a linked Stripe app.
          title: Stripe
        external_invoicing:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerDataExternalInvoicing'
          description: Used if the customer has a linked external invoicing app.
          title: External invoicing
      additionalProperties: false
      description: AppCustomerData upsert request.
    UpsertBillingProfileRequest:
      type: object
      required:
        - name
        - supplier
        - workflow
        - default
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        supplier:
          allOf:
            - $ref: '#/components/schemas/BillingParty'
          description: |-
            The name and contact information for the supplier this billing profile
            represents
        workflow:
          allOf:
            - $ref: '#/components/schemas/BillingWorkflow'
          description: The billing workflow settings for this profile
        default:
          type: boolean
          description: Whether this is the default profile.
      additionalProperties: false
      description: BillingProfile upsert request.
    UpsertCustomerBillingDataRequest:
      type: object
      properties:
        billing_profile:
          allOf:
            - $ref: '#/components/schemas/BillingProfileReference'
          description: |-
            The billing profile for the customer.

            If not provided, the default billing profile will be used.
          title: Billing profile
        app_data:
          allOf:
            - $ref: '#/components/schemas/BillingAppCustomerData'
          description: App customer data.
          title: App customer data
      additionalProperties: false
      description: CustomerBillingData upsert request.
    UpsertCustomerRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        usage_attribution:
          allOf:
            - $ref: '#/components/schemas/BillingCustomerUsageAttribution'
          description: Mapping to attribute metered usage to the customer by the event subject.
          title: Usage Attribution
        primary_email:
          type: string
          description: The primary email address of the customer.
          title: Primary Email
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyCode'
          description: Currency of the customer. Used for billing, tax and invoicing.
          title: Currency
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: The billing address of the customer. Used for tax and invoicing.
          title: Billing Address
      additionalProperties: false
      description: Customer upsert request.
    UpsertPlanAddonRequest:
      type: object
      required:
        - name
        - from_plan_phase
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        from_plan_phase:
          allOf:
            - $ref: '#/components/schemas/ResourceKey'
          description: The key of the plan phase from which the add-on becomes available for purchase.
          title: From plan phase
        max_quantity:
          type: integer
          minimum: 1
          description: |-
            The maximum number of times the add-on can be purchased for the plan. For
            single-instance add-ons this field must be omitted. For multi-instance add-ons
            when omitted, unlimited quantity can be purchased.
          title: Max quantity
      additionalProperties: false
      description: PlanAddon upsert request.
    UpsertPlanRequest:
      type: object
      required:
        - name
        - phases
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        pro_rating_enabled:
          type: boolean
          description: Whether pro-rating is enabled for this plan.
          title: Pro-rating enabled
          default: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/BillingPlanPhase'
          minItems: 1
          description: |-
            The plan phases define the pricing ramp for a subscription. A phase switch
            occurs only at the end of a billing period. At least one phase is required.
          title: Plan phases
      additionalProperties: false
      description: Plan upsert request.
    UpsertTaxCodeRequest:
      type: object
      required:
        - name
        - app_mappings
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Display name of the resource.

            Between 1 and 256 characters.
        description:
          type: string
          maxLength: 1024
          description: |-
            Optional description of the resource.

            Maximum 1024 characters.
        labels:
          $ref: '#/components/schemas/Labels'
        app_mappings:
          type: array
          items:
            $ref: '#/components/schemas/BillingTaxCodeAppMapping'
          description: Mapping of app types to tax codes.
          title: App type to tax code mappings
      additionalProperties: false
      description: TaxCode upsert request.
    UsageAttributionSubjectKey:
      type: string
      minLength: 1
      description: Subject key.
    VoidCreditGrantRequest:
      type: object
      properties:
        payment_adjustment:
          allOf:
            - $ref: '#/components/schemas/BillingCreditGrantVoidPaymentAdjustment'
          description: |-
            How voiding adjusts payment state related to the grant.

            Currently only `none` is supported: voiding does not adjust invoices, payment
            authorization, settlement, payment intents, or external collection state. If
            payment later completes, the original invoiced amount may still be collected.
          default: none
      additionalProperties: false
      description: Request body for voiding a credit grant.
    SortQuery:
      title: SortQuery
      type: string
      example: created_at desc
      description: |
        The `asc` suffix is optional as the default sort order is ascending.
        The `desc` suffix is used to specify a descending order.
        Multiple sort attributes may be provided via a comma separated list.
        JSONPath notation may be used to specify a sub-attribute (eg: 'foo.bar desc').
    Labels:
      title: Labels
      type: object
      example:
        env: test
      maxProperties: 50
      description: |
        Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. 

        Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
      additionalProperties:
        type: string
        pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
        minLength: 1
        maxLength: 63
    PageMeta:
      type: object
      description: Contains pagination query parameters and the total number of objects returned.
      required:
        - number
        - size
        - total
      properties:
        number:
          type: number
          example: 1
          x-speakeasy-terraform-ignore: true
        size:
          type: number
          example: 10
          x-speakeasy-terraform-ignore: true
        total:
          type: number
          example: 100
          x-speakeasy-terraform-ignore: true
    PaginatedMeta:
      type: object
      title: PaginatedMeta
      x-speakeasy-terraform-ignore: true
      description: returns the pagination information
      properties:
        page:
          $ref: '#/components/schemas/PageMeta'
      required:
        - page
    BaseError:
      type: object
      title: Error
      description: standard error
      required:
        - status
        - title
        - instance
        - detail
      properties:
        status:
          type: integer
          description: |
            The HTTP status code of the error. Useful when passing the response
            body to child properties in a frontend UI. Must be returned as an integer.
          readOnly: true
        title:
          type: string
          description: |
            A short, human-readable summary of the problem. It should not
            change between occurences of a problem, except for localization.
            Should be provided as "Sentence case" for direct use in the UI.
          readOnly: true
        type:
          type: string
          description: The error type.
          readOnly: true
        instance:
          type: string
          description: |
            Used to return the correlation ID back to the user, in the format
            kong:trace:<correlation_id>. This helps us find the relevant logs
            when a customer reports an issue.
          readOnly: true
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurence of the problem.
            This field may contain request/entity data to help the user understand
            what went wrong. Enclose variable values in square brackets. Should be
            provided as "Sentence case" for direct use in the UI.
          readOnly: true
    InvalidRules:
      description: invalid parameters rules
      type: string
      readOnly: true
      nullable: true
      enum:
        - required
        - is_array
        - is_base64
        - is_boolean
        - is_date_time
        - is_integer
        - is_null
        - is_number
        - is_object
        - is_string
        - is_uuid
        - is_fqdn
        - is_arn
        - unknown_property
        - missing_reference
        - is_label
        - matches_regex
        - invalid
        - is_supported_network_availability_zone_list
        - is_supported_network_cidr_block
        - is_supported_provider_region
        - type
    InvalidParameterStandard:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          $ref: '#/components/schemas/InvalidRules'
        source:
          type: string
          example: body
        reason:
          type: string
          example: is a required field
          readOnly: true
      required:
        - field
        - reason
    InvalidParameterMinimumLength:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          readOnly: true
          nullable: false
          enum:
            - min_length
            - min_digits
            - min_lowercase
            - min_uppercase
            - min_symbols
            - min_items
            - min
        minimum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must have at least 8 characters
          readOnly: true
      required:
        - field
        - reason
        - rule
        - minimum
    InvalidParameterMaximumLength:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          readOnly: true
          nullable: false
          enum:
            - max_length
            - max_items
            - max
        maximum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must not have more than 8 characters
          readOnly: true
      required:
        - field
        - reason
        - rule
        - maximum
    InvalidParameterChoiceItem:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          readOnly: true
          nullable: false
          enum:
            - enum
        reason:
          type: string
          example: is a required field
          readOnly: true
        choices:
          type: array
          uniqueItems: true
          readOnly: true
          nullable: false
          minItems: 1
          items: {}
        source:
          type: string
          example: body
      required:
        - field
        - reason
        - rule
        - choices
    InvalidParameterDependentItem:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          readOnly: true
          nullable: true
          enum:
            - dependent_fields
        reason:
          type: string
          example: is a required field
          readOnly: true
        dependents:
          type: array
          uniqueItems: true
          nullable: true
          items: {}
          readOnly: true
        source:
          type: string
          example: body
      required:
        - field
        - rule
        - reason
        - dependents
    InvalidParameters:
      type: array
      nullable: false
      uniqueItems: true
      minItems: 1
      description: invalid parameters
      items:
        oneOf:
          - $ref: '#/components/schemas/InvalidParameterStandard'
          - $ref: '#/components/schemas/InvalidParameterMinimumLength'
          - $ref: '#/components/schemas/InvalidParameterMaximumLength'
          - $ref: '#/components/schemas/InvalidParameterChoiceItem'
          - $ref: '#/components/schemas/InvalidParameterDependentItem'
    BadRequestError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          required:
            - invalid_parameters
          properties:
            invalid_parameters:
              $ref: '#/components/schemas/InvalidParameters'
    UnauthorizedError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            status:
              example: 401
            title:
              example: Unauthorized
            type:
              example: https://httpstatuses.com/401
            instance:
              example: kong:trace:1234567890
            detail:
              example: Invalid credentials
    ForbiddenError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            status:
              example: 403
            title:
              example: Forbidden
            type:
              example: https://httpstatuses.com/403
            instance:
              example: kong:trace:1234567890
            detail:
              example: Forbidden
    NotFoundError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            status:
              example: 404
            title:
              example: Not Found
            type:
              example: https://httpstatuses.com/404
            instance:
              example: kong:trace:1234567890
            detail:
              example: Not found
    GoneError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            status:
              example: 410
            title:
              example: Gone
            type:
              example: https://httpstatuses.com/410
            instance:
              example: kong:trace:1234567890
            detail:
              example: Gone
    ConflictError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            status:
              example: 409
            title:
              example: Conflict
            type:
              example: https://httpstatuses.com/409
            instance:
              example: kong:trace:1234567890
            detail:
              example: Conflict
    CursorMetaPage:
      type: object
      required:
        - size
        - next
        - previous
      properties:
        first:
          description: URI to the first page
          type: string
          format: path
        last:
          description: URI to the last page
          type: string
          format: path
        next:
          description: URI to the next page
          type: string
          format: path
          nullable: true
        previous:
          description: URI to the previous page
          type: string
          format: path
          nullable: true
        size:
          description: Requested page size
          type: number
          example: 10
    CursorMeta:
      type: object
      description: Pagination metadata.
      required:
        - page
      properties:
        page:
          $ref: '#/components/schemas/CursorMetaPage'
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/ForbiddenExample'
    NotFound:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    Gone:
      description: Gone
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GoneError'
    Conflict:
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ConflictError'
  examples:
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:8347343766220159418
        detail: Unauthorized
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
    NotFoundExample:
      value:
        status: 404
        title: Not Found
        instance: kong:trace:6816496025408232265
        detail: Not Found