List Subscriptions

​

Returns a paginated list of subscriptions. By default, returns subscriptions that have not been canceled. Use the status parameter to filter by status, including CANCELED.

Query Parameters
  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Maximum number of subscriptions to return (1–100).

  • last_key
    Type: string

    Cursor for pagination in format: {ISO_timestamp}_{ULID}. Use the last_key value from a previous response to fetch the next page.

  • status
    Type: array string[]enum

    Filter by subscription status. Repeat the parameter to filter by multiple statuses.

    values
    • INCOMPLETE
    • INCOMPLETE_EXPIRED
    • TRIALING
    • ACTIVE
    • PAST_DUE
    • CANCELED
    • UNPAID
    • PAUSED
  • customer
    Type: array string[]

    Filter by customer ID(s). Repeat the parameter for multiple values.

  • start_date
    Type: stringFormat: date-time

    Return subscriptions created on or after this date (ISO 8601).

  • end_date
    Type: stringFormat: date-time

    Return subscriptions created on or before this date (ISO 8601).

  • search
    Type: string

    Full-text search across subscription fields.

  • expand
    enum
    const:  
    customer

    Expand related objects inline. Use customer to replace the customer ID with the full customer object.

    values
    • customer
Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/v1/subscriptions
curl 'https://api.paypercut.io/v1/subscriptions?limit=20&last_key=2026-01-07T08%3A16%3A15.154Z_01KEBRE9980EPAX58CMW5AEPSE&status=INCOMPLETE&customer=&start_date=&end_date=&search=&expand=customer' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "items": [
    {
      "id": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
      "customer": "01KJQ34MWYH0TES77RDXA8T8TT",
      "status": "ACTIVE",
      "start_date": "2026-01-01T00:00:00Z",
      "next_billing_date": "2026-02-01T00:00:00Z",
      "current_period_start": "2026-01-01T00:00:00Z",
      "current_period_end": "2026-02-01T00:00:00Z",
      "cancel_at_period_end": false,
      "cancel_at": null,
      "canceled_at": null,
      "collection_method": "charge_automatically",
      "currency": "USD",
      "default_payment_method": "pm_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
      "livemode": false,
      "items": [
        {
          "id": "si_01HD7M6DRKZ4Q4QEVWJB0RC1S6",
          "price": "01XXXXXXXXXXXXXXXXXXXXXXX",
          "product": "01XXXXXXXXXXXXXXXXXXXXXXX",
          "quantity": 1,
          "billing_interval": "monthly",
          "unit_amount": 2999,
          "currency": "USD",
          "recurring": {
            "interval": "monthly",
            "interval_count": 1,
            "usage_type": "licensed"
          },
          "created_at": "2026-01-01T00:00:00Z",
          "updated_at": "2026-01-01T00:00:00Z"
        }
      ],
      "metadata": {
        "plan": "premium"
      },
      "created": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "last_key": null
}

Paginated list of subscriptions.