Subscriptions
Subscription entities describe a recurring billing relationship with a customer. They're closely related to transactions.
Subscriptions let you charge a customer on a recurring basis. They hold information about what Paddle should charge a customer for and how often.
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.
Subscription entities hold information like:
- Who you're billing
- Which prices a customer has subscribed to
- How often you charge your customer
- Details about trial periods
- Any upcoming scheduled changes
Subscriptions work products, prices, and discounts to say what a customer has subscribed to, and customers, addresses, and businesses to say who you're billing.
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 includes 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.
See: Proration