> 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](/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](/developers/api-groups/webhooks.md).

## Endpoints

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/accounts/{id}/subscriptions" method="get" %}
<https://api.peakcommerce.com/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.

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/subscriptions" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/subscriptions" method="post" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/subscriptions/{id}" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/subscriptions/{id}/cancel" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

Cancels the subscription. The effective date and refund / credit behavior are determined by the matching cancellation **business rule** (see [`POST /preview/cancellation`](/developers/api-groups/preview.md#post-apiv1previewcancellation) 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`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/subscriptions/{id}/change-plan" method="post" %}
<https://api.peakcommerce.com/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`](/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}/renew`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/subscriptions/{id}/renew" method="post" %}
<https://api.peakcommerce.com/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.