Get Subscription

GET/api/subscriptions/{subscription_id}

Returns the full record for a single subscription, including current status, plan details, customer information, current period start and end, renewal history, and any active dunning attempts. Use this in your application's “manage subscription” screen, or in webhook handlers when you need to reconcile a renewal event against the latest server-side state. This endpoint is the only safe source of truth for subscription status — never rely on cached client-side state.

Request headers

Field	Type	Required	Description
Authorization	string	required	Your test or live API key. Example: `pg_live_xxx`

URL parameters

Field	Type	Required	Description
subscription_id	string	required	The subscription_id returned by Subscription Checkout. Example: `sub_01HZY8K2R4T8AB7CDEF9G2H3JK`

Response

200 OK

1{
2  "subscription_id": "sub_01HZY8K2R4T8AB7CDEF9G2H3JK",
3  "status": "active",
4  "plan": {
5    "id": "plan_pro_monthly",
6    "amount": 1500,
7    "currency": "BDT",
8    "interval": "month"
9  },
10  "customer": {
11    "id": "cus_01HZW...",
12    "full_name": "Tasin Fahim",
13    "email": "tasin@example.com"
14  },
15  "current_period_start": "2026-05-15T00:00:00Z",
16  "current_period_end":   "2026-06-15T00:00:00Z",
17  "cancel_at_period_end": false,
18  "renewal_history": [
19    { "invoice_id": "inv_01HZX...", "amount": 1500, "status": "completed", "paid_at": "2026-04-15T..." }
20  ],
21  "metadata": { "user_id": "u_99" },
22  "created_at": "2026-04-15T00:00:00Z"
23}

TipPossible status values

incomplete (initial checkout not finished), active (current and paid), past_due (renewal failed, dunning in progress), cancelled (ended), and expired (lapsed without renewal).

Error codes

Field	Type	Required	Description
401	unauthorized	optional	API key is missing or invalid.
403	wrong_storefront	optional	Subscription belongs to a different storefront.
404	not_found	optional	No subscription exists for the given id.