For the complete documentation index, see llms.txt. This page is also available as Markdown.

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}/subscriptions for portals and dashboards.

  • Create — POST /subscriptions for net-new sign-ups; bind to a contactId or organizationId.

  • 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

Endpoint
Event

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

List subscriptions for an account via the billing adapter

get
/accounts/{id}/subscriptions
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired
Query parameters
limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20
offsetintegerOptional

Number of items to skip (default 0)

Default: 0
sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:
Responses
200

Paginated list of subscriptions

get/accounts/{id}/subscriptions
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

Re-sync existing Stripe subscriptions from Stripe

post
/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.

Required scopes
This endpoint requires the following scopes:
Authorizations
X-API-KeystringRequired

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.

Query parameters
executebooleanOptional

Exactly true (with the dry run's planToken) to apply; anything else is a dry run

Body
planTokenstringOptional

Required with execute=true: the planToken from the dry run being applied

subscriptionIdstring · uuidOptional

Only this PeakCommerce subscription

integrationIdstring · uuidOptional

The Stripe integration to use; required when the tenant has more than one active

Responses
200

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

post/billing/stripe/resync
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

List all subscriptions for the tenant

get
/subscriptions
Authorizations
X-API-KeystringRequired

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.

Query parameters
limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20
offsetintegerOptional

Number of items to skip (default 0)

Default: 0
sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:
statusstringOptional

Filter by status

Responses
200

Paginated list of subscriptions

get/subscriptions
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

Create a new subscription

post
/subscriptions
Authorizations
X-API-KeystringRequired

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.

Header parameters
Idempotency-KeystringOptional

Idempotency key to safely retry without creating duplicates

Body
productIdstringRequired
contactIdstringOptional
organizationIdstringOptional
priceCentsintegerOptional
currencystringOptional
billingIntervalstringOptional
externalIdstringOptional
Responses
201

Subscription created

No content

post/subscriptions
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}

Get subscription details

get
/subscriptions/{id}
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired
Responses
200

Subscription details

No content

get/subscriptions/{id}
GET /api/v1/subscriptions/{id} HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
200

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

Cancel a subscription

post
/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.

Required scopes
This endpoint requires the following scopes:
or
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired
Body
integrationIdstringOptional

Which Stripe integration, when the tenant has more than one

Responses
200

Cancellation scheduled at period end (cancellation.atPeriodEnd, cancellation.effectiveDate), or, with no billing provider, cancelled

No content

post/subscriptions/{id}/cancel
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 active with cancelAtPeriodEnd: true, and the response carries cancellation: { atPeriodEnd: true, effectiveDate }. The subscription.cancelled webhook is sent when the period ends and Stripe ends the subscription. Calling cancel again on a subscription already scheduled returns the same result with alreadyScheduled: true.

    • If your tenant has more than one active Stripe integration, pass integrationId in the body; without it the call returns 409 stripe_integration_unresolved.

    • If Stripe refuses the cancel, the call returns 502 provider_cancel_failed with Stripe's reason, and nothing is changed.

    • Writes subscription.cancel_scheduled to the audit log.

  • Any other subscription — the subscription is marked cancelled in PeakCommerce immediately and the subscription.cancelled webhook is sent. This endpoint does not send a cancellation to any other billing system. Writes subscription.cancel to 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)

post
/subscriptions/{id}/change-plan
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired
Body
productIdstringOptional
priceCentsintegerOptional
billingIntervalstringOptional
Responses
200

Plan changed

No content

post/subscriptions/{id}/change-plan
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"
}
200

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.

post
/subscriptions/{id}/change-quantity
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired

Subscription ID

Header parameters
Idempotency-KeystringOptional

Idempotency key to safely retry without applying the change twice

Body
accountIdstringRequired

Billing account the subscription belongs to — verified against the subscription before the change is applied

chargeIdstringRequired

The subscription charge whose quantity is being changed

newQuantityintegerRequired
editedFieldstring · enumOptional

Which field the new value applies to (defaults to quantity)

Possible values:
catalogChargeIdstringOptional

Catalog charge ID, used to resolve plan-dependency rules

integrationIdstringOptional

Billing integration to use. Defaults to the tenant's active integration.

Responses
200

Quantity changed — returns the billing integration's change result

No content

post/subscriptions/{id}/change-quantity
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

Renew a subscription

post
/subscriptions/{id}/renew
Authorizations
X-API-KeystringRequired

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.

Path parameters
idstringRequired
Responses
200

Subscription renewed

No content

post/subscriptions/{id}/renew
POST /api/v1/subscriptions/{id}/renew HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*
200

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?