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

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, or a non-UUID customer / product / variant — returns a 400 (see Bad Request).

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

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

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 (the subscription's owner.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)

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