Transactions

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 Paddle dashboard or the 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 the customer is.
Which items they're purchasing.
Calculated totals for the customer and items.
Any payment attempts.

Details

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.

Payments

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.

Previews

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.

Attributes

idstring

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

statusstring

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.

currency_codestring

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

originstring

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 Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle 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.

collection_modestring

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.

payment_termsobject

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

intervalstring

Unit of time.

frequencyinteger

Amount of time.

enable_checkoutboolean

Whether the related transaction may be paid using a Paddle Checkout. If omitted when creating a transaction, defaults to false.

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.

billing_periodobject or null

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

ends_atstring<date-time>

RFC 3339 datetime string of when this period ends.

starts_atstring<date-time>

RFC 3339 datetime string of when this period starts.

itemsarray[object]

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

price_idstring

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

priceobject

Represents a price entity.

quantityinteger

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.

detailsobject

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

tax_rates_usedarray[object]

List of tax rates applied for this transaction.

totalsobject

Breakdown of the total for a transaction. These numbers can become negative when dealing with subscription updates that result in credit.

adjusted_totalsobject

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.

line_itemsarray[object]

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.

paymentsarray[object]

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

payment_attempt_idstring

UUID for this payment attempt.

stored_payment_method_idstring

UUID for the stored payment method used for this payment attempt. Deprecated - use payment_method_id instead.

payment_method_idstring or null

Paddle ID of the payment method used for this payment attempt, prefixed with paymtd_.

amountstring

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

statusstring

Status of this payment attempt.

error_codestring or null

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

method_detailsobject

Information about the payment method used for a payment attempt.

created_atstring<date-time>

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.

urlstring or null

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

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.

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

gethttps://api.paddle.com/transactions

Create a transaction

posthttps://api.paddle.com/transactions

Get a transaction

gethttps://api.paddle.com/transactions/{transaction_id}

Update a transaction

patchhttps://api.paddle.com/transactions/{transaction_id}

Preview a transaction

posthttps://api.paddle.com/transactions/preview

Get a PDF invoice for a transaction

gethttps://api.paddle.com/transactions/{transaction_id}/invoice