> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Subscriptions

A subscription captures the commercial relationship between a customer and a billing entity: it ties a customer to a pricing plan and its terms, and is what eventually results in invoices.

---

## Why this matters

Everything you bill flows through a subscription. It determines which pricing applies, in which currency, on what cadence, and how the resulting invoice is paid. Understanding its parts (details, terms, and schedules) is a prerequisite for the rest of this section.

## How it works

A subscription connects a customer to one or more schedules, each of which points to a pricing plan version for a period of time. Invoices are generated per billing period from the active schedule.

```mermaid
erDiagram
    CUSTOMER ||--o{ SUBSCRIPTION : has
    SUBSCRIPTION ||--|{ SCHEDULE : contains
    SCHEDULE }o--|| PRICING-PLAN-VERSION : "prices with"
    SUBSCRIPTION ||--o{ INVOICE : generates
```

Subscriptions follow their own lifecycle (`DRAFT`, `ACTIVE`, `PAUSED`, and terminal states); see [Subscription lifecycle](/platform-guides/customers-and-billing/subscriptions/subscription-lifecycle) for the full state table.

## Create a subscription

### Via API

Create a subscription with the [Create a pricing plan subscription](/api-docs/configuration-api/pricing-plan-subscriptions/create-a-pricing-plan-subscription) endpoint:

**`Create a subscription`**

```curl Create a subscription
curl -X POST https://test.api.solvimon.com/v1/pricing-plan-subscriptions \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "sub-acme-2026",
    "purchase_order_number": "MyPONumber_001",
    "customer_id": "cust_awDeAl0tsKup9BBJNU1m",
    "billing_entity_id": "bile_EwDegI0tt0diFEBEed12",
    "billing_period": { "type": "MONTH", "value": 1 },
    "billing_currency": "EUR"
  }'
```

**`Response`**

```json Response
{
  "object_type": "PRICING_PLAN_SUBSCRIPTION",
  "id": "ppsu_awDeAl0tsKup9BBJNU1m",
  "status": "DRAFT",
  "reference": "sub-acme-2026",
  "purchase_order_number": "MyPONumber_001",
  "customer_id": "cust_awDeAl0tsKup9BBJNU1m",
  "billing_entity_id": "bile_EwDegI0tt0diFEBEed12",
  "billing_period": { "type": "MONTH", "value": 1 },
  "billing_currency": "EUR"
}
```

The subscription is created in `DRAFT` status. To make it billable, add one or more [schedules](/platform-guides/customers-and-billing/subscriptions/subscription-schedules) linking it to a pricing plan version.

> **Tip**
>
> If you want to create the subscription, its schedule, and the first invoice (optionally with a first payment attempt) in a single call, use the init endpoint instead. See [Subscription initialisation](/platform-guides/customers-and-billing/subscriptions/subscription-initialisation).

### Via Desk

## Subscription details

Selecting the customer and the variant is mandatory when creating a subscription.

The variant defines the structure of invoicing and event calculation for that customer:

