# Search subscriptions

Returns a paginated list of subscriptions that match the specified filters, ordered newest first. Results are eventually consistent, so new and updated records are not immediately searchable. Do not use this endpoint for read-after-write flows. To get the current state of a subscription, use get subscription.

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

## Security:

  - `bearerAuth` (unknown)
    http bearer asec_xxx

## Request fields (application/json):

  - `filters` (object)
    Filters for subscriptions. All filters must match.

  - `filters.status` (object)
    Operator and value for subscription status filter.

  - `filters.status.operator` (string, required)
    Comparison operator. Use `IN` to match any of several statuses.
    Enum: "EQ", "IN"

  - `filters.status.value` (string, required)
    One subscription status for `EQ`, or a comma-separated list of statuses for `IN`. Allowed values - `CREATED`, `PENDING`, `TRIALING`, `ACTIVE`, `REDEMPTION`, `UNPAID`, `CANCELLED`, `EXPIRED`, `PAUSED`.
    Example: ACTIVE,TRIALING

  - `filters.customer_id` (object)
    Operator and value for customer identifier filter.

  - `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.customer_email` (object)
    Operator and value for customer email filter.

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

  - `filters.customer_email.value` (string, required)
    Email of the customer who owns the subscriptions.
    Example: jane.doe@example.com

  - `filters.product_id` (object)
    Operator and value for product identifier filter. Matches subscriptions with at least one line item for the product.

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

  - `filters.product_id.value` (string, required)
    Product identifier.
    Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

  - `filters.product_price_id` (object)
    Operator and value for product price identifier filter. Matches subscriptions with at least one line item for the price.

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

  - `filters.product_price_id.value` (string, required)
    Product price identifier.
    Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

  - `filters.created_at` (object)
    Operator and value for a date and time filter. `GTE` and `LTE` take a single date and time, `RANGE` takes an inclusive range.
    Example: {"operator":"RANGE","value":{"from":"2024-01-01T10:00:00.000000Z","to":"2024-01-31T10:00:00.000000Z"}}

  - `filters.created_at.operator` (string, required)
    Comparison operator. `GTE` matches values at or after the date and time, `LTE` at or before it.
    Enum: "GTE", "LTE"

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

  - `filters.created_at.operator` (string, required)
    Comparison operator. `RANGE` matches values within the inclusive range.
    Enum: "RANGE"

  - `filters.created_at.value` (object, required)
    Inclusive range of dates and times.

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

  - `filters.created_at.value.to` (string, required)
    Date and time value.
    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. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 200:

  - `200` (unknown)
    OK

## 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.
The list of enum values may be extended without notice.
    Enum: "CREATED", "PENDING", "TRIALING", "ACTIVE", "REDEMPTION", "UNPAID", "CANCELLED", "EXPIRED", "PAUSED"

  - `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.
The list of enum values may be extended without notice.
    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.
The list of enum values may be extended without notice.
    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.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.
The list of enum values may be extended without notice.
    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","calculation_type":"PERCENTAGE","calculation_value":25}]

  - `items.discounts.coupon_id` (string)
    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.discounts.calculation_type` (string)
    Discount calculation type.
The list of enum values may be extended without notice.
    Enum: "PERCENTAGE", "AMOUNT"

  - `items.discounts.calculation_value` (number)
    Discount calculation value. Percent for `PERCENTAGE`, minor units for `AMOUNT`.
    Example: 25

  - `items.metadata` (object)
    Set of key-value pairs attached to the subscription.
    Example: {"order_id":"12345"}

  - `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. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 400:

  - `400` (unknown)
    Bad request

## 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"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.

## Response 401:

  - `401` (unknown)
    Unauthenticated

## 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:

  - `403` (unknown)
    Unauthorized

## 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:

  - `429` (unknown)
    Too many requests

## 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