curl https://api.khaime.com/api/v1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
-H "X-API-Key: pk_sandbox_your_key"
Subscriptions
Get Subscription
Get details of a specific subscription.
GET
/
subscriptions
/
{subscription_id}
curl https://api.khaime.com/api/v1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
-H "X-API-Key: pk_sandbox_your_key"
Get Subscription
Intro
Retrieve the full record for a single subscription — billing state, trial info, plan snapshot, and payment history — by its ID. Use this when you already have asubscription_id (from a webhook, from List Subscriptions, or stored from creation) and need the current, uncached state of that one record.
Context
This sits alongside List Subscriptions and Cancel Subscription as one of the three subscription-management endpoints in the Partner API. Subscriptions are created by addingsubscription_frequency_key to a charge or checkout session, not through this endpoint — see Subscriptions for that flow and for how billing frequencies and renewals work.
Unlike the list endpoint, this call always reads the database directly, so it reflects any change immediately — including one made seconds ago through Cancel Subscription.
Hows
GET /subscriptions/{subscription_id}
Path parameters
| Parameter | Type | Description |
|---|---|---|
subscription_id | string (UUID) | The subscription ID to retrieve. |
Response
{
"success": true,
"data": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"product": {
"id": 3046,
"title": "Premium Plan",
"thumbnail": "https://cdn.khaime.com/products/3046.png",
"type": "digital"
},
"customer": {
"id": 88210,
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe"
},
"status": "active",
"frequency": "monthly",
"price": 4999,
"currency": "USD",
"quantity": 1,
"next_payment": "2026-02-16T21:05:00.000Z",
"last_payment_date": "2026-01-16T21:05:00.000Z",
"subscription_counts": 1,
"cancellation_date": null,
"trial": {
"is_on_trial": false,
"trial_start_date": null,
"trial_end_date": null,
"days_remaining": 0
},
"plan": {
"key": "premium_monthly",
"display_name": "Premium",
"features": ["Priority support", "Unlimited exports"]
},
"payment_history": [
{ "time": 1768597500000, "amount": 4999 }
],
"created_at": "2026-01-16T21:05:00.000Z",
"updated_at": "2026-01-16T21:05:00.000Z"
}
}
status is one of pending, active, due, cancelled, paused. price and currency describe the recurring charge; plan is a snapshot of the plan’s key, display name, and features as they were at the time the subscription was created, so it won’t change if you edit the plan later. payment_history entries are { time, amount }, with time as a Unix millisecond timestamp and amount in minor units. cancellation_date is only set once the subscription has been cancelled.
Errors
| Status | error_code | Cause |
|---|---|---|
| 400 | VALIDATION_MISSING_FIELD | subscription_id missing from the path |
| 400 | VALIDATION_FAILED | subscription_id isn’t a valid UUID |
| 404 | SUBSCRIPTION_PLAN_NOT_FOUND | No subscription with that ID, it belongs to a different merchant, or it belongs to the other environment (sandbox vs. live) from your API key |
| 400 | API_KEY_INVALID | API key isn’t associated with a merchant |
| 500 | INTERNAL_ERROR | Unexpected server error |
curl https://api.khaime.com/api/v1/subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
-H "X-API-Key: pk_sandbox_your_key"
Whys
A subscription you don’t own and a subscription that doesn’t exist return the identical404 SUBSCRIPTION_PLAN_NOT_FOUND — the API never confirms that an ID is valid but belongs to someone else. That’s deliberate: leaking “this ID is real, just not yours” is a way to enumerate other merchants’ subscription IDs over time.
The same logic applies to environment: a sandbox key requesting a live subscription’s ID gets a 404, not a 400 “wrong environment” error, again so the response can’t be used to distinguish “doesn’t exist” from “exists in the other mode.”
Why nots
- This endpoint doesn’t accept any body or query parameters to shape the response — you get the full record every time. If you only need a handful of fields across many subscriptions, List Subscriptions is the cheaper call.
- It’s read-only. To end a subscription, use Cancel Subscription — there’s no way to change status, price, or frequency through this endpoint.
payment_historyis whatever has accumulated on the record; it isn’t a paginated ledger, so a very long-lived subscription’s history returns in full on every call.