Subscriptions
The Subscriptions API is the public surface for the recurring side of the commerce model. Subscriptions are stored locally and (when the tenant has a billing integration) mirrored into the connected billing system; this API speaks to the local row and delegates lifecycle effects (proration, mid-cycle credits, dunning) to the active billing adapter.
The endpoints fall into three groups:
Discovery / read —
GET /subscriptions,GET /subscriptions/{id},GET /accounts/{id}/subscriptionsfor portals and dashboards.Create —
POST /subscriptionsfor net-new sign-ups; bind to acontactIdororganizationId.Lifecycle —
cancel,change-plan,renew. Each runs through the policy / business-rule engine before being applied. Use the matching Preview endpoints first if the customer-facing UI needs to show effective dates, proration, or retention requirements before committing.
All writes require the commerce scope; reads require read. Every state change writes an audit log entry (subscription.create / subscription.update / subscription.cancel / subscription.change_plan / subscription.renew) and emits an event for subscribed webhooks.
Webhook events emitted by these endpoints
POST /subscriptions
subscription.created
POST /subscriptions/{id}/change-plan
subscription.changed
POST /subscriptions/{id}/cancel
subscription.cancelled — for a Stripe subscription, subscription.changed when the cancel is scheduled, then subscription.cancelled when the period ends
POST /subscriptions/{id}/renew
subscription.renewed
Subscription events also carry the customer's resolved entitlement set — see Webhooks overview and the Entitlements API — so you can react to a subscription change without a second call to find out what the customer may now do.
Endpoints
GET /api/v1/accounts/{id}/subscriptions
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Max items to return (1–100, default 20)
20Number of items to skip (default 0)
0Field to sort by
Sort direction
ascPossible values: Paginated list of subscriptions
API key missing or invalid
No billing integration configured
GET /api/v1/accounts/{id}/subscriptions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
No content
Returns every subscription owned by the given account, sourced from the active billing adapter (fetchSubscriptions). Use this for customer-portal "your subscriptions" lists where you want the adapter as the source of truth (status, current term, next billing date).
Requires the read scope.
POST /api/v1/billing/stripe/resync
Reads each of this tenant's Stripe-backed subscriptions from Stripe and brings our record up to date (status, current period, billing interval, cancel-at-period-end), exactly as the Stripe webhooks would, including the same subscription.changed / subscription.cancelled events. A dry run by default, for every request shape: it returns before → after per field plus a planToken, and writes nothing. To apply, send ?execute=true (exactly) with body { planToken } taken from the dry run: the plan is recomputed from Stripe and applied only if it still matches the reviewed one. No token is 400 plan_token_required; a plan that changed since the dry run (or a different scope) is 409 plan_changed; a token older than 15 minutes is 409 plan_token_expired; in each case nothing is written. Admin only; an applied run is audited. When any subscription cannot be read from Stripe the rest are still processed and the response is 502 stripe_read_failed carrying the full report.
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Exactly true (with the dry run's planToken) to apply; anything else is a dry run
Required with execute=true: the planToken from the dry run being applied
Only this PeakCommerce subscription
The Stripe integration to use; required when the tenant has more than one active
data is { tenantId, integrationId, dryRun, checked, failed, planToken, planExpiresAt, rows: [{ subscriptionId, externalId, result: up_to_date | would_change | applied | failed, changes?: [{ field, before, after }] }] }
No content
Validation failed; execute=true without a planToken (plan_token_required); malformed planToken (invalid_plan_token)
Insufficient scope (admin required)
Named integration or subscription not found
No active Stripe integration, or several and none named; or, on execute, the plan changed since the dry run (plan_changed) or the planToken expired (plan_token_expired), with nothing written
At least one subscription could not be read from Stripe (stripe_read_failed); details is the full report
POST /api/v1/billing/stripe/resync HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 131
{
"planToken": "text",
"subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
"integrationId": "123e4567-e89b-12d3-a456-426614174000"
}No content
Notes, examples, or caveats for POST /billing/stripe/resync go here.
GET /api/v1/subscriptions
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Max items to return (1–100, default 20)
20Number of items to skip (default 0)
0Field to sort by
Sort direction
ascPossible values: Filter by status
Paginated list of subscriptions
API key missing or invalid
GET /api/v1/subscriptions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
No content
Tenant-wide list of every local subscription row, intended for back-office reconciliation. For account-scoped portal views prefer GET /accounts/{id}/subscriptions, which goes through the billing adapter and reflects the source-of-truth status.
Requires the read scope.
POST /api/v1/subscriptions
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Idempotency key to safely retry without creating duplicates
Subscription created
No content
Validation error
POST /api/v1/subscriptions HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 141
{
"productId": "text",
"contactId": "text",
"organizationId": "text",
"priceCents": 1,
"currency": "text",
"billingInterval": "text",
"externalId": "text"
}No content
Creates a new subscription for (productId, contactId | organizationId). Provide priceCents / currency / billingInterval to override the catalog defaults — useful for negotiated deals — otherwise the values are resolved from the product's catalog plan.
When the tenant has an active billing integration, supply externalId to record the corresponding subscription id in the connected system; the platform will use it to correlate future webhook events from the adapter.
Requires the commerce scope. Returns 201 and a nextActions hint pointing at POST /payments (for the first invoice).
GET /api/v1/subscriptions/{id}
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Subscription details
No content
GET /api/v1/subscriptions/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
Subscription details
No content
Returns the full local subscription row plus its current adapter-side status when an integration is configured. Returns 404 when the id is not owned by the calling tenant.
Requires the read scope.
POST /api/v1/subscriptions/{id}/cancel
For a subscription billed through Stripe, cancels AT STRIPE at the end of the paid period (cancel_at_period_end), the same as a portal cancel. The subscription stays active with cancelAtPeriodEnd: true until Stripe ends it, when status becomes cancelled and subscription.cancelled is sent. Nothing changes if Stripe does not accept the request. An eligible $0 Stripe subscription (every item priced at $0, with no schedule, pending update or pending charge) ends immediately instead, with no final invoice or credit; cancellation.immediate says which happened. A subscription with no billing provider is cancelled immediately. Repeating the call after a cancellation is scheduled is a no-op. Needs commerce, or the narrow subscriptions:cancel. A key holding only subscriptions:cancel can schedule a cancellation at the end of the paid period or end an eligible $0 subscription: for a subscription with no billing provider it is refused with 409 period_end_cancel_unavailable and nothing changes.
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Which Stripe integration, when the tenant has more than one
Cancellation scheduled at period end (cancellation.atPeriodEnd, cancellation.effectiveDate), or, with no billing provider, cancelled
No content
Blocked by a policy, or insufficient scope (commerce or subscriptions:cancel required)
Subscription not found
Already cancelled; the Stripe integration could not be resolved (pass integrationId); or period_end_cancel_unavailable (a key with only subscriptions:cancel, on a subscription with no billing provider). Nothing was changed.
Stripe did not accept the cancellation (provider_cancel_failed). Nothing was changed.
POST /api/v1/subscriptions/{id}/cancel HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"integrationId": "text"
}No content
Cancels the subscription. Your tenant's cancellation policies are checked first; if one blocks the cancel, the call returns 403 with code policy_violation and nothing changes.
What happens next depends on where the subscription is billed:
Billed through Stripe — PeakCommerce asks Stripe to cancel at the end of the current paid period, the same as a cancel from the customer portal. The subscription stays
activewithcancelAtPeriodEnd: true, and the response carriescancellation: { atPeriodEnd: true, effectiveDate }. Thesubscription.cancelledwebhook is sent when the period ends and Stripe ends the subscription. Calling cancel again on a subscription already scheduled returns the same result withalreadyScheduled: true.If your tenant has more than one active Stripe integration, pass
integrationIdin the body; without it the call returns409 stripe_integration_unresolved.If Stripe refuses the cancel, the call returns
502 provider_cancel_failedwith Stripe's reason, and nothing is changed.Writes
subscription.cancel_scheduledto the audit log.
Any other subscription — the subscription is marked
cancelledin PeakCommerce immediately and thesubscription.cancelledwebhook is sent. This endpoint does not send a cancellation to any other billing system. Writessubscription.cancelto the audit log.
A subscription that is already cancelled returns 409 already_cancelled.
Requires the commerce scope.
POST /api/v1/subscriptions/{id}/change-plan
Change the plan for a subscription (update product, price, interval)
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Plan changed
No content
POST /api/v1/subscriptions/{id}/change-plan HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 60
{
"productId": "text",
"priceCents": 1,
"billingInterval": "text"
}Plan changed
No content
Moves the subscription to a different product / price / billing interval. Proration, effective date, and any required co-term behavior come from the matching plan-change business rule — preview them with POST /preview/plan-change before committing.
When connected to a billing adapter, the change is forwarded to the adapter's amendment / subscription-update flow; the platform record is updated only after the adapter confirms.
Requires the commerce scope. Writes subscription.change_plan to the audit log.
POST /api/v1/subscriptions/{id}/change-quantity
Change the quantity of a subscription charge. Routes through the configured billing integration and applies any plan-dependency rules for the charge.
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Subscription ID
Idempotency key to safely retry without applying the change twice
Billing account the subscription belongs to — verified against the subscription before the change is applied
The subscription charge whose quantity is being changed
Which field the new value applies to (defaults to quantity)
Catalog charge ID, used to resolve plan-dependency rules
Billing integration to use. Defaults to the tenant's active integration.
Quantity changed — returns the billing integration's change result
No content
Validation error, no billing integration configured, or the integration does not support self-service changes
Subscription does not belong to the supplied account
POST /api/v1/subscriptions/{id}/change-quantity HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 127
{
"accountId": "text",
"chargeId": "text",
"newQuantity": 1,
"editedField": "quantity",
"catalogChargeId": "text",
"integrationId": "text"
}No content
Notes, examples, or caveats for POST /subscriptions/{id}/change-quantity go here.
POST /api/v1/subscriptions/{id}/renew
Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.
Subscription renewed
No content
POST /api/v1/subscriptions/{id}/renew HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
Subscription renewed
No content
Forces an immediate renewal of the subscription's current term — useful for renew-on-demand UIs and for back-office "extend the customer for another year" actions. Without an explicit call, renewal happens automatically on the term boundary.
Requires the commerce scope. Writes subscription.renew to the audit log.
Last updated
Was this helpful?
