Get Subscriptions

Retrieve a list of subscriptions from your store.

Subscriptions are returned newest first. Each row carries the dates needed for common questions — "what's renewing next week?" / "which subscriptions are canceling right now?" — so you can answer them without fetching each subscription individually.

Request

GET /subscriptions

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number for pagination
per_page	integer	No	10	Items per page (min: 1, max: 100).
sort	string	No	-created_at	Sort order: created_at. Prefix with - for descending.
status	string	No	—	Filter by status. One of active, trialing, past_due, canceled, incomplete, incomplete_expired, unpaid.
customer	string	No	—	Filter by customer (account holder) UUID.
product	string	No	—	Filter by product UUID.
variant	string	No	—	Filter by variant (price) UUID.
created_from	string	No	—	Only subscriptions created on or after this date (inclusive), YYYY-MM-DD.
created_to	string	No	—	Only subscriptions created on or before this date (inclusive), YYYY-MM-DD.
canceled_from	string	No	—	Only subscriptions canceled on or after this date (inclusive), YYYY-MM-DD.
canceled_to	string	No	—	Only subscriptions canceled on or before this date (inclusive), YYYY-MM-DD.
current_period_end_from	string	No	—	Only subscriptions whose current period ends on or after this date (inclusive), YYYY-MM-DD. Useful for "what's renewing next week?".
current_period_end_to	string	No	—	Only subscriptions whose current period ends on or before this date (inclusive), YYYY-MM-DD.
query	string	No	—	Search term. Matched as an exact email when it is a valid email address, otherwise as a partial, case-insensitive match on the customer name, product name, or variant name.

Omitting a filter or passing it empty means "no filter on that field". Passing a non-empty but unparseable value — an unknown status, a malformed date, a non-UUID customer / product / variant, an out-of-range per_page, or an unknown sort field — returns a 400 (see Bad Request). The query search term is free-text and is always accepted.

The list returns every subscription, including any that a customer has hidden from their own self-service portal.

Ordering: Subscriptions default to created_at descending (newest first) unless sort is supplied.

Counting matches: every response includes the filtered total in pagination.total. To get only a count, request per_page=1 with your filters and read pagination.total.

Example Request — what's renewing next week?

curl -X GET "https://cart.easy.tools/api/v1/subscriptions?status=active&current_period_end_from=2026-06-01&current_period_end_to=2026-06-07" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Request — pending cancels (will end soon)

curl -X GET "https://cart.easy.tools/api/v1/subscriptions?status=active&canceled_from=2026-05-01" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a paginated list of subscriptions.

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440040",
      "remote_id": "sub_1QabcDEFghiJKLmn",
      "provider": "stripe",
      "status": "active",
      "variant_name": "Monthly Plan",
      "product_name": "Premium Course",
      "recurring_amount": 4900,
      "currency": "pln",
      "interval": "month",
      "interval_count": 1,
      "quantity": 1,
      "customer_email": "buyer@example.com",
      "current_period_end": "2026-06-20T14:02:00+00:00",
      "cancel_at": null,
      "canceled_at": null,
      "created_at": "2026-01-15T10:00:00+00:00"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440041",
      "remote_id": "sub_1QabcDEFghiJKLmo",
      "provider": "stripe",
      "status": "active",
      "variant_name": "Annual Plan",
      "product_name": "Premium Course",
      "recurring_amount": 49000,
      "currency": "pln",
      "interval": "year",
      "interval_count": 1,
      "quantity": 1,
      "customer_email": "another@example.com",
      "current_period_end": "2026-06-05T09:00:00+00:00",
      "cancel_at": "2026-06-05T09:00:00+00:00",
      "canceled_at": "2026-05-21T16:45:00+00:00",
      "created_at": "2025-06-05T09:00:00+00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 4,
    "per_page": 10,
    "total": 36
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the subscription (UUID)
remote_id	string	Yes	Provider's own subscription id (e.g. the Stripe subscription id)
provider	string	No	Payment provider — currently always stripe
status	string	Yes	Subscription status. See the status table for values.
variant_name	string	Yes	Related variant (price) name
product_name	string	Yes	Product name
recurring_amount	integer	Yes	Recurring charge in minor units (e.g. cents/grosze)
currency	string	Yes	Lowercase ISO currency code (e.g. "pln")
interval	string	Yes	Billing interval: day, week, month, or year
interval_count	integer	Yes	Number of intervals between renewals
quantity	integer	No	Quantity of the variant
customer_email	string	Yes	Customer email
current_period_end	string	Yes	End of the current paid period — the next renewal date when active (ISO 8601)
cancel_at	string	Yes	When the subscription will end (set when a cancellation is pending or scheduled)
canceled_at	string	Yes	When the cancellation was requested
created_at	string	No	When the subscription was created (ISO 8601)

Pagination Object

Field	Type	Description
current_page	integer	Current page number
total_pages	integer	Total number of pages
per_page	integer	Effective page size (echoes the per_page request parameter)
total	integer	Total number of subscriptions matching the applied filters, across all pages

Error Responses

Bad Request (400)

Returned when a filter has a non-empty but unparseable value. The message names the offending field and the value received.

{
  "message": "Invalid value for 'status': 'expred'"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}