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.

Endpoints

GET /api/v1/accounts/{id}/subscriptions

List subscriptions for an account via the billing adapter

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/accounts/{id}/subscriptions

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

401

API key missing or invalid

application/json

404

No billing integration configured

application/json

get/accounts/{id}/subscriptions

HTTPcURLJavaScriptPython

GET /api/v1/accounts/{id}/subscriptions HTTP/1.1
Host: 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.

GET /api/v1/subscriptions

List all subscriptions for the tenant

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

401

API key missing or invalid

application/json

get/subscriptions

HTTPcURLJavaScriptPython

GET /api/v1/subscriptions HTTP/1.1
Host: 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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Header parameters

Idempotency-KeystringOptional

Idempotency key to safely retry without creating duplicates

Body

application/json

productIdstringRequired

contactIdstringOptional

organizationIdstringOptional

priceCentsintegerOptional

currencystringOptional

billingIntervalstringOptional

externalIdstringOptional

Responses

201

Subscription created

No content

400

Validation error

application/json

post/subscriptions

HTTPcURLJavaScriptPython

POST /api/v1/subscriptions HTTP/1.1
Host: 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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Subscription details

No content

get/subscriptions/{id}

HTTPcURLJavaScriptPython

GET /api/v1/subscriptions/{id} HTTP/1.1
Host: 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

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions/{id}/cancel

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Subscription cancelled

No content

post/subscriptions/{id}/cancel

HTTPcURLJavaScriptPython

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

200

Subscription cancelled

No content

Cancels the subscription. The effective date and refund / credit behavior are determined by the matching cancellation business rule (see POST /preview/cancellation to compute it ahead of time). The platform then forwards the cancel call to the active billing adapter.

If a retention save flow is enabled for the tenant, this endpoint can also accept an inline feedback object captured from the cancellation form; that record is written to cancellation_feedback for analytics regardless of whether the cancel proceeds.

Requires the commerce scope. Writes subscription.cancel to the audit log.

POST /api/v1/subscriptions/{id}/change-plan

Change the plan for a subscription (update product, price, interval)

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions/{id}/change-plan

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Body

application/json

productIdstringOptional

priceCentsintegerOptional

billingIntervalstringOptional

Responses

200

Plan changed

No content

post/subscriptions/{id}/change-plan

HTTPcURLJavaScriptPython

POST /api/v1/subscriptions/{id}/change-plan HTTP/1.1
Host: 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}/renew

Renew a subscription

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/subscriptions/{id}/renew

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Subscription renewed

No content

post/subscriptions/{id}/renew

HTTPcURLJavaScriptPython

POST /api/v1/subscriptions/{id}/renew HTTP/1.1
Host: 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.