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

# Get Subscriptions

`GET /v1/subscriptions`

List subscriptions belonging to the authenticated merchant division. Results are limited to only show subscriptions authorized by the X-API-Key and X-Publishable-Key.

## Query parameters

- `seller_id` string
- `product_ids` string
- `plan_ids` string
- `emails` string
- `statuses` SubscriptionV2Status[]
- `page` integer
- `page_size` integer

## Headers

- `X-Publishable-Key` string, required
- `X-Bolt-Connect-Seller-Id` string

## Response `200`

Success

- SubscriptionV2List — A paginated list of subscriptions.
  - `subscriptions` SubscriptionV2[], required
    - `id` string, required — The unique ID for a Bolt subscription.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `merchant_name` string, required — The name of the merchant this subscription belongs to.
    - `email` string, nullable, required — The email address of the shopper who owns this subscription. Nullable.
    - `status_details` SubscriptionV2StatusDetails, required — Details about the subscription's current status.
      - `type` 'active' | 'paused' | 'canceled' | 'payment_failed', required — The current status of the subscription.
      - `reason` string — Additional context for the current status, when available.
    - `payment_method` SubscriptionV2PaymentMethod — The card currently used to pay for this subscription.
      - `card_last_4` string, required — The last 4 digits of the card number.
      - `card_network` string, required — The card network (e.g. Visa, Mastercard).
    - `next_renewal_date` string, date-time, nullable — The date of the next scheduled renewal, if any.
    - `next_payment_retry_date` string, date-time, nullable — The date of the next scheduled payment retry, if the subscription currently has a failed payment.
    - `canceled_date` string, date-time, nullable
    - `paused_date` string, date-time, nullable
    - `plan` SubscriptionV2Plan, required — The billing plan the subscription is enrolled in.
      - `id` string, required — The unique ID for the subscription plan.
      - `name` string, required — The display name of the plan.
      - `sku` string, required — The merchant-defined SKU for the plan.
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `frequency` integer, required — The number of `frequency_unit`s between each billing cycle.
      - `frequency_unit` 'day' | 'week' | 'month' | 'year', required — The unit of time between billing cycles.
      - `product_id` string, required — The unique ID of the subscription product this plan belongs to.
      - `checkout_link` string — A hosted checkout link for this plan, when available.
      - `initial_period` SubscriptionV2InitialPeriod — An initial billing period, such as a trial or introductory offer, that differs from the plan's regular frequency.
        - `frequency` integer, required — The number of `frequency_unit`s in the initial period.
        - `frequency_unit` 'day' | 'week' | 'month' | 'year', required — The unit of time for the initial period's frequency.
    - `product_names` string[], required
    - `total_amount` Amounts, required — The amount. **Nullable** for Transactions Details.
      - `amount` integer, required — The amount in cents. **Nullable** for Transactions Details.
      - `currency` string, required — The 3-digit ISO code for the currency. **Nullable** for Transactions Details.
      - `currency_symbol` string, required — The currency symbol used for the amount. **Nullable** for Transactions Details.
    - `metadata` object, required — Merchant-defined custom metadata.
  - `pagination` SubscriptionV2Pagination, required — Pagination details for a list response.
    - `page_size` integer, required
    - `total_count` integer, required

## Other responses

- `400` — BAD REQUEST. Request is malformed or invalid values are detected.
- `401` — UNAUTHORIZED. Missing or invalid X-API-Key or X-Publishable-Key.

## Changes

- **2026-07-31** `1f62c40558c6` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/bolt/apis/bolt-api-reference/changes/v1/subscriptions/get.md)

---

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