Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing
Search
Home
Concepts
Build
Errors
Webhooks
API reference
Paddle.js
Changelog
API reference

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

Follow our step-by-step guides to learn how to work with subscription items, upgrade or downgrade subscriptions, or pause or cancel them.

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.

Attributes

idstring

Unique Paddle ID for this subscription entity, prefixed with sub_.

statusstring

Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.

customer_idstring

Paddle ID of the customer that this subscription is for, prefixed with ctm_.

address_idstring

Paddle ID of the address that this subscription is for, prefixed with add_.

business_idstring or null

Paddle ID of the business that this subscription is for, prefixed with biz_.

currency_codestring

Supported three-letter ISO 4217 currency code. Transactions for this subscription are created in this currency. Must be USD, EUR, or GBP if collection_mode is manual.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

started_atstring<date-time> or null

RFC 3339 datetime string of when this subscription started. This may be different from first_billed_at if the subscription started in trial.

first_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was first billed. This may be different from started_at if the subscription started in trial.

next_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription is next scheduled to be billed.

paused_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was paused. Set automatically by Paddle when the pause subscription operation is used. null if not paused.

canceled_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. null if not canceled.

discountobject or null

Details of the discount applied to this subscription.

idstring

Unique Paddle ID for this discount, prefixed with dsc_.

starts_atstring<date-time>

RFC 3339 datetime string of when this discount was first applied.

ends_atstring<date-time>

RFC 3339 datetime string of when this discount no longer applies. Where a discount has maximum_recurring_intervals, this is the date of the last billing period where this discount applies. null where a discount recurs forever.

collection_modestring

How payment is collected for transactions created for this subscription. automatic for checkout, manual for invoices.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.

enable_checkoutboolean

Whether the related transaction may be paid using a Paddle Checkout.

purchase_order_numberstring

Customer purchase order number. Appears on invoice documents.

additional_informationstring

Notes or other information to include on this invoice. Appears on invoice documents.

payment_termsobject

How long a customer has to pay this invoice once issued.

current_billing_periodobject or null

Current billing period for this subscription. Set automatically by Paddle based on the billing cycle.

starts_atstring<date-time>

RFC 3339 datetime string of when this period starts.

ends_atstring<date-time>

RFC 3339 datetime string of when this period ends.

billing_cycleobject

How often this subscription renews. Set automatically by Paddle based on the prices on this subscription.

intervalstring

Unit of time.

frequencyinteger

Amount of time.

scheduled_changeobject or null

Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. null if no scheduled changes.

actionstring

Kind of change that's scheduled to be applied to this subscription.

effective_atstring<date-time>

RFC 3339 datetime string of when this scheduled change takes effect.

resume_atstring<date-time> or null

RFC 3339 datetime string of when a paused subscription should resume. Only used for pause scheduled changes.

management_urlsobject

Public URLs that customers can use to make changes to this subscription. For security, the token appended to each link is temporary. You shouldn't store these links.

update_payment_methodstring<uri> or null

Public URL that lets customers update the payment method for this subscription. Creates or gets a transaction that can be used to update a payment method, then passes it to your default checkout page.

cancelstring<uri>

Public URL that lets customers cancel this subscription. Takes customers to a Paddle page that lets them cancel their subscription.

itemsarray[object]

Represents a subscription item.

statusstring

Status of this subscription item. Set automatically by Paddle.

quantitynumber

Quantity of this item on the subscription.

recurringboolean

Whether this is a recurring item. false if one-time.

created_atstring<date-time>

RFC 3339 datetime string of when this item was added to this subscription.

updated_atstring<date-time>

RFC 3339 datetime string of when this item was last updated on this subscription.

previously_billed_atstring<date-time> or null

RFC 3339 datetime string of when this item was last billed.

next_billed_atstring<date-time> or null

RFC 3339 datetime string of when this item is next scheduled to be billed.

trial_datesobject or null

Trial dates for this item.

priceobject

Price object for this item.

custom_dataobject or null

Your own structured key-value data.

List subscriptions
gethttps://api.paddle.com/subscriptions
Get a subscription
gethttps://api.paddle.com/subscriptions/{subscription_id}
Preview an update to a subscription
patchhttps://api.paddle.com/subscriptions/{subscription_id}/preview
Update a subscription
patchhttps://api.paddle.com/subscriptions/{subscription_id}
Get a transaction to update payment method
gethttps://api.paddle.com/subscriptions/{subscription_id}/update-payment-method-transaction
Preview a one-time charge for a subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/charge/preview
Create a one-time charge for a subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/charge
Activate a trialing subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/activate
Pause a subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/pause
Resume a paused subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/resume
Cancel a subscription
posthttps://api.paddle.com/subscriptions/{subscription_id}/cancel