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


Transaction entities calculate and capture revenue. They hold information about an amount that you're billing for.

Transactions are at the heart of Paddle. They tie together products, prices, and discounts with customers to calculate revenue for checkouts, invoices, and subscriptions.

Paddle automatically creates transactions when customers sign up using the checkout, as well as when subscription lifecycle events like renewals or upgrades happen.

You can also create a transaction through the Dashboard or API. You may collect for a transaction manually to create an invoice, or collect automatically using a card on file or by presenting a checkout.

Transactions hold information like:

  • Who you're billing
  • Which prices you're billing for
  • Whether you'd like to generate an invoice number
  • Calculated totals for the customer and items
  • Any payment attempts


Transactions handle all parts of revenue calculation, including complex proration operations, localized pricing, and tax calculations.

Paddle returns calculated totals for a transaction in the details object. Details are the single source for totals on a transaction. Ultimately, they're used for collecting payment from a customer and revenue recognition.


Though the terms "transaction" and "payment" are sometimes used interchangeably, they're distinct entities in Paddle:

  • Transactions calculate and captures revenue, ready for payment
  • Payments are attempts to collect for the amount against a transaction – both online and offline

Transactions may have more than one payment against them. For example, customers paying for larger value deals by invoice might make multiple payments, and automatically collected payments might fail.


For pricing pages and other screens that let customers preview changes to their subscription, you can preview a transaction rather than creating it.

When previewing a transaction, you don't need to send the same information as you would if you were creating it.

See: Preview a transaction

Transactions are financial records. They can't be deleted, and they can't be changed once they've been billed. Cancel a transaction, or create an adjustment to record post-billing actions that impact a transaction.



Unique Paddle ID for this transaction entity, prefixed with txn_.


Status of this transaction. You may set a transaction to billed or canceled, other statuses are set automatically by Paddle. Automatically-collected transactions may return completed if payment is captured successfully, or past_due if payment failed.

customer_idstring or null

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

address_idstring or null

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

business_idstring or null

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

custom_dataobject or null

Your own structured key-value data.


Supported three-letter ISO 4217 currency code. Must be USD, EUR, or GBP if collection_mode is manual.


Describes how this transaction was created.

subscription_idstring or null

Paddle ID of the subscription that this transaction is for, prefixed with sub_.

invoice_idstring or null

Paddle ID of the invoice that this transaction is related to, prefixed with inv_. Used for compatibility with the initial version of the Paddle Invoice API.

invoice_numberstring or null

Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as billed where collection_mode is manual.


How payment is collected for this transaction. automatic for checkout, manual for invoices.

discount_idstring or null

Paddle ID of the discount applied to this transaction, prefixed with dsc_.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.


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


Customer purchase order number. Appears on invoice documents.


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


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

billing_periodobject or null

Time period that this transaction is for. Set automatically by Paddle for recurring subscriptions to describe the period that charges are for.


RFC 3339 datetime string of when this period starts.


RFC 3339 datetime string of when this period ends.


List of items on this transaction. For calculated totals, use details.line_items.


Paddle ID for the price to add to this transaction, prefixed with pri_.


Represents a price entity.


Quantity of this item on the transaction.

prorationobject or null

How proration was calculated for this item. Populated when a transaction is created from a subscription change, where proration_billing_mode was prorated_immediately or prorated_next_billing_period. Set automatically by Paddle.


Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.


List of tax rates applied for this transaction.


Breakdown of the total for a transaction.


Breakdown of the payout totals for a transaction after adjustments. null until the transaction is completed.

payout_totalsobject or null

Breakdown of the payout total for a transaction. null until the transaction is completed. Returned in your payout currency.

adjusted_payout_totalsobject or null

Breakdown of the payout total for a transaction after adjustments. null until the transaction is completed.


Information about line items for this transaction. Different from transaction items as they include totals calculated by Paddle. Considered the source of truth for line item totals.


List of payment attempts for this transaction, including successful payments. Sorted by created_at in descending order, so most recent attempts are returned first.


UUID for this payment attempt.


UUID for the stored payment method used for this payment attempt.


Amount for collection in the lowest denomination of a currency (e.g. cents for USD).


Status of this payment attempt.

error_codestring or null

Reason why a payment attempt failed. Returns null if payment captured successfully.


Information about the payment method used for a payment attempt.


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

captured_atstring<date-time> or null

RFC 3339 datetime string of when this payment was captured. null if status is not captured.

checkoutobject or null

Paddle Checkout details for this transaction. Returned for automatically-collected transactions and where billing_details.enable_checkout is true for manually-collected transactions; null otherwise.


Paddle Checkout URL for this transaction, composed of your default payment URL + _?txn= and the Paddle ID for this transaction.


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


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

billed_atstring<date-time> or null

RFC 3339 datetime string of when this transaction was marked as billed. null for transactions that are not billed or completed. Set automatically by Paddle.

List transactions
Create a transaction
Get a transaction
Update a transaction
Preview a transaction
Get a PDF invoice for a transaction