Kong OpenMeter Billing API

openapi: 3.1.0
info:
  contact:
    email: support@konghq.com
    name: Kong Inc
    url: https://konghq.com
  description: 'OpenAPI 3.0 spec for Kong Gateway''s Admin API.


    You can learn more about Kong Gateway at [developer.konghq.com](https://developer.konghq.com).

    Give Kong a star at the [Kong/kong](https://github.com/kong/kong) repository.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Kong Enterprise Admin ACLs OpenMeter Billing API
  version: 3.14.0
servers:
- description: Default Admin API URL
  url: '{protocol}://{hostname}:{port}{path}'
  variables:
    hostname:
      default: localhost
      description: Hostname for Kong's Admin API
    path:
      default: /
      description: Base path for Kong's Admin API
    port:
      default: '8001'
      description: Port for Kong's Admin API
    protocol:
      default: http
      description: Protocol for requests to Kong's Admin API
      enum:
      - http
      - https
security:
- adminToken: []
tags:
- name: OpenMeter Billing
  description: Billing manages the billing profiles, currencies, cost bases, and invoices for customers.
paths:
  /v3/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
    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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingProfileRequest'
      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
  /v3/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
    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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertBillingProfileRequest'
      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
    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
components:
  schemas:
    InvalidParameterMinimumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
          - min_length
          - min_digits
          - min_lowercase
          - min_uppercase
          - min_symbols
          - min_items
          - min
          nullable: false
          readOnly: true
          x-speakeasy-unknown-values: allow
        minimum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must have at least 8 characters
          readOnly: true
      additionalProperties: false
      required:
      - field
      - reason
      - rule
      - minimum
    BillingProfilePagePaginatedResponse:
      description: Page paginated response.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingProfile'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      required:
      - data
      - meta
    BillingWorkflowCollectionAlignmentAnchored:
      description: 'BillingWorkflowCollectionAlignmentAnchored specifies the alignment for collecting the pending line items

        into an invoice.'
      type: object
      properties:
        type:
          description: The type of alignment.
          type: string
          enum:
          - anchored
        recurring_period:
          description: The recurring period for the alignment.
          type: object
          properties:
            anchor:
              description: A date-time anchor to base the recurring period on.
              type: string
              format: date-time
              example: '2023-01-01T01:01:01.001Z'
              title: Anchor time
            interval:
              description: The interval duration in ISO 8601 format.
              type: string
              format: ISO8601
              example: P1M
              pattern: ^P(?:\d+(?:\.\d+)?Y)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?W)?(?:\d+(?:\.\d+)?D)?(?:T(?:\d+(?:\.\d+)?H)?(?:\d+(?:\.\d+)?M)?(?:\d+(?:\.\d+)?S)?)?$
              title: Interval in ISO 8601 duration format
          required:
          - anchor
          - interval
      required:
      - type
      - recurring_period
    InvalidParameterChoiceItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
          - enum
          nullable: false
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        choices:
          type: array
          items: {}
          minItems: 1
          nullable: false
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
      - field
      - reason
      - rule
      - choices
    BillingProfile:
      description: Billing profiles contain the settings for billing and controls invoice generation.
      type: object
      properties:
        id:
          description: ULID (Universally Unique Lexicographically Sortable Identifier).
          type: string
          example: 01G65Z755AFWAKHE12NY0CQ9FH
          pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
          readOnly: true
          title: ULID
        name:
          description: 'Display name of the resource.


            Between 1 and 256 characters.'
          type: string
          maxLength: 256
          minLength: 1
        description:
          description: 'Optional description of the resource.


            Maximum 1024 characters.'
          type: string
          maxLength: 1024
        labels:
          $ref: '#/components/schemas/Labels'
        created_at:
          description: An ISO-8601 timestamp representation of entity creation date.
          type: string
          format: date-time
          example: '2023-01-01T01:01:01.001Z'
          readOnly: true
          title: RFC3339 Date-Time
        updated_at:
          description: An ISO-8601 timestamp representation of entity last update date.
          type: string
          format: date-time
          example: '2023-01-01T01:01:01.001Z'
          readOnly: true
          title: RFC3339 Date-Time
        deleted_at:
          description: An ISO-8601 timestamp representation of entity deletion date.
          type: string
          format: date-time
          example: '2023-01-01T01:01:01.001Z'
          readOnly: true
          title: RFC3339 Date-Time
        supplier:
          description: The name and contact information for the supplier this billing profile represents
          type: object
          properties:
            id:
              description: Unique identifier for the party.
              type: string
              readOnly: true
            key:
              description: An optional unique key of the party.
              type: string
              example: 019ae40f-4258-7f15-9491-842f42a7d6ac
              maxLength: 256
              minLength: 1
              title: External Resource Key
            name:
              description: Legal name or representation of the party.
              type: string
            tax_id:
              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.'
              type: object
              properties:
                code:
                  description: Normalized tax identification code shown on the original identity document.
                  type: string
                  maxLength: 32
                  minLength: 1
            addresses:
              description: Address for where information should be sent if needed.
              type: object
              properties:
                billing_address:
                  description: Billing address.
                  type: object
                  properties:
                    country:
                      description: Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 format.
                      type: string
                      example: US
                      maxLength: 2
                      minLength: 2
                      pattern: ^[A-Z]{2}$
                      title: Country
                    postal_code:
                      description: Postal code.
                      type: string
                      title: Postal Code
                    state:
                      description: State or province.
                      type: string
                      title: State
                    city:
                      description: City.
                      type: string
                      title: City
                    line1:
                      description: First line of the address.
                      type: string
                      title: Line 1
                    line2:
                      description: Second line of the address.
                      type: string
                      title: Line 2
                    phone_number:
                      description: Phone number.
                      type: string
                      title: Phone Number
              required:
              - billing_address
        workflow:
          description: The billing workflow settings for this profile
          type: object
          properties:
            collection:
              description: The collection settings for this workflow
              type: object
              properties:
                alignment:
                  description: The alignment for collecting the pending line items into an invoice.
                  type: object
                  default:
                    type: subscription
                  discriminator:
                    propertyName: type
                    mapping:
                      subscription: '#/components/schemas/BillingWorkflowCollectionAlignmentSubscription'
                      anchored: '#/components/schemas/BillingWorkflowCollectionAlignmentAnchored'
                  oneOf:
                  - $ref: '#/components/schemas/BillingWorkflowCollectionAlignmentSubscription'
                  - $ref: '#/components/schemas/BillingWorkflowCollectionAlignmentAnchored'
                interval:
                  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.'
                  type: string
                  format: ISO8601
                  example: P1D
                  default: PT1H
              title: Workflow collection settings
            invoicing:
              description: The invoicing settings for this workflow
              type: object
              properties:
                auto_advance:
                  description: Whether to automatically issue the invoice after the draftPeriod has passed.
                  type: boolean
                  default: true
                draft_period:
                  description: The period for the invoice to be kept in draft status for manual reviews.
                  type: string
                  format: ISO8601
                  example: P1D
                  default: P0D
                progressive_billing:
                  description: Should progressive billing be allowed for this workflow?
                  type: boolean
                  default: true
              title: Workflow invoice settings
            payment:
              description: The payment settings for this workflow
              type: object
              discriminator:
                propertyName: collection_method
                mapping:
                  charge_automatically: '#/components/schemas/BillingWorkflowPaymentChargeAutomaticallySettings'
                  send_invoice: '#/components/schemas/BillingWorkflowPaymentSendInvoiceSettings'
              oneOf:
              - $ref: '#/components/schemas/BillingWorkflowPaymentChargeAutomaticallySettings'
              - $ref: '#/components/schemas/BillingWorkflowPaymentSendInvoiceSettings'
            tax:
              description: The tax settings for this workflow
              type: object
              properties:
                enabled:
                  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.'
                  type: boolean
                  default: true
                enforced:
                  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.'
                  type: boolean
                  default: false
                default_tax_config:
                  description: Default tax configuration to apply to the invoices for line items.
                  type: object
                  properties:
                    behavior:
                      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.'
                      type: string
                      enum:
                      - inclusive
                      - exclusive
                      title: Tax behavior
                      x-speakeasy-unknown-values: allow
                    stripe:
                      description: Stripe tax config.
                      type: object
                      deprecated: true
                      properties:
                        code:
                          description: Product [tax code](https://docs.stripe.com/tax/tax-codes).
                          type: string
                          example: txcd_10000000
                          pattern: ^txcd_\d{8}$
                          title: Tax code
                      required:
                      - code
                      title: Stripe tax config
                    external_invoicing:
                      description: External invoicing tax config.
                      type: object
                      deprecated: true
                      properties:
                        code:
                          description: The tax code should be interpreted by the external invoicing provider.
                          type: string
                          maxLength: 64
                          title: Tax code
                      required:
                      - code
                      title: External invoicing tax config
                    tax_code_id:
                      description: Tax code ID.
                      type: string
                      example: 01G65Z755AFWAKHE12NY0CQ9FH
                      deprecated: true
                      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
                      title: Tax code ID
                    tax_code:
                      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.'
                      type: object
                      properties:
                        id:
                          $ref: '#/components/schemas/ULID'
                      required:
                      - id
                      title: Tax code
              title: Workflow tax settings
        apps:
          description: The applications used by this billing profile.
          type: object
          properties:
            tax:
              description: The tax app used for this workflow.
              type: object
              properties:
                id:
                  description: The ID of the app.
                  type: string
                  example: 01G65Z755AFWAKHE12NY0CQ9FH
                  pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
                  title: ULID
              required:
              - id
            invoicing:
              description: The invoicing app used for this workflow.
              type: object
              properties:
                id:
                  description: The ID of the app.
                  type: string
                  example: 01G65Z755AFWAKHE12NY0CQ9FH
                  pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
                  title: ULID
              required:
              - id
            payment:
              description: The payment app used for this workflow.
              type: object
              properties:
                id:
                  description: The ID of the app.
                  type: string
                  example: 01G65Z755AFWAKHE12NY0CQ9FH
                  pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
                  title: ULID
              required:
              - id
          required:
          - tax
          - invoicing
          - payment
        default:
          description: Whether this is the default profile.
          type: boolean
      required:
      - id
      - name
      - created_at
      - updated_at
      - supplier
      - workflow
      - apps
      - default
    InvalidParameterMaximumLength:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
          - max_length
          - max_items
          - max
          nullable: false
          readOnly: true
          x-speakeasy-unknown-values: allow
        maximum:
          type: integer
          example: 8
        source:
          type: string
          example: body
        reason:
          type: string
          example: must not have more than 8 characters
          readOnly: true
      additionalProperties: false
      required:
      - field
      - reason
      - rule
      - maximum
    Labels:
      description: "Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. \n\nKeys must be of length 1-63 characters, and cannot start with \"kong\", \"konnect\", \"mesh\", \"kic\", or \"_\".\n"
      type: object
      example:
        env: test
      additionalProperties:
        type: string
        pattern: ^[a-z0-9A-Z]{1}([a-z0-9A-Z-._]*[a-z0-9A-Z]+)?$
        minLength: 1
        maxLength: 63
      maxProperties: 50
      title: Labels
    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
    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
    BillingWorkflowPaymentSendInvoiceSettings:
      description: Payment settings for a billing workflow when the collection method is send invoice.
      type: object
      properties:
        collection_method:
          description: The collection method for the invoice.
          type: string
          enum:
          - send_invoice
        due_after:
          description: 'The period after which the invoice is due.

            With some payment solutions it''s only applicable for manual collection method.'
          type: string
          format: ISO8601
          example: P30D
          default: P30D
      required:
      - collection_method
    PaginatedMeta:
      description: returns the pagination information
      type: object
      properties:
        page:
          $ref: '#/components/schemas/PageMeta'
      required:
      - page
      title: PaginatedMeta
      x-speakeasy-terraform-ignore: true
    BaseError:
      description: standard error
      type: object
      properties:
        status:
          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.

            '
          type: integer
          readOnly: true
        title:
          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.

            '
          type: string
          readOnly: true
        type:
          description: The error type.
          type: string
          readOnly: true
        instance:
          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.

            '
          type: string
          readOnly: true
        detail:
          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.

            '
          type: string
          readOnly: true
      required:
      - status
      - title
      - instance
      - detail
      title: Error
    InvalidParameterDependentItem:
      type: object
      properties:
        field:
          type: string
          example: name
          readOnly: true
        rule:
          description: invalid parameters rules
          type: string
          enum:
          - dependent_fields
          nullable: true
          readOnly: true
        reason:
          type: string
          example: is a required field
          readOnly: true
        dependents:
          type: array
          items: {}
          nullable: true
          readOnly: true
          uniqueItems: true
        source:
          type: string
          example: body
      additionalProperties: false
      required:
      - field
      - rule
      - reason
      - dependents
    InvalidRules:
      description: invalid parameters rules
      type: string
      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
      nullable: true
      readOnly: true
      x-speakeasy-unknown-values: allow
    InvalidParameters:
      description: invalid parameters
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/InvalidParameterStandard'
        - $ref: '#/components/schemas/InvalidParameterMinimumLength'
        - $ref: '#/components/schemas/InvalidParameterMaximumLength'
        - $ref: '#/components/schemas/InvalidParameterChoiceItem'
        - $ref: '#/components/schemas/InvalidParameterDependentItem'
      minItems: 1
      nullable: false
      uniqueItems: true
    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/BaseError'
      - type: object
        required:
        - invalid_parameters
        properties:
          invalid_parameters:
            $ref: '#/components/schemas/InvalidParameters'
    CreateBillingProfileRequest:
      description: BillingProfile create request.
      type: object
      properties:
        name:
          description: 'Display name of the resource.


            Between 1 and 256 characters.'
          type: string
          maxLength: 256
          minLength: 1
        description:
          description: 'Optional description of the resource.


            Maximum 1024 characters.'
          type: string
          maxLength: 1024
        labels:
          $ref: '#/components/schemas/Labels'
        supplier:
          description: The name and contact information for the supplier this billing profile represents
          type: object
          properties:
            id:
              description: Unique identifier for the party.
              type: string
              readOnly: true
            key:
              description: An optional unique key of the party.
              type: string
              example: 019ae40f-4258-7f15-9491-842f42a7d6ac
              maxLength: 256
              minLength: 1
              title: External Resource Key
            name:
              description: Legal name or representation of the party.
              type: string
            tax_id:
              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.'
              type: object
              properties:
                code:
                  description: Normalized tax identification code shown on the original identity document.
                  type: string
                  maxLength: 32
                  minLength: 1
            addresses:
              description: Address for where information should be sent if needed.
              type: object
              properties:
                billing_address:
                  description: Billing address.
                  type: object
                  properties:
                    country:
                      description: Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 format.
                      type: string
                      example: US
                      maxLength: 2
                      minLength: 2
                      pattern: ^[A-Z]{2}$
                      title: Country
                    postal_code:
                      description: Postal code.
                      type: string
                      title: Postal Code
                    state:
                      description: State or province.
                      type: string
                      title: State
                    city:
                      description: City.
                      type: string
                      title: City
                    line1:
                      description: First line of the address.
                      type: string
                      title: Line 1
                    line2:
                      description: Second line of the address.
                      type: string
                      title: Line 2
                    phone_number:
                      description: Phone number.
                      type: string
                      title: Phone Number
              required:
              - billing_address
        workflow:
          description: The billing workflow settings for this profile
          type: object
          properties:
            collection:
              description: The collection settings for this workflow
              type: object
              properties:
                alignment:
                  description: The alignment for collecting the pending line items into an invoice.
                  type: object
                  default:
                    type: subscription
                  discriminator:
                    propertyName: type
                    mapping:
                      subscription: '#/components/schemas/BillingWorkflowCollectionAlignmentSubscription'
                      anchored: '#/components/schemas/BillingWorkflowCollectionAlignmentAnchored'
                  oneOf:
                  - $ref: '#/components/schemas/BillingWorkflowCollectionAlign

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kong/refs/heads/main/openapi/kong-openmeter-billing-api-openapi.yml