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