Subscriptions

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, prices, and discounts to say what a customer has subscribed to, and customers, addresses, and businesses 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, or when you create and issue an invoice 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 to cancel a subscription.

Transactions

Billing for subscriptions is powered by transactions. 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.

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, pause, or update an item on a subscription and returns them in the scheduled_change object.

Proration

Proration 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 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.

History

Paddle keeps a chronological record of the changes made to a subscription over its lifetime. See subscription history to retrieve what changed, when, where, who did it, and why.