--- title: "List customer charges" method: GET path: "/v3/openmeter/customers/{customerId}/charges" tags: ["OpenMeter Customers"] --- # List customer charges `GET /v3/openmeter/customers/{customerId}/charges` ## Request - Base URL: `https://global.api.konghq.com` - URL: `https://global.api.konghq.com/v3/openmeter/customers/{customerId}/charges` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP bearer - HTTP bearer **Pre-release Endpoint** This endpoint is currently in beta and is subject to change. List customer charges. Returns the customer's charges that are represented as either flat fee or usage-based charges. ## Path parameters - `customerId` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). ## Query parameters - `page` object - `size` integer: The number of items to include per page. - `number` integer: The page number. - `sort` string: 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'). - `filter` ListCustomerChargesParamsFilter: Filter options for listing charges. - `status` object: Filter charges by status. Supported statuses are: - `created` - `active` - `final` - `deleted` If omitted, all statuses are returned except for `deleted`. - `eq` string - `oeq` string, required - `neq` string, required - `feature_id` union: Filter charges by the ID of their associated feature. - string: ULID (Universally Unique Lexicographically Sortable Identifier). - object - `eq` string: Value strictly equals the given ULID value. - `oeq` string: Returns entities that exact match any of the comma-delimited ULIDs in the filter string. - `neq` string: Value does not equal the given ULID value. - `feature_key` object: Filter charges by the key of their associated feature. - `eq` string - `oeq` string, required - `neq` string, required - `service_period_from` union: Filter charges by the start of their service period. - object - `eq` string, date-time, required: Value strictly equals given RFC-3339 formatted timestamp in UTC - object - `lt` string, date-time, required: Value is less than the given RFC-3339 formatted timestamp in UTC - object - `lte` string, date-time, required: Value is less than or equal to the given RFC-3339 formatted timestamp in UTC - object - `gt` string, date-time, required: Value is greater than the given RFC-3339 formatted timestamp in UTC - object - `gte` string, date-time, required: Value is greater than or equal to the given RFC-3339 formatted timestamp in UTC - `service_period_to` union: Filter charges by the end of their service period. - object - `eq` string, date-time, required: Value strictly equals given RFC-3339 formatted timestamp in UTC - object - `lt` string, date-time, required: Value is less than the given RFC-3339 formatted timestamp in UTC - object - `lte` string, date-time, required: Value is less than or equal to the given RFC-3339 formatted timestamp in UTC - object - `gt` string, date-time, required: Value is greater than the given RFC-3339 formatted timestamp in UTC - object - `gte` string, date-time, required: Value is greater than or equal to the given RFC-3339 formatted timestamp in UTC - `expand` BillingChargesExpand[] ## Response `200` Page paginated response. - ChargePagePaginatedResponse: Page paginated response. - `data` BillingCharge[], required - union: Customer charge. - object: A flat fee charge for a customer. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `type` 'flat_fee', required: The type of the charge. - `customer` union, required: The customer owning the charge. By default, only the `id` of the customer is returned. For more details use the `customer` expand. - BillingCustomer: Customers can be individuals or organizations that can subscribe to plans and have access to features. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `key` string, required: ExternalResourceKey is a unique string that is used to identify a resource in an external system. - `usage_attribution` object: Mapping to attribute metered usage to the customer by the event subject. - … - `primary_email` string: The primary email address of the customer. - `currency` string: Currency of the customer. Used for billing, tax and invoicing. - `billing_address` object: The billing address of the customer. Used for tax and invoicing. - … - CustomerReference: Customer reference. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `lifecycle_controller` 'system' | 'manual', required: Indicates whether the charge lifecycle is controlled by the system or manually overridden by the API user. - `subscription` union: The subscription that originated the charge, when the charge was created from a subscription item. By default, only the `id`, `phase.id`, `phase.item.id` of the subscription is returned. For more details use the `subscription` expand. - BillingSubscription: Subscription. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `name` string, required: Display name of the subscription. Defaults to the plan name when the subscription is created from a plan. - `description` string: Optional description of the subscription. - `active_from` string, date-time, required: An ISO-8601 timestamp representation of when the subscription became (or will become) active. - `active_to` string, date-time: An ISO-8601 timestamp representation of when the subscription stops being active. Open-ended when not set. - `customer_id` string, required: The customer ID of the subscription. - `plan_id` string: The plan ID of the subscription. Set if subscription is created from a plan. - `plan` object: The plan the subscription was created from, if any. Includes the plan key and version so clients can resolve the exact plan revision. - … - `invoice_currency` string, required: The fiat currency in which the subscription is invoiced. - `cost_basis_mode` 'dynamic' | 'pinned', required: Controls whether custom-currency cost bases are resolved dynamically or pinned when their currency pair is introduced to the subscription. - `cost_basis_pins` BillingSubscriptionCostBasisPin[], required: Cost bases pinned to custom-currency pairs for this subscription. - … - `billing_cadence` string, ISO8601, required: The billing cadence of the subscription in ISO-8601 duration format. Defines how often the customer is billed. Examples: `P1M` (monthly), `P3M` (quarterly), `P1Y` (annually). - `pro_rating_config` object: The pro-rating configuration of the subscription. - … - `billing_anchor` string, date-time, required: 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) - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required: The status of the subscription. - `settlement_mode` 'credit_then_invoice' | 'credit_only': 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. - `current_period` object: The current aligned billing period. Present only when the subscription is active and aligned. - … - `phases` BillingSubscriptionPhase[], required: The phases of the subscription in chronological order. A phase groups the rate cards that are in effect for a segment of the subscription's lifetime. - … - BillingSubscriptionReference: Subscription reference represents a reference to the specific subscription item this entity represents. - `id` string, required: The ID of the subscription. - `name` string: The display name of the subscription. Only populated where the referencing endpoint documents a `subscription` expand that resolves it. - `phase` object, required: The phase of the subscription. - … - `currency` union, required: The currency of the charge. - string: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string: Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `resolved_cost_basis` object: The resolved fiat conversion rate of a custom-currency charge. Resolution depends on costbasis type: dynamic is resolved when charge becomes active, all other types resolved on creation. - `fiat_currency` string, required: The fiat currency the charge amount is converted into for invoicing. - `rate` string, required: Fiat amount per one unit of the custom currency. - `cost_basis_id` string: ID of the custom currency's cost basis resource the rate was taken from. Absent for manual cost bases. - `resolved_at` string, date-time, required: When the rate was resolved. - `status` 'created' | 'active' | 'final' | 'deleted', required: The lifecycle status of the charge. - `validation_issues` BillingValidationIssue[]: Validation issues found while processing the charge. Present only when there are one or more validation findings. An empty list is omitted. - `code` string, required: Machine-readable error code. - `message` string, required: Human-readable description of the error. - `attributes` object: Additional structured context. - `severity` 'critical' | 'warning', required: Severity of the validation issue. - `field` string: JSON path to the field that caused the validation issue, if applicable. - `component` string: Component that reported the validation issue, if applicable. - `invoice_at` string, date-time, required: The timestamp when the charge is intended to be invoiced. - `service_period` object, required: The effective service period covered by the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `full_service_period` object, required: The full, unprorated service period of the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `billing_period` object, required: The billing period the charge belongs to. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `advance_after` string, date-time: The earliest time when the charge should be advanced again by background processing. - `unique_reference_id` string: Unique reference ID of the charge. - `settlement_mode` 'credit_then_invoice' | 'credit_only', required: Settlement mode of the charge. - `tax_config` object: Tax configuration of the charge. - `behavior` 'inclusive' | 'exclusive': 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. - `stripe` object: Stripe tax config. - `code` string, required: Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` object: External invoicing tax config. - `code` string, required: The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string: Tax code ID. - `tax_code` object: 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. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `realizations` BillingChargeRealization[], required: The realization runs of the charge, sorted by `created_at`. - `id` string: The ID of the realization run. Not present on `outstanding` entries, which are projections rather than persisted runs. - `line_id` string: The ID of the invoice line this realization was booked to, when the realization has been invoiced. - `invoice` union: The reference of the invoice related to the realization. - BillingChargeRealizationInvoice: The invoice a charge realization was booked to, embedded as a header. Matches the standard invoice entity, except that it carries no `customer` snapshot (the charge context already identifies the customer) and `lines` are never populated (the realization itself is the line-level breakdown). The shared invoice contract stays untouched: this model exists so the charges API can slim the embedding without loosening the invoices API. - … - ChargeRealizationInvoiceReference: ChargeRealizationInvoice reference. - … - `type` 'final_realization' | 'partial_invoice' | 'outstanding' | 'voided', required: The type of the realization run. - `service_period` object, required: The service period covered by this realization run. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `usage` string: The metered usage quantity this realization run accounts for. Only present on usage-based charges; flat fees are not metered, so their realizations carry no usage. Booked entries report a signed delta: a negative value states a downward usage correction (or a voided run that snapshotted behind its live neighbors) instead of masking it as zero. On an `outstanding` entry this is `0` unless the `real_time_usage` expand is applied, in which case it is the not-yet-booked remainder of the live metering read (never negative). - `payment` object: The payment state of the realization, when the charge requires a fiat transaction to settle. - `status` 'authorized' | 'settled', required: The settlement status of the payment. - `totals` object: Financial totals for the realization run, including credit allocations. Requires the `realization.totals` expand. - `amount` string, required: The total value of the resource before taxes, discounts and commitments. - `taxes_total` string, required: The total tax amount applied to the resource. - `taxes_inclusive_total` string, required: The total tax amount already included in the resource amount. - `taxes_exclusive_total` string, required: The total tax amount added on top of the resource amount. - `charges_total` string, required: The total amount contributed by additional charges. - `discounts_total` string, required: The total amount deducted through discounts. - `credits_total` string, required: The total amount deducted through credits before taxes are applied. - `total` string, required: The final total value of the resource after taxes, discounts and commitments. - `detailed_lines` BillingChargeRealizationDetailedLine[]: The detailed (rated) lines produced by the realization run. Requires the `realization.detailed_lines` expand. - union: A detailed (child) line type of a charge realization run. This is distinct from an invoice's own detailed lines: it represents the rated/priced breakdown produced by the realization run itself, before that breakdown is (or is not yet) reflected on an invoice line. Credit-then-invoice runs include credit allocations in these lines, while credits-only runs keep the gross rated detail. - … - `payment_term` 'in_advance' | 'in_arrears', required: Payment term of the flat fee charge. - `discounts` object: The discounts applied to the charge. - `percentage` number: Percentage discount applied to the price (0–100). - `feature` union: The feature associated with the charge, when applicable. - Feature: A capability or billable dimension offered by a provider. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `key` string, required: A key is a unique string that is used to identify a resource. - `meter` object: The meter that the feature is associated with and based on which usage is calculated. If not specified, the feature is static. - … - `unit_cost` union: 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. - … - FeatureReference: Feature reference. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `proration_configuration` object, required: The proration configuration of the charge. - `mode` 'no_proration' | 'prorate_prices', required: The proration mode of the rate card. - `amount_after_proration` object, required: The amount after proration of the charge. - `amount` string, required: The amount as an arbitrary-precision decimal string. - `currency` union, required: The fiat or custom currency code of the amount. - string: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string: Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `price` object, required: The price of the charge. - `type` 'flat', required: The type of the price. - `amount` string, required: The amount of the flat price. - `system_intent` object: 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. - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `invoice_at` string, date-time, required: The timestamp when the charge is intended to be invoiced. - `service_period` object, required: The effective service period covered by the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `full_service_period` object, required: The full, unprorated service period of the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `billing_period` object, required: The billing period the charge belongs to. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `payment_term` 'in_advance' | 'in_arrears', required: Payment term of the flat fee charge. - `discounts` object: The discounts applied to the charge. - `percentage` number: Percentage discount applied to the price (0–100). - `proration_configuration` object, required: The proration configuration of the charge. - `mode` 'no_proration' | 'prorate_prices', required: The proration mode of the rate card. - `amount_before_proration` object, required: The amount before proration of the system lifecycle controller flat fee intent. - `amount` string, required: The amount as an arbitrary-precision decimal string. - `currency` union, required: The fiat or custom currency code of the amount. - … - `deleted_at` string, date-time: The timestamp when the system lifecycle controller intent was deleted. The effective charge can remain visible while a manual override is active. - object: A usage-based charge for a customer. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `type` 'usage_based', required: The type of the charge. - `customer` union, required: The customer owning the charge. By default, only the `id` of the customer is returned. For more details use the `customer` expand. - BillingCustomer: Customers can be individuals or organizations that can subscribe to plans and have access to features. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `key` string, required: ExternalResourceKey is a unique string that is used to identify a resource in an external system. - `usage_attribution` object: Mapping to attribute metered usage to the customer by the event subject. - … - `primary_email` string: The primary email address of the customer. - `currency` string: Currency of the customer. Used for billing, tax and invoicing. - `billing_address` object: The billing address of the customer. Used for tax and invoicing. - … - CustomerReference: Customer reference. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `lifecycle_controller` 'system' | 'manual', required: Indicates whether the charge lifecycle is controlled by the system or manually overridden by the API user. - `subscription` union: The subscription that originated the charge, when the charge was created from a subscription item. By default, only the `id`, `phase.id`, `phase.item.id` of the subscription is returned. For more details use the `subscription` expand. - BillingSubscription: Subscription. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `name` string, required: Display name of the subscription. Defaults to the plan name when the subscription is created from a plan. - `description` string: Optional description of the subscription. - `active_from` string, date-time, required: An ISO-8601 timestamp representation of when the subscription became (or will become) active. - `active_to` string, date-time: An ISO-8601 timestamp representation of when the subscription stops being active. Open-ended when not set. - `customer_id` string, required: The customer ID of the subscription. - `plan_id` string: The plan ID of the subscription. Set if subscription is created from a plan. - `plan` object: The plan the subscription was created from, if any. Includes the plan key and version so clients can resolve the exact plan revision. - … - `invoice_currency` string, required: The fiat currency in which the subscription is invoiced. - `cost_basis_mode` 'dynamic' | 'pinned', required: Controls whether custom-currency cost bases are resolved dynamically or pinned when their currency pair is introduced to the subscription. - `cost_basis_pins` BillingSubscriptionCostBasisPin[], required: Cost bases pinned to custom-currency pairs for this subscription. - … - `billing_cadence` string, ISO8601, required: The billing cadence of the subscription in ISO-8601 duration format. Defines how often the customer is billed. Examples: `P1M` (monthly), `P3M` (quarterly), `P1Y` (annually). - `pro_rating_config` object: The pro-rating configuration of the subscription. - … - `billing_anchor` string, date-time, required: 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) - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required: The status of the subscription. - `settlement_mode` 'credit_then_invoice' | 'credit_only': 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. - `current_period` object: The current aligned billing period. Present only when the subscription is active and aligned. - … - `phases` BillingSubscriptionPhase[], required: The phases of the subscription in chronological order. A phase groups the rate cards that are in effect for a segment of the subscription's lifetime. - … - BillingSubscriptionReference: Subscription reference represents a reference to the specific subscription item this entity represents. - `id` string, required: The ID of the subscription. - `name` string: The display name of the subscription. Only populated where the referencing endpoint documents a `subscription` expand that resolves it. - `phase` object, required: The phase of the subscription. - … - `currency` union, required: The currency of the charge. - string: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string: Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `resolved_cost_basis` object: The resolved fiat conversion rate of a custom-currency charge. Resolution depends on costbasis type: dynamic is resolved when charge becomes active, all other types resolved on creation. - `fiat_currency` string, required: The fiat currency the charge amount is converted into for invoicing. - `rate` string, required: Fiat amount per one unit of the custom currency. - `cost_basis_id` string: ID of the custom currency's cost basis resource the rate was taken from. Absent for manual cost bases. - `resolved_at` string, date-time, required: When the rate was resolved. - `status` 'created' | 'active' | 'final' | 'deleted', required: The lifecycle status of the charge. - `validation_issues` BillingValidationIssue[]: Validation issues found while processing the charge. Present only when there are one or more validation findings. An empty list is omitted. - `code` string, required: Machine-readable error code. - `message` string, required: Human-readable description of the error. - `attributes` object: Additional structured context. - `severity` 'critical' | 'warning', required: Severity of the validation issue. - `field` string: JSON path to the field that caused the validation issue, if applicable. - `component` string: Component that reported the validation issue, if applicable. - `invoice_at` string, date-time, required: The timestamp when the charge is intended to be invoiced. - `service_period` object, required: The effective service period covered by the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `full_service_period` object, required: The full, unprorated service period of the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `billing_period` object, required: The billing period the charge belongs to. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `advance_after` string, date-time: The earliest time when the charge should be advanced again by background processing. - `unique_reference_id` string: Unique reference ID of the charge. - `settlement_mode` 'credit_then_invoice' | 'credit_only', required: Settlement mode of the charge. - `tax_config` object: Tax configuration of the charge. - `behavior` 'inclusive' | 'exclusive': 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. - `stripe` object: Stripe tax config. - `code` string, required: Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` object: External invoicing tax config. - `code` string, required: The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string: Tax code ID. - `tax_code` object: 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. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `realizations` BillingChargeRealization[], required: The realization runs of the charge, sorted by `created_at`. - `id` string: The ID of the realization run. Not present on `outstanding` entries, which are projections rather than persisted runs. - `line_id` string: The ID of the invoice line this realization was booked to, when the realization has been invoiced. - `invoice` union: The reference of the invoice related to the realization. - BillingChargeRealizationInvoice: The invoice a charge realization was booked to, embedded as a header. Matches the standard invoice entity, except that it carries no `customer` snapshot (the charge context already identifies the customer) and `lines` are never populated (the realization itself is the line-level breakdown). The shared invoice contract stays untouched: this model exists so the charges API can slim the embedding without loosening the invoices API. - … - ChargeRealizationInvoiceReference: ChargeRealizationInvoice reference. - … - `type` 'final_realization' | 'partial_invoice' | 'outstanding' | 'voided', required: The type of the realization run. - `service_period` object, required: The service period covered by this realization run. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `usage` string: The metered usage quantity this realization run accounts for. Only present on usage-based charges; flat fees are not metered, so their realizations carry no usage. Booked entries report a signed delta: a negative value states a downward usage correction (or a voided run that snapshotted behind its live neighbors) instead of masking it as zero. On an `outstanding` entry this is `0` unless the `real_time_usage` expand is applied, in which case it is the not-yet-booked remainder of the live metering read (never negative). - `payment` object: The payment state of the realization, when the charge requires a fiat transaction to settle. - `status` 'authorized' | 'settled', required: The settlement status of the payment. - `totals` object: Financial totals for the realization run, including credit allocations. Requires the `realization.totals` expand. - `amount` string, required: The total value of the resource before taxes, discounts and commitments. - `taxes_total` string, required: The total tax amount applied to the resource. - `taxes_inclusive_total` string, required: The total tax amount already included in the resource amount. - `taxes_exclusive_total` string, required: The total tax amount added on top of the resource amount. - `charges_total` string, required: The total amount contributed by additional charges. - `discounts_total` string, required: The total amount deducted through discounts. - `credits_total` string, required: The total amount deducted through credits before taxes are applied. - `total` string, required: The final total value of the resource after taxes, discounts and commitments. - `detailed_lines` BillingChargeRealizationDetailedLine[]: The detailed (rated) lines produced by the realization run. Requires the `realization.detailed_lines` expand. - union: A detailed (child) line type of a charge realization run. This is distinct from an invoice's own detailed lines: it represents the rated/priced breakdown produced by the realization run itself, before that breakdown is (or is not yet) reflected on an invoice line. Credit-then-invoice runs include credit allocations in these lines, while credits-only runs keep the gross rated detail. - … - `discounts` object: Discounts applied to the usage-based charge. - `percentage` number: Percentage discount applied to the price (0–100). - `usage` string: 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. - `feature` union, required: The feature associated with the charge. - Feature: A capability or billable dimension offered by a provider. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date. - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity last update date. - `deleted_at` string, date-time: An ISO-8601 timestamp representation of entity deletion date. - `key` string, required: A key is a unique string that is used to identify a resource. - `meter` object: The meter that the feature is associated with and based on which usage is calculated. If not specified, the feature is static. - … - `unit_cost` union: 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. - … - FeatureReference: Feature reference. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `totals` object, required: Aggregated booked and realtime totals for the charge. - `booked` object, required: The amount of the charge already booked to the internal accounting system. - `amount` string, required: The total value of the resource before taxes, discounts and commitments. - `taxes_total` string, required: The total tax amount applied to the resource. - `taxes_inclusive_total` string, required: The total tax amount already included in the resource amount. - `taxes_exclusive_total` string, required: The total tax amount added on top of the resource amount. - `charges_total` string, required: The total amount contributed by additional charges. - `discounts_total` string, required: The total amount deducted through discounts. - `credits_total` string, required: The total amount deducted through credits before taxes are applied. - `total` string, required: The final total value of the resource after taxes, discounts and commitments. - `realtime` object: The realtime amount of the charge, i.e. the whole usage rated at the charge's price for its full service period, ignoring what has already been booked to a realization. This differs from the `usage` of a realization with type `outstanding`, which only covers the quantity not yet booked. Requires the `real_time_usage` expand. - `amount` string, required: The total value of the resource before taxes, discounts and commitments. - `taxes_total` string, required: The total tax amount applied to the resource. - `taxes_inclusive_total` string, required: The total tax amount already included in the resource amount. - `taxes_exclusive_total` string, required: The total tax amount added on top of the resource amount. - `charges_total` string, required: The total amount contributed by additional charges. - `discounts_total` string, required: The total amount deducted through discounts. - `credits_total` string, required: The total amount deducted through credits before taxes are applied. - `total` string, required: The final total value of the resource after taxes, discounts and commitments. - `usage` string: The metered usage quantity of the charge for its full service period. Requires the `real_time_usage` expand, since it is computed live from the metering store rather than stored on the charge. - `price` union, required: The price of the charge. `free` prices are rejected on create: a usage-based charge always carries a concrete price. - object: Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the object, billing units are the converted quantities (e.g. GB instead of bytes). - `type` 'unit', required: The type of the price. - `amount` string, required: The amount of the unit price. - object: 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 containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - `type` 'graduated', required: The type of the price. - `tiers` BillingPriceTier[], required: The tiers of the graduated price. At least one tier is required. - … - object: 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 containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - `type` 'volume', required: The type of the price. - `tiers` BillingPriceTier[], required: The tiers of the volume price. At least one tier is required. - … - `commitments` object: Spend commitments for the charge. - `minimum_amount` string: The customer is committed to spend at least the amount. - `maximum_amount` string: The customer is limited to spend at most the amount. - `unit_config` object: Unit conversion configuration for the charge. Synthesized on read for charges created from 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 only when the UnitConfig feature is enabled on the deployment; otherwise rejected. - `operation` 'divide' | 'multiply', required: The arithmetic operation to apply to the raw metered quantity. - `conversion_factor` string, required: The factor used in the conversion operation. - For `divide`: `converted = raw / conversionFactor`. - For `multiply`: `converted = raw × conversionFactor`. Must be a positive non-zero value. - `rounding` 'ceiling' | 'floor' | 'half_up' | 'none': The rounding mode applied to the converted quantity for invoicing. Defaults to none (no rounding). Entitlement checks always use the precise (unrounded) value. - `precision` integer: The number of decimal places to retain after rounding. Only meaningful when rounding is not "none". Defaults to 0 (round to whole numbers). - `display_unit` string: 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. - `system_intent` object: 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. - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: 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 "_". - `invoice_at` string, date-time, required: The timestamp when the charge is intended to be invoiced. - `service_period` object, required: The effective service period covered by the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `full_service_period` object, required: The full, unprorated service period of the charge. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `billing_period` object, required: The billing period the charge belongs to. - `from` string, date-time, required: The start of the period. The period is inclusive at the start. - `to` string, date-time, required: The end of the period. The period is exclusive at the end. - `discounts` object: Discounts applied to the usage-based charge. - `percentage` number: Percentage discount applied to the price (0–100). - `usage` string: 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. - `price` union, required: The price of the charge. `free` prices are rejected on create: a usage-based charge always carries a concrete price. - object: Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the object, billing units are the converted quantities (e.g. GB instead of bytes). - … - object: 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 containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - … - object: 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 containing resource, tier boundaries (up_to_amount) are expressed in converted billing units. - … - `commitments` object: Spend commitments for the charge. - `minimum_amount` string: The customer is committed to spend at least the amount. - `maximum_amount` string: The customer is limited to spend at most the amount. - `unit_config` object: Unit conversion configuration for the charge. Synthesized on read for charges created from 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 only when the UnitConfig feature is enabled on the deployment; otherwise rejected. - `operation` 'divide' | 'multiply', required: The arithmetic operation to apply to the raw metered quantity. - `conversion_factor` string, required: The factor used in the conversion operation. - For `divide`: `converted = raw / conversionFactor`. - For `multiply`: `converted = raw × conversionFactor`. Must be a positive non-zero value. - `rounding` 'ceiling' | 'floor' | 'half_up' | 'none': The rounding mode applied to the converted quantity for invoicing. Defaults to none (no rounding). Entitlement checks always use the precise (unrounded) value. - `precision` integer: The number of decimal places to retain after rounding. Only meaningful when rounding is not "none". Defaults to 0 (round to whole numbers). - `display_unit` string: 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. - `deleted_at` string, date-time: The timestamp when the system lifecycle controller intent was deleted. The effective charge can remain visible while a manual override is active. - `meta` PaginatedMeta, required: returns the pagination information - `page` PageMeta, required: Contains pagination query parameters and the total number of objects returned. - `number` number, required - `size` number, required - `total` number, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found ## Changes - **2026-10-15** `7aab863a6daa`: 1 breaking, 2 warning - added `#/components/schemas/InvalidParameterMinimumTime, #/components/schemas/InvalidParameterMaximumTime` to the `invalid_parameters/items/` response property `oneOf` list for the response status `400` - added the new `key_invalid` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400` - added the new `unique` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400` - **2026-10-07** `59663dd13a10`: 1 info - endpoint added - **2026-09-18** `f324fb7610e4`: 1 breaking - api path removed without deprecation - **2026-07-16** `a2e95e9f6c80`: 1 info - endpoint added [Operation history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v3/openmeter/customers/:customerId/charges/get.md) --- [API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/7aab863a6daa?raw)