Get Subscription

Retrieve a specific subscription from your store.

By default the response contains the subscription's base fields plus is_cancelable. Use the include query parameter to expand related sections — the customer, the current variant, the product, the originating order, the renewal history, and a preview of the next invoice — in the same call.

Request

GET /subscriptions/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Subscription UUID

Query Parameters

Parameter	Type	Required	Description
include	string	No	Comma-separated list of sections to expand. Allowed: customer, variant, product, order, renewals, upcoming_invoice. Unknown values are ignored.

note

A section that is not requested is returned as null — the key is always present, so the response shape stays stable. Requesting include=customer therefore leaves variant, product, order, renewals, and upcoming_invoice as null.

upcoming_invoice triggers a remote call

The upcoming_invoice section calls the payment provider to preview the next bill. Request it only when you actually need the preview. If the provider call fails or times out, the section is returned as null and the rest of the response is unaffected.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/subscriptions/550e8400-e29b-41d4-a716-446655440040?include=customer,variant,product,order,renewals" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a single subscription. The example below requests every section except upcoming_invoice.

{
  "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_start": "2026-05-20T14:02:00+00:00",
  "current_period_end": "2026-06-20T14:02:00+00:00",
  "trial_end": null,
  "cancel_at": null,
  "canceled_at": null,
  "active_until": null,
  "active_cycles": null,
  "cancel_early": false,
  "keep_access_after_expiring": false,
  "is_delegated": false,
  "is_cancelable": true,
  "created_at": "2026-01-15T10:00:00+00:00",
  "customer": {
    "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "email": "buyer@example.com",
    "name": "Jane Doe"
  },
  "variant": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "recurring",
    "recurring_options": {
      "interval": "month",
      "interval_count": 1
    },
    "name": "Monthly Plan",
    "amount": 4900,
    "currency": "pln",
    "checkout_url": "https://example.cart.easy.tools/premium-course?price=monthly",
    "custom_id": null,
    "is_hidden": false,
    "trial_period_days": null,
    "active_cycles": null,
    "cancel_early": false,
    "keep_access_after_expiring": false,
    "allow_multiple_subscriptions": false,
    "active_days": null,
    "quantity": null,
    "has_quantity": false,
    "old_price": null,
    "active_from": null,
    "active_until": null,
    "show_active_until_counter": null,
    "tax_behavior": "exclusive",
    "refund_days": 14,
    "redirect_url": null,
    "redirect_time": null,
    "file": null,
    "files": [],
    "invoice_remarks": null
  },
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Premium Course",
    "checkout_url": "https://example.cart.easy.tools/premium-course"
  },
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440050",
    "status": "completed",
    "created_at": "2026-01-15T10:00:00+00:00"
  },
  "renewals": [
    {
      "renewed_at": "2026-04-20T14:02:00+00:00",
      "stripe_invoice_id": "in_1Q3..."
    },
    {
      "renewed_at": "2026-03-20T14:02:00+00:00",
      "stripe_invoice_id": "in_1Q2..."
    }
  ],
  "upcoming_invoice": null
}

A lean read (no include) returns the base fields with every section set to null:

{
  "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_start": "2026-05-20T14:02:00+00:00",
  "current_period_end": "2026-06-20T14:02:00+00:00",
  "trial_end": null,
  "cancel_at": null,
  "canceled_at": null,
  "active_until": null,
  "active_cycles": null,
  "cancel_early": false,
  "keep_access_after_expiring": false,
  "is_delegated": false,
  "is_cancelable": true,
  "created_at": "2026-01-15T10:00:00+00:00",
  "customer": null,
  "variant": null,
  "product": null,
  "order": null,
  "renewals": null,
  "upcoming_invoice": null
}

An upcoming_invoice request returns a preview of the next bill:

{
  "upcoming_invoice": {
    "amount_due": 4900,
    "currency": "pln",
    "period_start": "2026-06-20T14:02:00+00:00",
    "period_end": "2026-07-20T14:02:00+00:00",
    "next_payment_attempt": "2026-06-20T14:02:00+00:00"
  }
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Subscription identifier (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
currency	string	Yes	Lowercase ISO currency code
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_start	string	Yes	Start of the current paid period (ISO 8601)
current_period_end	string	Yes	End of the current paid period (ISO 8601)
trial_end	string	Yes	End of the trial period; null if the subscription had no trial
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
active_until	string	Yes	When access actually lapses (set when access lingers past cancel_at)
active_cycles	integer	Yes	Number of billing cycles before the subscription auto-cancels ("installments" mode). Null = open-ended.
cancel_early	boolean	No	Whether the customer is allowed to cancel before reaching active_cycles (only meaningful when it is set)
keep_access_after_expiring	boolean	No	Whether the customer keeps access after the subscription expires
is_delegated	boolean	No	Whether the subscription was granted on behalf of the customer (no checkout flow)
is_cancelable	boolean	No	Whether POST /subscriptions/{id}/cancel would succeed for this subscription right now
created_at	string	No	When the subscription was created (ISO 8601)
customer	object	Yes	The customer. null unless customer is included.
variant	object	Yes	The current variant (same shape that GET /product-variants/{id} returns). null unless variant is included.
product	object	Yes	Lean product projection. null unless product is included.
order	object	Yes	Lean originating-order projection. null unless order is included.
renewals	array	Yes	Recorded renewals. null unless renewals is included.
upcoming_invoice	object	Yes	Preview of the next invoice (calls the payment provider). null unless upcoming_invoice is included or the provider failed.

customer

Resolved from the subscription's owner account. id is null when the linked account is missing (and email/name will be too).

Field	Type	Nullable	Description
id	string	Yes	Customer identifier (UUID)
email	string	Yes	Customer email
name	string	Yes	Customer full name

product

Field	Type	Nullable	Description
id	string	No	Product identifier (UUID)
name	string	Yes	Product name
checkout_url	string	Yes	Product checkout URL

order

Field	Type	Nullable	Description
id	string	No	Order identifier (UUID)
status	string	Yes	Order status: created, awaiting_payment, processing, completed, canceled, or refunded.
created_at	string	No	When the order was created (ISO 8601)

renewals[]

Field	Type	Nullable	Description
renewed_at	string	No	When this renewal was recorded (ISO 8601)
stripe_invoice_id	string	Yes	Stripe invoice id of the renewal (when paid via Stripe)

upcoming_invoice

Field	Type	Nullable	Description
amount_due	integer	No	Amount the next invoice will charge, in minor units
currency	string	No	Lowercase ISO currency code
period_start	string	Yes	Start of the period the invoice covers (ISO 8601)
period_end	string	Yes	End of the period the invoice covers (ISO 8601)
next_payment_attempt	string	Yes	When the payment provider will next attempt to charge the invoice (ISO 8601)

Error Responses

Bad Request (400)

{
  "message": "Invalid subscription ID"
}

Subscription Not Found (404)

{
  "message": "Subscription with ID 550e8400-e29b-41d4-a716-446655440040 not found"
}

Unauthorized (401)

{
  "message": "Unauthenticated."
}