| Variant           | Behaviour                                                                                                                                                           |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DEFAULT`         | The customer on the subscription is billed directly.                                                                                                                |
| `FORWARD_BILLING` | Charges are forwarded to another customer, typically in a [parent-child account](/platform-guides/customers-and-billing/customer/parent-child-relationships) setup. |

![](/_fern-img/fd8ea35e983fb8596c24a5b60fe6c5259a2c21bcb2e954648ddd0a3a679f61eb.webp)

Optional information can also be added to a subscription:

* **Reference**: unique across all subscription resources; use it to identify individual subscriptions from your own systems.
* **Name**: a free-form label with no uniqueness validation.
* **PO number**: carried onto the generated invoices.

## Subscription terms

Subscription terms are the billing and invoicing rules the subscription adheres to.

![](/_fern-img/a956a08de219426851e48382dafb736efc2608333ce8c053d9524fb39830b369.webp)

* **Billing currency**: the currency invoices are issued in.
* **Payment terms**: determine the invoice due date.
* **Billing time**: `CALENDAR` (aligned to calendar periods) or `EXACT` (anniversary billing, aligned to the activation date). Read more in [Billing cycles & pro-ration](/platform-guides/customers-and-billing/subscriptions/billing-cycles-proration).
* **Taxation**: the country code on the billing entity together with the country code on the customer decides the taxation of the invoice line items.
* **Payment methods**: setting the invoice [payment method](/integrations/paymentserviceproviders/adyen)(s) on the subscription ensures this information is on the generated invoice. The dropdown populates based on the billing entity selected.

> **Note**
>
> Default terms can be set at platform level in the subscription settings; any term you don't set explicitly falls back to the platform default. Read more in [Default platform settings](/platform-guides/platform-configuration/default-platform-settings).

## Combining subscriptions

You can combine multiple subscriptions for one customer. If `combine` is enabled and the terms match (billing entity, currency, billing time, and payment terms), a single invoice is generated for that customer with the product items from each subscription showing up as invoice lines.

> **Note**
>
> If one of the subscriptions in the combined group is voided and the invoice is not final, the invoice lines from that subscription are removed from the invoice.

For pooling volume across multiple customers that are billed individually, use [subscription groups](/platform-guides/customers-and-billing/subscriptions/subscription-groups) instead.

## Duplicating subscriptions

You can duplicate a subscription to create a new one. This copies the entire subscription in `DRAFT` status, including all schedules, discounts, commitments, and overwrites. In Desk, use the duplicate action on the subscription; via the API, use the copy endpoint (`POST /v1/pricing-plan-subscriptions/{resourceId}/copy`).

![](/_fern-img/bc960624bcb5c576978340ec72d552165d058e7d9dbdf60f48d181755192e47a.webp)

## Ramp-up periods

Ramp-up periods let you introduce customers to your product gradually with adjusted pricing in the early billing periods. By adding multiple schedules with adjusted pricing to a customer's subscription, you can create any ramp-up that you want.

There are multiple ways to create ramp-up periods:

* **Fixed ramp-up pricing plan template**: if a ramp-up period is a standard offering and prices are fairly fixed, create the ramp-up prices in a standard pricing plan and version.
* **Custom schedules per customer**: for customer-specific ramp-ups, add multiple [subscription schedules](/platform-guides/customers-and-billing/subscriptions/subscription-schedules) with [discounts, commitments, or included volume](/platform-guides/customers-and-billing/subscriptions/schedule-configurations) adjusted per period.

## Explore this section

#### [Subscription lifecycle](/platform-guides/customers-and-billing/subscriptions/subscription-lifecycle)

Statuses from Draft to Cancelled, and what you can change in each.

#### [Billing cycles & pro-ration](/platform-guides/customers-and-billing/subscriptions/billing-cycles-proration)

Billing frequencies, calendar vs. anniversary billing, and pro-ration.

#### [Subscription schedules](/platform-guides/customers-and-billing/subscriptions/subscription-schedules)

Link pricing plan versions to periods of time and handle plan changes.

#### [Draft schedules](/platform-guides/customers-and-billing/subscriptions/draft-schedules)

Prepare a schedule, get it reviewed, and activate it as one deliberate step.

#### [Discounts, commitments, and included volume](/platform-guides/customers-and-billing/subscriptions/schedule-configurations)

Tailor a schedule for a specific customer without changing the pricing plan.

#### [Customising subscriptions & pricing](/platform-guides/customers-and-billing/subscriptions/custom-pricing)

Custom pricing plans for customers that don't fit standard offerings.

#### [Price indexation](/platform-guides/customers-and-billing/subscriptions/price-indexation)

Move every price on a schedule by a percentage for an annual uplift.

#### [Plan changes in a pricing plan group](/platform-guides/customers-and-billing/subscriptions/plan-changes)

Move a subscription to another plan in the same group, on the group's own timing rules.

#### [Subscription groups](/platform-guides/customers-and-billing/subscriptions/subscription-groups)

Pool volume across child customers while billing them individually.

#### [Subscription initialisation](/platform-guides/customers-and-billing/subscriptions/subscription-initialisation)

Create a subscription, schedule, and first invoice in a single API call.

## Docs

- [Subscription lifecycle](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/subscription-lifecycle.md)
- [Billing cycles & Pro-ration](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/billing-cycles-proration.md)
- [Discounts, commitments, and included volume](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/schedule-configurations.md)
- [Customising subscriptions & pricing](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/custom-pricing.md)
- [Subscription Groups](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/subscription-groups.md)
- [Subscription Initialisation](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/subscription-initialisation.md)
- [Subscription schedules](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/subscription-schedules.md)
- [Draft schedules](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/draft-schedules.md)
- [Price indexation](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/price-indexation.md)
- [Plan changes in a pricing plan group](https://docs.solvimon.com/platform-guides/customers-and-billing/subscriptions/plan-changes.md)