--- title: "List customer charges" method: GET path: "/v3/openmeter/customers/{customerId}/charges" tags: ["OpenMeter Customers"] --- # List customer charges `GET /v3/openmeter/customers/{customerId}/charges` **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` ListChargesParamsFilter — 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 - `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` object, required — The customer owning the charge. - `id` string, required — The ID of the customer. - `lifecycle_controller` 'system' | 'manual', required — Indicates whether the charge lifecycle is controlled by OpenMeter or manually overridden by the API user. - `subscription` object — The subscription that originated the charge, when the charge was created from a subscription item. - `id` string, required — The ID of the subscription. - `phase` object, required — The phase of the subscription. - `id` string, required — The ID of the phase. - `item` object, required — The item of the phase. - … - `currency` string, required — The currency of the charge. - `status` 'created' | 'active' | 'final' | 'deleted', required — The lifecycle status of the charge. - `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). - `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_key` string — The feature associated with the charge, when applicable. - `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 — Numeric represents an arbitrary precision number. - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `price` union, required — The price of the charge. - object — Free price. - `type` 'free', required — The type of the price. - object — Flat price. - `type` 'flat', required — The type of the price. - `amount` string, required — The amount of the flat price. - object — Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the rate card, billing units are the converted quantities (e.g. GB instead of bytes). - `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 rate card, 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 rate card, 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. - … - 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` object, required — The customer owning the charge. - `id` string, required — The ID of the customer. - `lifecycle_controller` 'system' | 'manual', required — Indicates whether the charge lifecycle is controlled by OpenMeter or manually overridden by the API user. - `subscription` object — The subscription that originated the charge, when the charge was created from a subscription item. - `id` string, required — The ID of the subscription. - `phase` object, required — The phase of the subscription. - `id` string, required — The ID of the phase. - `item` object, required — The item of the phase. - … - `currency` string, required — The currency of the charge. - `status` 'created' | 'active' | 'final' | 'deleted', required — The lifecycle status of the charge. - `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). - `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_key` string, required — The feature associated with the charge. - `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. Requires the `realtime_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. - `price` union, required — The price of the charge. - object — Free price. - `type` 'free', required — The type of the price. - object — Flat price. - `type` 'flat', required — The type of the price. - `amount` string, required — The amount of the flat price. - object — Unit price. Charges a fixed rate per billing unit. When UnitConfig is present on the rate card, billing units are the converted quantities (e.g. GB instead of bytes). - `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 rate card, 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 rate card, 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. - … - `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 --- [API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/revisions/0261aef4b1e2/schema)