Fields
None. Needs Subscription: Read, which a key of a Data Feed or an FFL Checkout store can hold.
It answers whatever the subscription's status, including while the store is suspended or canceled: that is when a store most needs the link to renew. Nothing here changes the subscription.
What it answers
| Field | Meaning |
|---|---|
| status | The subscription's status: trialing, active, past_due, unpaid, paused, canceled, incomplete or incomplete_expired, and any added later. Null when the store has no subscription. |
| plan | The plan, as below, or null. |
| trial_ends_at | When the trial ends, or null. |
| current_period_end | When the period paid for ends, or null. |
| renews | true when the subscription carries on into another period by itself. false when it is set to end, a payment failed (past_due), it is unpaid or has ended, or there is none. |
| ends_at | When it is set to end, while it still runs. Null when it renews, has no date, or has already ended. |
| renewal_url | Null while it renews, and for an active store with no subscription. Otherwise a link to a page where the store renews, updates its card, pays or subscribes again. The page sends the store on to Stripe, where card details are typed. |
The plan
| Field | Meaning |
|---|---|
| name | Such as Data Feed (monthly). |
| price | Per interval, as a string with two decimals, such as "17.99". |
| currency | ISO 4217, lowercase, such as usd. |
| interval | month or year. |
Treat renewal_url as a secret
The link works for an hour, and whoever holds it can open your store's billing. Fetch it when a person is about to use it, show it to them, and never store, log or email it.
Told before it ends
Seven days or fewer before a subscription that is set to end, your store gets a subscription.ending_soon change, once for each end date: by webhook, and in GET /changes for a key that can also read Products and changes. Its payload holds license_id, billing_status, ends_at and cancel_at_period_end, and no link: call GET /subscription when a person is about to renew. A subscription that renews is never announced.
Returns
- 200The store's subscription, in
data.
This endpoint can also answer 401 invalid_api_key, 403 insufficient_scope and 429 rate_limited. It never answers 403 license_not_active.