Subscriptions
The subscriptions feature defines account-owner subscription and plan operations exposed through Inbox Manager proxy routes. It gives owners direct plan lifecycle control while keeping account and role checks strict.
Why This Matters
This feature consolidates owner subscription actions under the Inbox Manager API surface while preserving strict account and role checks from bearer token claims. It exposes checkout, portal, sync, and plan-change operations without requiring clients to duplicate subscription orchestration logic.
Core Flow
Operations
| Operation | Endpoint | Purpose |
|---|---|---|
| List subscriptions | GET /api/subscriptions |
Retrieve subscriptions for token-selected account |
| List features | GET /api/subscriptions/features |
Retrieve active subscription feature set |
| Get subscription identity | GET /api/subscriptions/identity |
Retrieve subscription identity binding for account |
| List merchants | GET /api/subscriptions/merchants |
Retrieve merchant/provider options |
| Sync subscriptions | POST /api/subscriptions/sync |
Refresh subscription state from provider |
| Change subscription | POST /api/subscriptions/:subscription_id/change |
Modify plan or interval |
| Cancel subscription | POST /api/subscriptions/:subscription_id/cancel |
End subscription lifecycle |
| Create checkout session | POST /api/subscriptions/stripe/checkout-session |
Start checkout for new or changed plan |
| Create portal session | POST /api/subscriptions/stripe/portal-session |
Open self-service subscription portal |
| Sync checkout session | POST /api/subscriptions/stripe/checkout-session-sync |
Link checkout completion to subscription state |
Key Data and State
{
data: {
account_id: "acc_...",
subscription_id: "sub_...",
status: "active"
},
links: {
checkout_url: "https://checkout.stripe.com/..."
}
}All responses use proxy-envelope style payloads keyed by data with optional links.
Failure Modes and Controls
Missing or invalid acc claim rejects owner subscription operations, and non-owner callers are blocked from owner-scoped subscription actions. Upstream proxy failures are returned as explicit operation failures, and subscription mutation remains restricted to explicit change or cancel routes.