Paddle Billing
Search

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

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> or null

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 or null

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.

intervalstring

Unit of time.

frequencyinteger

Amount of time.

current_billing_periodobject or null

Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. null for paused and canceled subscriptions.

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

Related price entity for this item. This reflects the price entity at the time it was added to the subscription.

custom_dataobject or null

Your own structured key-value data.

import_metaobject or null

Import information for this entity. null if this entity is not imported.

external_idstring or null

Reference or identifier for this entity from the solution where it was imported from.

imported_fromstring

Name of the platform where this entity was imported from.

List subscriptions
Get a subscription
Preview an update to a subscription
Update a subscription
Get a transaction to update payment method
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
Retry payment for a subscription transaction
posthttps://api.paddle.com/subscriptions/{subscription_id}/transactions/{transaction_id}/retry