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.

You can also review and manage subscriptions in the Merchant Dashboard.

Related guides: Products and Prices and Subscriptions

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

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

  • last_key
    Type: string

    Opaque cursor for pagination. Use the last_key value from the previous response to retrieve 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: string Format: date-time

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

  • end_date
    Type: string Format: 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
  • application/json
Request Example for get/v1/subscriptions
curl https://api.paypercut.io/v1/subscriptions \
  --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": "01XXXXXXXXXXXXXXXXXXXXXXX",
      "livemode": false,
      "items": [
        {
          "id": "01XXXXXXXXXXXXXXXXXXXXXXX",
          "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"
      },
      "payment_behavior": "default_incomplete",
      "created": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "last_key": null
}

Paginated list of subscriptions.