---
title: "List subscriptions"
method: GET
path: "/openmeter/subscriptions"
tags: ["OpenMeter Subscriptions"]
---

# List subscriptions

`GET /openmeter/subscriptions`

## 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` ListSubscriptionsParamsFilter — Filter options for listing subscriptions.
  - `id` union — Filters on the given ULID field value by exact match. All properties are optional; provide exactly one to specify the comparison.
    - string — ULID (Universally Unique Lexicographically Sortable Identifier).
    - object
      - `eq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `oeq` string — Returns entities that exact match any of the comma-delimited ULIDs in the filter string.
      - `neq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `customer_id` union — Filters on the given ULID field value by exact match. All properties are optional; provide exactly one to specify the comparison.
    - string — ULID (Universally Unique Lexicographically Sortable Identifier).
    - object
      - `eq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `oeq` string — Returns entities that exact match any of the comma-delimited ULIDs in the filter string.
      - `neq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `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.
  - `plan_id` union — Filters on the given ULID field value by exact match. All properties are optional; provide exactly one to specify the comparison.
    - string — ULID (Universally Unique Lexicographically Sortable Identifier).
    - object
      - `eq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `oeq` string — Returns entities that exact match any of the comma-delimited ULIDs in the filter string.
      - `neq` string — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `plan_key` 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.

## Response `200`

Page paginated response.

- SubscriptionPagePaginatedResponse — Page paginated response.
  - `data` BillingSubscription[], required
    - `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 — [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.
    - `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 — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `active_to` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `customer_id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
    - `plan_id` string — ULID (Universally Unique Lexicographically Sortable Identifier).
    - `plan` BillingSubscriptionPlanReference — A reference to the plan a subscription was created from, pinned to an exact revision.
      - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `key` string, required — A key is a unique string that is used to identify a resource.
      - `version` integer, required — The plan version.
    - `invoice_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.
    - `cost_basis_mode` 'dynamic' | 'pinned', required — Controls how custom-currency cost bases are selected for the subscription.
    - `cost_basis_pins` BillingSubscriptionCostBasisPin[], required — Cost bases pinned to custom-currency pairs for this subscription.
      - `custom_currency_id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `invoice_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.
      - `cost_basis_id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
    - `billing_cadence` string, ISO8601, required — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string.
    - `pro_rating_config` BillingSubscriptionProRatingConfig — The pro-rating configuration of a subscription.
      - `enabled` boolean, required — Whether pro-rating is enabled.
      - `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.
    - `billing_anchor` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `status` 'active' | 'inactive' | 'canceled' | 'scheduled', required — Subscription status.
    - `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` ClosedPeriod — 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.
    - `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.
      - `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.
      - `key` string, required — A key is a unique string that is used to identify a resource.
      - `active_from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
      - `active_to` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
      - `items` BillingSubscriptionItem[], required — The rate cards in effect for this phase, resolved to the version active at the queried time (the currently active version for the current phase, the first version for future phases, and the last version for past phases).
        - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
        - `active_from` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
        - `active_to` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
        - `rate_card` BillingRateCard, required — A rate card defines the pricing and entitlement of a feature or service.
          - `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 "_".
          - `key` string, required — A key is a unique string that is used to identify a resource.
          - `feature` FeatureReference — Feature reference.
            - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
          - `currency` union — Fiat or custom currency code.
            - 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.
          - `billing_cadence` string, ISO8601 — [ISO 8601 Duration](https://docs.digi.com/resources/documentation/digidocs/90001488-13/reference/r_iso_8601_duration_format.htm) string.
          - `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.
              - …
          - `unit_config` BillingUnitConfig — Unit conversion configuration. Transforms raw metered quantities into billing-ready units before pricing and entitlement evaluation. Applied at the rate card level so the same feature can be billed in different units across plans. Examples: - Meter bytes, bill GB: operation=divide, conversionFactor=1e9, rounding=ceiling, displayUnit="GB" - Meter seconds, bill hours: operation=divide, conversionFactor=3600, rounding=ceiling, displayUnit="hours" - Cost + 20% margin: operation=multiply, conversionFactor=1.2 - Bill per million tokens: operation=divide, conversionFactor=1e6, rounding=ceiling, displayUnit="M" v1 equivalents: - DynamicPrice(multiplier): operation=multiply, conversionFactor=multiplier + UnitPrice(amount=1) - PackagePrice(amount, quantityPerPkg): operation=divide, conversionFactor=quantityPerPkg, rounding=ceiling + UnitPrice(amount)
            - `operation` 'divide' | 'multiply', required — The arithmetic operation used to convert raw metered units into billing units. - `divide`: Divide the metered quantity by the conversion factor (e.g., bytes ÷ 1e9 = GB). - `multiply`: Multiply the metered quantity by the conversion factor (e.g., cost × 1.2 = cost + 20% margin).
            - `conversion_factor` string, required — Numeric represents an arbitrary precision number.
            - `rounding` 'ceiling' | 'floor' | 'half_up' | 'none' — The rounding mode applied to the converted quantity for invoicing. Rounding is applied only to the invoiced quantity. Entitlement balance checks use the precise decimal value after conversion. - `ceiling`: Round up to the next integer (typical for package-style billing). - `floor`: Round down to the previous integer. - `half_up`: Round to the nearest integer, with 0.5 rounding up. - `none`: No rounding; the converted value is used as-is.
            - `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.
          - `payment_term` 'in_advance' | 'in_arrears' — The payment term of a flat price.
          - `commitments` BillingSpendCommitments — Spend commitments for a rate card. The customer is committed to spend at least the minimum amount and at most the maximum amount.
            - `minimum_amount` string — Numeric represents an arbitrary precision number.
            - `maximum_amount` string — Numeric represents an arbitrary precision number.
          - `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.
          - `tax_config` BillingRateCardTaxConfig — The tax config of the rate card.
            - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price.
            - `code` TaxCodeReference, required — TaxCode reference.
              - …
          - `entitlement` union — Entitlement template configured on a rate card. The feature is taken from the rate card itself, so it is omitted here.
            - object — The entitlement template of a metered entitlement.
              - …
            - object — The entitlement template of a static entitlement.
              - …
            - object — The entitlement template of a boolean entitlement.
              - …
  - `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/327f2080730f/schema)