--- title: "List customer charges" method: GET path: "/openmeter/customers/{customerId}/charges" tags: ["OpenMeter Customers"] --- # List customer charges `GET /openmeter/customers/{customerId}/charges` 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` union — Filters on the given string field value by exact match. All properties are optional; provide exactly one to specify the comparison. - string - object - `eq` string — Value strictly equals the given string value. - `oeq` string — Returns entities that exact match any of the comma-delimited phrases in the filter string. - `neq` string — Value does not equal the given string value. - `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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `type` 'flat_fee', required — The type of the charge. - `customer` BillingCustomerReference, required — Customer reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `lifecycle_controller` 'system' | 'manual', required — Identifies whether a resource lifecycle is controlled by OpenMeter or manually overridden by the API user. Values: - `system`: The resource lifecycle is controlled by OpenMeter. - `manual`: The resource lifecycle was manually overridden by the API user. - `subscription` BillingSubscriptionReference — Subscription reference represents a reference to the specific subscription item this entity represents. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `phase` object, required — The phase of the subscription. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `item` object, required — The item of the phase. - … - `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. - `status` 'created' | 'active' | 'final' | 'deleted', required — Lifecycle status of a charge. Values: - `created`: The charge has been created but is not active yet. - `active`: The charge is active. - `final`: The charge is fully finalized and no further changes are expected. - `deleted`: The charge has been deleted. - `invoice_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `full_service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `billing_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `advance_after` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `unique_reference_id` string — Unique reference ID of the charge. - `settlement_mode` 'credit_then_invoice' | 'credit_only', required — 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. - `tax_config` BillingTaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` BillingTaxConfigStripe — The tax config for Stripe. - `code` string, required — Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` BillingTaxConfigExternalInvoicing — External invoicing tax config. - `code` string, required — The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string — ULID (Universally Unique Lexicographically Sortable Identifier). - `tax_code` TaxCodeReference — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `payment_term` 'in_advance' | 'in_arrears', required — The payment term of a flat price. - `discounts` BillingChargeFlatFeeDiscounts — Discounts applicable to flat fee charges. This is the same as `ProductCatalog.Discounts` but without the `usage` field, which is not applicable to flat fee charges. - `percentage` number — Percentage discount applied to the price (0–100). - `feature_key` string — The feature associated with the charge, when applicable. - `feature_id` string — The feature ID associated with the charge. - `proration_configuration` BillingRateCardProrationConfiguration, required — The proration configuration of the rate card. - `mode` 'no_proration' | 'prorate_prices', required — The proration mode of the rate card. Values: - `no_proration`: No proration. - `prorate_prices`: Prorate the price based on the time remaining in the billing period. - `amount_after_proration` CurrencyAmount, required — Monetary amount in a specific currency. - `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 — Price. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - 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. - … - `system_intent` BillingChargeFlatFeeSystemIntent — Flat fee intent fields from the system lifecycle controller shadowed by a manual override. - `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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `full_service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `billing_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `payment_term` 'in_advance' | 'in_arrears', required — The payment term of a flat price. - `discounts` BillingChargeFlatFeeDiscounts — Discounts applicable to flat fee charges. This is the same as `ProductCatalog.Discounts` but without the `usage` field, which is not applicable to flat fee charges. - `percentage` number — Percentage discount applied to the price (0–100). - `proration_configuration` BillingRateCardProrationConfiguration, required — The proration configuration of the rate card. - `mode` 'no_proration' | 'prorate_prices', required — The proration mode of the rate card. Values: - `no_proration`: No proration. - `prorate_prices`: Prorate the price based on the time remaining in the billing period. - `amount_before_proration` CurrencyAmount, required — Monetary amount in a specific currency. - `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. - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - 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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `type` 'usage_based', required — The type of the charge. - `customer` BillingCustomerReference, required — Customer reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `lifecycle_controller` 'system' | 'manual', required — Identifies whether a resource lifecycle is controlled by OpenMeter or manually overridden by the API user. Values: - `system`: The resource lifecycle is controlled by OpenMeter. - `manual`: The resource lifecycle was manually overridden by the API user. - `subscription` BillingSubscriptionReference — Subscription reference represents a reference to the specific subscription item this entity represents. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `phase` object, required — The phase of the subscription. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `item` object, required — The item of the phase. - … - `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. - `status` 'created' | 'active' | 'final' | 'deleted', required — Lifecycle status of a charge. Values: - `created`: The charge has been created but is not active yet. - `active`: The charge is active. - `final`: The charge is fully finalized and no further changes are expected. - `deleted`: The charge has been deleted. - `invoice_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `full_service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `billing_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `advance_after` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `unique_reference_id` string — Unique reference ID of the charge. - `settlement_mode` 'credit_then_invoice' | 'credit_only', required — 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. - `tax_config` BillingTaxConfig — Set of provider specific tax configs. - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `stripe` BillingTaxConfigStripe — The tax config for Stripe. - `code` string, required — Product [tax code](https://docs.stripe.com/tax/tax-codes). - `external_invoicing` BillingTaxConfigExternalInvoicing — External invoicing tax config. - `code` string, required — The tax code should be interpreted by the external invoicing provider. - `tax_code_id` string — ULID (Universally Unique Lexicographically Sortable Identifier). - `tax_code` TaxCodeReference — TaxCode reference. - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier). - `discounts` BillingRateCardDiscounts — Discount configuration for a rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Numeric represents an arbitrary precision number. - `feature_key` string, required — The feature associated with the charge. - `feature_id` string, required — The feature ID associated with the charge. - `totals` BillingChargeTotals, required — The totals of a change. RealTime is only expanded when the `real_time_usage` expand is used. - `booked` BillingTotals, required — Totals contains the summaries of all calculations for a billing resource. - `amount` string, required — Numeric represents an arbitrary precision number. - `taxes_total` string, required — Numeric represents an arbitrary precision number. - `taxes_inclusive_total` string, required — Numeric represents an arbitrary precision number. - `taxes_exclusive_total` string, required — Numeric represents an arbitrary precision number. - `charges_total` string, required — Numeric represents an arbitrary precision number. - `discounts_total` string, required — Numeric represents an arbitrary precision number. - `credits_total` string, required — Numeric represents an arbitrary precision number. - `total` string, required — Numeric represents an arbitrary precision number. - `realtime` BillingTotals — Totals contains the summaries of all calculations for a billing resource. - `amount` string, required — Numeric represents an arbitrary precision number. - `taxes_total` string, required — Numeric represents an arbitrary precision number. - `taxes_inclusive_total` string, required — Numeric represents an arbitrary precision number. - `taxes_exclusive_total` string, required — Numeric represents an arbitrary precision number. - `charges_total` string, required — Numeric represents an arbitrary precision number. - `discounts_total` string, required — Numeric represents an arbitrary precision number. - `credits_total` string, required — Numeric represents an arbitrary precision number. - `total` string, required — Numeric represents an arbitrary precision number. - `price` union, required — Price. - 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 — Numeric represents an arbitrary precision number. - 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 — Numeric represents an arbitrary precision number. - 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. - … - `system_intent` BillingChargeUsageBasedSystemIntent — Usage-based intent fields from the system lifecycle controller shadowed by a manual override. - `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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `full_service_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `billing_period` ClosedPeriod, required — A period with defined start and end dates. The period is always inclusive at the start and exclusive at the end. - `from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `to` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `discounts` BillingRateCardDiscounts — Discount configuration for a rate card. - `percentage` number — Percentage discount applied to the price (0–100). - `usage` string — Numeric represents an arbitrary precision number. - `price` union, required — Price. - object — Free price. - … - object — 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). - … - 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. - … - 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. - … - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `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/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/eabb28bd0633/schema)