> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.prolifi.io/endpoints/subscriptions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.prolifi.io/_mcp/server.

# Subscriptions

A subscription links a customer to a plan with a billing cycle. Subscriptions are the core billing object in Prolifi.

## Endpoints

| Method   | Path                         | Description                                |
| -------- | ---------------------------- | ------------------------------------------ |
| `POST`   | `/subscriptions`             | Create a new subscription                  |
| `GET`    | `/subscriptions`             | List subscriptions (paginated)             |
| `GET`    | `/subscriptions/{id}`        | Get a subscription                         |
| `PATCH`  | `/subscriptions/{id}`        | Update a subscription or switch plans      |
| `DELETE` | `/subscriptions/{id}`        | Cancel a subscription                      |
| `POST`   | `/subscriptions/{id}/pause`  | Pause a subscription (coming soon)         |
| `POST`   | `/subscriptions/{id}/resume` | Resume a paused subscription (coming soon) |

## Key concepts

* **Billing cycle resolution**: The `billing_cycle` field accepts a UUID or a name (e.g., `"monthly"`, `"yearly"`). It is matched against the plan's available billing cycles.
* **Country resolution**: If `country_id` is not provided when creating a subscription, it is automatically resolved from the customer's record.
* **Plan switching**: When you update a subscription with a different `plan_id`, Prolifi handles the plan switch — including proration, billing adjustments, and entitlement changes.
* **Cancellation timing**: Cancel at `end_of_period` (default) lets the subscription run until the billing cycle ends. Cancel `immediately` to end the subscription right away.
* **Pause/Resume**: These endpoints are planned but not yet available. They return `501` with a descriptive message.

> Create and manage subscriptions


## API Docs

- Subscriptions [Create a subscription](https://docs.prolifi.io/endpoints/subscriptions/create-subscription.md)
- Subscriptions [List subscriptions](https://docs.prolifi.io/endpoints/subscriptions/list-subscriptions.md)
- Subscriptions [Get a subscription](https://docs.prolifi.io/endpoints/subscriptions/get-subscription.md)
- Subscriptions [Update a subscription](https://docs.prolifi.io/endpoints/subscriptions/update-subscription.md)
- Subscriptions [Cancel a subscription](https://docs.prolifi.io/endpoints/subscriptions/cancel-subscription.md)
- Subscriptions [Pause a subscription](https://docs.prolifi.io/endpoints/subscriptions/pause-subscription.md)
- Subscriptions [Resume a subscription](https://docs.prolifi.io/endpoints/subscriptions/resume-subscription.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.prolifi.io/endpoints/subscriptions/openapi.json)
- [OpenAPI YAML](https://docs.prolifi.io/endpoints/subscriptions/openapi.yaml)