Kong OpenMeter Billing API

openapi: 3.2.0
info:
  title: Konnect API - Go SDK OpenMeter Billing API
  version: 3.14.0
  description: The Konnect platform API
  contact:
    name: Kong Inc
    url: https://konghq.com
    email: support@konghq.com
  x-extensions-note: "This API uses the `x-expression` vendor extension to indicate that a string property is a DSL expression.\nSupported types:\n\n\n  - `boolean`: An expression evaluates to boolean. For example, `context.topic.name == 'my-topic'`\n  - `string`: A template string expression that evaluates to a string or a literal string value. For example,\n    `${context.topic.name.substring(0, context.topic.name.length-4)}` or `my-literal-value`\n\nAdditionally, `x-sensitive` flag indicates that a field contains sensitive information. When the value\nof the field is provided in plain text, it's encrypted at rest and it's never returned in API responses.\nWhen the value is an expression, the expression itself is stored and returned in API responses.\n\n`x-min-runtime-version` indicates the minimum Event Gateway runtime version required to use a certain policy or\npolicy feature. The runtime version can be configured at the Event Gateway entity level. It must be a string\ncontaining a semantic version in the `MAJOR.MINOR` format, e.g., `\"1.1\"`.\n"
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-oas-source: kong/platform-api@
  x-oas-source-link: https://github.com/Kong/platform-api/commit/
servers:
- url: https://global.api.konghq.com
- url: https://us.api.konghq.com
- url: https://eu.api.konghq.com
- url: https://au.api.konghq.com
security:
- personalAccessToken: []
- systemAccountAccessToken: []
- konnectAccessToken: []
- serviceAccessToken: []
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:
    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/BaseError'
      - type: object
        required:
        - invalid_parameters
        properties:
          invalid_parameters:
            $ref: '#/components/schemas/InvalidParameters'
    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
    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
    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/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:
      - name
      - supplier
      - workflow
      - apps
      - default
    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
    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
    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
    BillingProfilePagePaginatedResponse:
      description: Page paginated response.
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingProfile'
        meta:
          $ref: '#/components/schemas/PaginatedMeta'
      required:
      - data
      - meta
    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
    PageMeta:
      description: Contains pagination query parameters and the total number of objects returned.
      type: object
      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
      required:
      - number
      - size
      - total
    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
    InvalidParameterStandard:
      type: object
      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
      additionalProperties: false
      required:
      - field
      - reason
    ULID:
      description: ULID (Universally Unique Lexicographically Sortable Identifier).
      type: string
      example: 01G65Z755AFWAKHE12NY0CQ9FH
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      title: ULID
    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
    BillingWorkflowPaymentChargeAutomaticallySettings:
      description: Payment settings for a billing workflow when the collection method is charge automatically.
      type: object
      properties:
        collection_method:
          description: The collection method for the invoice.
          type: string
          enum:
          - charge_automatically
      required:
      - collection_method
    UpsertBillingProfileRequest:
      description: BillingProfile upsert 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/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: 

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