This endpoint is typically the first call in any billing flow — fetch your subscription list to get your active subscription_id, then pass it downstream to proration, cancellation, or payment method update endpoints.
Common use cases:
- Subscription dashboard — Display your current plan, billing cycle, and payment status in your billing settings page.
- Payment failure handling — Check payment_failed: true to show an in-app banner prompting you to update your payment method before access is revoked.
- Trial expiry flows — Detect in_trial: true and can_be_canceled: false together to know you are in a free trial that cannot yet be cancelled.
- Reactivation eligibility — Use can_be_reactivated: true to show a reactivation prompt when you are still within the recovery window.
- Add-on visibility — Read the add_ons array to see which feature extensions are active on your current subscription.
Authorization: Bearer YOUR_TOKEN
Expected Behavior:
- On success, you receive a list of all your subscriptions under data.subscriptions along with a total count in meta.count.
- Status flags such as active, in_trial, payment_failed, and payment_pending reflect the current state of each subscription.
- The add_ons field will be null if no add-ons are attached to your subscription.
- You may have multiple subscriptions in the array — always filter by active: true to identify your current live subscription.
- If your request fails, an appropriate error message will be returned.