# List subscriptions

Returns a paginated list of <a href="https://docs.solidgate.com/billing/subscriptions/subscriptions-2.0/" target="_blank">subscriptions</a>.

Endpoint: POST /subscriptions/list
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `filters` (object)
    Filters for subscriptions.

  - `filters.customer_id` (object)
    Filter by customer identifier.

  - `filters.customer_id.operator` (string, required)
    Comparison operator.
    Enum: "EQ"

  - `filters.customer_id.value` (string, required)
    Identifier of the customer who owns the subscriptions.
    Example: cust_01KMG2ABYPF6XS5DMJQ817C429

  - `filters.created_at` (object)
    Filter by the date and time when the subscription was created.

  - `filters.created_at.operator` (string, required)
    Comparison operator.
    Enum: "GTE", "LTE"

  - `filters.created_at.value` (string, required)
    Date and time value to filter by.
    Example: 2024-01-01T10:00:00.000000Z

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 200 fields (application/json):

  - `items` (array)
    List of subscriptions for the current page.

  - `items.id` (string, required)
    Unique subscription identifier.
    Example: subs_01HYDYBRKN16B8X3BR9WP78ZR7

  - `items.status` (string, required)
    Current subscription status.
    Enum: "CREATED", "PENDING", "TRIALING", "ACTIVE", "REDEMPTION", "UNPAID", "CANCELLED", "EXPIRED"

  - `items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: USD

  - `items.line_items` (array, required)
    Line items applied to the subscription.
    Example: [{"id":"slit_01KPWT0K1PQWEYYRT7J1H3NC85","billing_type":"RECURRING","currency":"USD","amount":1000,"quantity":1,"started_at":"2025-12-24T11:45:00.000000Z","period":{"start_at":"2025-12-24T11:45:00.000…

  - `items.line_items.id` (string, required)
    Unique line item identifier.
    Example: slit_01KPWT0K1PQWEYYRT7J1H3NC85

  - `items.line_items.billing_type` (string, required)
    Billing type of the line item.
    Enum: "RECURRING", "ONE_TIME"

  - `items.line_items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: USD

  - `items.line_items.amount` (integer, required)
    Line item amount in minor units.
    Example: 1000

  - `items.line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `items.line_items.started_at` (string)
    Date and time when the line item started.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.line_items.period` (object)
    Billing period interval for the line item.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `items.line_items.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.line_items.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: 2026-01-24T11:45:00.000000Z

  - `items.line_items.billing_period_config` (object)
    Recurring calendar interval at which the line item is billed.
    Example: {"value":1,"unit":"MONTH"}

  - `items.line_items.billing_period_config.value` (integer, required)
    Number of units in the period.
    Example: 1

  - `items.line_items.billing_period_config.unit` (string, required)
    Time unit for the period.
    Enum: "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

  - `items.line_items.product_info` (object, required)
    Snapshot of product details for the line item.

  - `items.line_items.product_info.name` (string, required)
    Product name.
    Example: Great product

  - `items.line_items.product_info.description` (string)
    Product description.
    Example: Annual subscription for a great product

  - `items.line_items.created_at` (string, required)
    Date and time when the line item was created.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.line_items.updated_at` (string, required)
    Date and time when the line item was updated.
    Example: 2025-12-24T11:47:00.000000Z

  - `items.line_items.product_id` (string, required)
    Identifier of the associated product.
    Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

  - `items.line_items.product_price_id` (string, required)
    Identifier of the associated price.
    Example: e6f26db1-f633-4723-ab08-50ddee7bc648

  - `items.created_at` (string, required)
    Date and time when the subscription was created.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.updated_at` (string, required)
    Date and time when the subscription was updated.
    Example: 2025-12-24T11:47:00.000000Z

  - `items.started_at` (string)
    Date and time when the subscription started.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.start_scheduled_at` (string)
    Date and time when the subscription is scheduled to start. Present only while the subscription is in the `CREATED` status and matches the `starts_at` value from the create request.
    Example: 2026-01-24T11:45:00.000000Z

  - `items.next_billing_at` (string)
    Date and time when the next billing occurs.
    Example: 2026-01-24T11:45:00.000000Z

  - `items.anchor_at` (string)
    Date and time used to anchor billing cycles.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.trial_info` (object)
    Trial details for the subscription.

  - `items.trial_info.type` (string, required)
    Trial type.
    Enum: "FREE", "PAID"

  - `items.trial_info.period` (object)
    Trial period interval.
    Example: {"start_at":"2025-12-24T11:45:00.000000Z","end_at":"2026-01-24T11:45:00.000000Z"}

  - `items.trial_info.period.start_at` (string, required)
    Date and time when the interval starts.
    Example: 2025-12-24T11:45:00.000000Z

  - `items.trial_info.period.end_at` (string, required)
    Date and time when the interval ends. Not present when the interval is open-ended and continues indefinitely.
    Example: 2026-01-24T11:45:00.000000Z

  - `items.trial_info.amount` (integer, required)
    Trial amount in minor units.
    Example: 0

  - `items.trial_info.period_config` (object)
    Period expressed as a numeric value and a time unit.
    Example: {"value":1,"unit":"MONTH"}

  - `items.trial_info.period_config.value` (integer, required)
    Number of units in the period.
    Example: 1

  - `items.trial_info.period_config.unit` (string, required)
    Time unit for the period.
    Enum: "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

  - `items.cancellation_info` (object)
    Cancellation details for the subscription. Present when the subscription is scheduled for cancellation or already cancelled.

  - `items.cancellation_info.cancel_at` (string, required)
    Date and time when the subscription is scheduled to be cancelled or was cancelled.
    Example: 2026-03-24T11:45:00.000000Z

  - `items.cancellation_info.requested_at` (string, required)
    Date and time when cancellation was requested.
    Example: 2026-02-24T11:45:00.000000Z

  - `items.cancellation_info.reason` (string, required)
    Reason for the cancellation.
    Enum: "DUNNING_EXHAUSTED", "CANCELLATION_REQUESTED", "FRAUD_ALERT_RECEIVED", "DISPUTE_RECEIVED"

  - `items.cancellation_info.comment` (string)
    Additional cancellation comment.
    Example: Customer requested cancellation

  - `items.discounts` (array)
    Discounts applied to the subscription.
    Example: [{"coupon_id":"0291b87b-deac-4eb4-8732-2a70d247a171","coupon_code":"WINTER25"}]

  - `items.discounts.coupon_id` (string, required)
    Unique identifier of the associated coupon.
    Example: 0291b87b-deac-4eb4-8732-2a70d247a171

  - `items.discounts.coupon_code` (string)
    Code of the associated coupon.
    Example: WINTER25

  - `items.description` (string)
    Additional description for the subscription.
    Example: Premium plan subscription

  - `items.merchant_reference` (string)
    Merchant-defined reference for the subscription.
    Example: premium-plan-subs-482

  - `items.customer_id` (string, required)
    Unique customer identifier.
    Example: cust_01KMG2ABYPF6XS5DMJQ817C429

  - `items.payment_instrument_id` (string)
    Identifier of the payment instrument used for billing.
    Example: pi_01J1Z2X3Y4W5V6U7T8S9R0

  - `items.latest_invoice_id` (string)
    Identifier of the most recent invoice.
    Example: inv_01KPWT0K1PQWEYYRT7J1H3NC85

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. It is empty on the last page.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: One or more fields failed validation due to constraints

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: Credentials are invalid or missing

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: Permission denied

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: Rate limit exhausted

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: 2024-12-31T23:59:59.000000Z