***

title: Subscriptions
subtitle: Create and manage subscriptions
slug: endpoints/subscriptions
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/endpoints/llms.txt. For full documentation content, see https://docs.prolifi.io/endpoints/llms-full.txt.

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.