> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-groups/subscriptions.md).

# 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](https://docs.peakcommerce.com/developers/api-groups/preview.md) 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](https://docs.peakcommerce.com/developers/api-groups/webhooks.md).

### 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](https://docs.peakcommerce.com/developers/api-reference/webhooks-overview.md#resolved-entitlements-on-subscription-events) and the [Entitlements API](https://docs.peakcommerce.com/developers/api-groups/entitlements.md) — 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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/accounts/{id}/subscriptions" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/billing/stripe/resync" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `POST /billing/stripe/resync` go here.*

### `GET /api/v1/subscriptions`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Tenant-wide list of every local subscription row, intended for back-office reconciliation. For account-scoped portal views prefer [`GET /accounts/{id}/subscriptions`](#get-apiv1accountsidsubscriptions), which goes through the billing adapter and reflects the source-of-truth status.

Requires the `read` scope.

### `POST /api/v1/subscriptions`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions/{id}" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions/{id}/cancel" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions/{id}/change-plan" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`](https://docs.peakcommerce.com/developers/api-groups/preview.md#post-apiv1previewplan-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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions/{id}/change-quantity" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `POST /subscriptions/{id}/change-quantity` go here.*

### `POST /api/v1/subscriptions/{id}/renew`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/subscriptions/{id}/renew" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/api-groups/subscriptions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
