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

# List subscriptions

`GET /v1/subscriptions`

List subscriptions for your organization, newest first. Filter by customer or status.

## Query parameters

- `limit` integer
- `offset` integer
- `customer_id` string
- `status` 'trialing' | 'active' | 'past_due' | 'unpaid' | 'canceled'

## Response `200`

A page of subscriptions

- SubscriptionListResponse
  - `items` SubscriptionResponse[]
    - `id` string — Unique identifier for the subscription.
    - `customer` Customer
      - `customer_id` string — Unique identifier for the customer, prefixed with `cust_`.
      - `email` string, nullable — The customer's email address.
      - `name` string, nullable — The customer's full name. `null` when not set.
      - `phone_number` string, nullable — The customer's phone number in E.164 format, e.g. `+2348012345678`.
      - `metadata` object — Your own key-value data attached to the customer.
      - `created_at` string, date-time, nullable — ISO 8601 timestamp when the customer was created.
      - `updated_at` string, date-time, nullable — ISO 8601 timestamp when the customer was last updated.
    - `payment_method_id` string, nullable — The saved payment method billed on each renewal. `null` until a payment method is attached.
    - `status` 'trialing' | 'active' | 'past_due' | 'unpaid' | 'canceled' | 'paused' — Status of the subscription. Set automatically by Bachs as payments succeed or fail. `trialing`: In a free trial. No payment has been collected yet. `trial_end` marks when billing begins. `active`: Active and paid. Bachs is billing this subscription automatically each cycle. `past_due`: A cycle payment failed. Bachs is retrying the payment while access continues. `unpaid`: Payment retries have been exhausted. Access should be restricted. `canceled`: Canceled and will not renew. This is a terminal state. `paused`: Temporarily suspended. Billing is halted until the subscription resumes.
    - `collection_method` string — How renewals are collected. `charge_automatically` bills the saved card each cycle.
    - `currency` string — The currency the subscription is billed in, as an ISO 4217 code. Subscriptions are USD only today.
    - `amount` string — Recurring amount as a decimal string
    - `billing_cycle` SubscriptionCadence
      - `interval` 'day' | 'week' | 'month' | 'year' — Unit of time for each billing cycle. `day`: billed daily. `week`: billed weekly. `month`: billed monthly. `year`: billed yearly.
      - `frequency` integer — Number of intervals per cycle. For example, `interval` `month` with `frequency` `3` bills every three months.
    - `quantity` integer — Total billable quantity across the subscription's line items.
    - `current_period_start` string, date-time — Start of the period currently being billed for, in UTC.
    - `current_period_end` string, date-time — End of the period currently being billed for, in UTC. The next charge lands at this time unless the subscription is canceled first.
    - `previously_billed_at` string, date-time, nullable — Start of the period that was last billed
    - `next_billed_at` string, date-time, nullable — Next scheduled charge date
    - `trial_end` string, date-time, nullable — When the free trial ends and billing begins, in UTC. `null` if the subscription is not trialing.
    - `cancel_at_period_end` boolean — When `true`, the subscription stays active until `current_period_end` and is not renewed. When `false`, it renews normally.
    - `canceled_at` string, date-time, nullable — When the subscription was canceled, in UTC. `null` if it has not been canceled.
    - `created_at` string, date-time — When the subscription was created, in UTC.
    - `product` SubscriptionCatalogProduct
      - `id` string — Unique identifier for the product.
      - `name` string — The product's name, shown to customers at checkout.
      - `description` string, nullable — The product's description. `null` if none was set.
      - `status` string — Whether the product is active or archived.
      - `billing_cycle` SubscriptionCadence
        - `interval` 'day' | 'week' | 'month' | 'year' — Unit of time for each billing cycle. `day`: billed daily. `week`: billed weekly. `month`: billed monthly. `year`: billed yearly.
        - `frequency` integer — Number of intervals per cycle. For example, `interval` `month` with `frequency` `3` bills every three months.
      - `trial_period` TrialPeriod — The length of the free trial before the first charge, expressed as a count of time units. For example, `{ "interval": "day", "frequency": 14 }` is a 14-day trial.
        - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time the trial is measured in: `day`, `week`, `month`, or `year`.
        - `frequency` integer, required — How many `interval` units the trial lasts. For example, `interval` `day` with `frequency` `14` is a 14-day trial.
      - `created_at` string, date-time — When the product was created, in UTC.
      - `updated_at` string, date-time — When the product was last updated, in UTC.
    - `items` SubscriptionItem[] — The line items that make up the subscription. Each item ties a product and its price to a billed quantity.
      - `id` string — Unique identifier for the line item.
      - `status` string — Lifecycle status of the item. Follows the parent subscription's status.
      - `quantity` integer — The billed quantity for this item.
      - `recurring` boolean — Whether this item recurs each billing cycle. Always `true` for subscription items.
      - `price_type` 'fixed' | 'free' | 'custom' — How this line item is priced. `fixed`: a set price per cycle, the same for every customer. `free`: no charge. `custom`: the customer chose the amount at checkout, within the product's bounds.
      - `unit_amount` string — Price for one unit of this item, as a decimal string in the item's currency.
      - `currency` string — The currency this item is billed in, as an ISO 4217 code.
      - `previously_billed_at` string, date-time, nullable — When this item was last billed, in UTC. `null` if it has not been billed yet.
      - `next_billed_at` string, date-time, nullable — When this item will next be billed, in UTC.
      - `price` SubscriptionItemPrice
        - `id` string — Unique identifier for the price.
        - `product_id` string — The product this price belongs to.
        - `price_type` 'fixed' | 'free' | 'custom' — How this line item is priced. `fixed`: a set price per cycle, the same for every customer. `free`: no charge. `custom`: the customer chose the amount at checkout, within the product's bounds.
        - `currency` string — The currency of this price, as an ISO 4217 code.
        - `unit_amount` string — Decimal string at the currency's precision
        - `billing_cycle` SubscriptionCadence
          - `interval` 'day' | 'week' | 'month' | 'year' — Unit of time for each billing cycle. `day`: billed daily. `week`: billed weekly. `month`: billed monthly. `year`: billed yearly.
          - `frequency` integer — Number of intervals per cycle. For example, `interval` `month` with `frequency` `3` bills every three months.
        - `trial_period` TrialPeriod — The length of the free trial before the first charge, expressed as a count of time units. For example, `{ "interval": "day", "frequency": 14 }` is a 14-day trial.
          - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time the trial is measured in: `day`, `week`, `month`, or `year`.
          - `frequency` integer, required — How many `interval` units the trial lasts. For example, `interval` `day` with `frequency` `14` is a 14-day trial.
        - `seat_tiers` object, nullable — Reserved for seat-based pricing. `null` for the standard pricing available today.
        - `is_archived` boolean — Whether the price has been archived. Archived prices keep billing existing subscribers but are not offered for new checkouts.
        - `created_at` string, date-time — When the price was created, in UTC.
        - `updated_at` string, date-time — When the price was last updated, in UTC.
      - `product` SubscriptionCatalogProduct
        - `id` string — Unique identifier for the product.
        - `name` string — The product's name, shown to customers at checkout.
        - `description` string, nullable — The product's description. `null` if none was set.
        - `status` string — Whether the product is active or archived.
        - `billing_cycle` SubscriptionCadence
          - `interval` 'day' | 'week' | 'month' | 'year' — Unit of time for each billing cycle. `day`: billed daily. `week`: billed weekly. `month`: billed monthly. `year`: billed yearly.
          - `frequency` integer — Number of intervals per cycle. For example, `interval` `month` with `frequency` `3` bills every three months.
        - `trial_period` TrialPeriod — The length of the free trial before the first charge, expressed as a count of time units. For example, `{ "interval": "day", "frequency": 14 }` is a 14-day trial.
          - `interval` 'day' | 'week' | 'month' | 'year', required — The unit of time the trial is measured in: `day`, `week`, `month`, or `year`.
          - `frequency` integer, required — How many `interval` units the trial lasts. For example, `interval` `day` with `frequency` `14` is a 14-day trial.
        - `created_at` string, date-time — When the product was created, in UTC.
        - `updated_at` string, date-time — When the product was last updated, in UTC.
      - `created_at` string, date-time — When the item was created, in UTC.
      - `updated_at` string, date-time — When the item was last updated, in UTC.
    - `metadata` object — Your own key-value data attached to the subscription at creation, returned unchanged.
  - `pagination` SubscriptionPagination
    - `next_cursor` string, nullable — Cursor for the next page, or `null` on the last page.
    - `prev_cursor` string, nullable — Cursor for the previous page, or `null` on the first page.
    - `has_more` boolean — Whether more results exist after this page.
    - `limit` integer — The page size that was applied.
    - `offset` integer — The offset that was applied.
    - `returned` integer — The number of items returned on this page.
    - `total` integer — Total number of subscriptions matching the query.

## Other responses

- `401` — Unauthorized - Invalid, missing, or expired API key. Verify your API key is correctly formatted and included in the Authorization header as `Bearer sk_sandbox_...` or `Bearer sk_live_...`. Check that your key hasn't been revoked.
- `403` — Forbidden - API key does not have permission for the requested resource. Verify you're using the correct organization's API key and that you're not trying to access another organization's data.
- `429` — Too Many Requests - Rate limit exceeded. Standard tier allows 100 requests per minute per API key. Wait a few seconds before retrying. Check X-RateLimit-Reset header for when the window resets.
- `500` — Internal Server Error - An unexpected error occurred while processing the request. Retry with exponential backoff. If the issue persists, contact support with your request context.

---

[API](https://skmtc.dev/bachs/apis/bachs-api.md) · [All operations](https://skmtc.dev/bachs/apis/bachs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bachs/bachs-api/revisions/f29efa8a22df/schema)