> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Subscriptions

Subscription entities describe a recurring billing relationship with a customer. They're closely related to transactions.

---

Subscriptions let customers pay for products on a recurring schedule. They hold information about what Paddle should charge a customer for and how often.

Subscription entities hold information like:

- Who the customer is.
- Which prices a customer has subscribed to.
- How often a subscription renews.
- Details about trial periods.
- Any upcoming scheduled changes.

Subscriptions work with [products](https://developer.paddle.com/api-reference/products.md), [prices](https://developer.paddle.com/api-reference/prices.md), and [discounts](https://developer.paddle.com/api-reference/discounts.md) to say what a customer has subscribed to, and [customers](https://developer.paddle.com/api-reference/customers.md), [addresses](https://developer.paddle.com/api-reference/addresses.md), and [businesses](https://developer.paddle.com/api-reference/businesses.md) to say who the customer is.

### Create a subscription

You can't create a subscription directly.

Paddle automatically creates subscriptions for you when customers pay for recurring items using [the checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md), or when you [create and issue an invoice](https://developer.paddle.com/build/invoices/create-issue-invoices.md) using a manually-collected transaction.

### Delete a subscription

Subscriptions describe an ongoing financial relationship with a customer, so they can't be deleted. Use the [cancel a subscription operation](https://developer.paddle.com/api-reference/subscriptions/cancel-subscription.md) to cancel a subscription.

### Transactions

Billing for subscriptions is powered by [transactions](https://developer.paddle.com/api-reference/transactions.md). When a subscription bills, Paddle creates a related transaction to calculate totals and collect for payment.

You can get a preview of the next transaction when getting a subscription [using the `include` parameter](https://developer.paddle.com/api-reference/about/include-entities.md).

### Scheduled changes

A scheduled change is a change that's going to happen automatically when the subscription next bills.

Paddle creates a scheduled change automatically when you [cancel](https://developer.paddle.com/build/subscriptions/cancel-subscriptions.md), pause, or [update an item](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md) on a subscription and returns them in the `scheduled_change` object.

### Proration

[Proration](https://developer.paddle.com/concepts/subscriptions/proration.md) is how Paddle calculates what a customer should be billed for, based on changes made in the current billing cycle.

When updating subscription items, you must include the `proration_billing_mode` field to tell Paddle how to handle proration for the items you're adding or removing.

### Customer portal URLs

Subscriptions return authenticated links to the [customer portal](https://developer.paddle.com/concepts/customer-portal.md) in the `management_urls` object. You can use these links to redirect customers to the portal to manage their subscriptions.

Authenticated links are only returned when your API key has a Customer portal session (Write) [permission](https://developer.paddle.com/api-reference/about/permissions.md).

{% callout type="info" %}
The `token` appended to authenticated links is the token for the [customer portal session](https://developer.paddle.com/api-reference/customer-portal-sessions.md). It is temporary and shouldn't be cached or stored.
{% /callout %}