Create a transaction

posthttps://api.paddle.com/transactions

Creates a new transaction.

Transactions are typically created with the status of draft or ready initially:

Draft transactions have items against them, but don't have all of the required fields for billing. Paddle creates draft transactions automatically when a checkout is opened.
Paddle automatically marks transactions as ready when all of the required fields are present for billing. This includes customer_id and address_id for automatically-collected transactions, and billing_details for manually-collected transactions.

The collection_mode against a transaction determines how Paddle tries to collect for payment:

Manually-collected transactions are for sales-assisted billing. Paddle sends an invoice to your customer when a transaction is billed. Payment is often by wire transfer.
Automatically-collected transactions are for self-serve checkouts. You may pass the transaction to a checkout or use the returned checkout.url to collect for payment.

When a manually-collected transaction is marked as billed or an automatically-collected transaction is completed, Paddle automatically creates a related subscription for the items on the transaction.

If successful, your response includes a copy of the new transaction entity.

Use the include parameter to include related entities in the response.

Query Parameters

includearray[string]

Include related entities in the response. Use a comma-separated list to specify multiple entities.

Request Body

itemsarray[object]required

Add a non-catalog price for a non-catalog product in your catalog to a transaction. In this case, the product and price that you're billing for are specific to this transaction.

One of:

Catalog itemNon-catalog price for an existing productNon-catalog price and product

price_idstringrequired

Paddle ID of an existing catalog price to add to this transaction, prefixed with pri_.

quantityintegerrequired

Quantity of this item on the transaction.

statusstring

Status of this transaction. You may set a transaction to billed when creating, or omit to let Paddle set the status. Transactions are created as ready if they have an address_id, customer_id, and items, otherwise they are created as draft.

Marking as billed when creating is typically used when working with manually-collected transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled.

customer_idstring or null

Paddle ID of the customer that this transaction is for, prefixed with ctm_. If omitted, transaction status is draft.

address_idstring or null

Paddle ID of the address that this transaction is for, prefixed with add_. Requires customer_id. If omitted, transaction status is draft.

business_idstring or null

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

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.

collection_modestring

How payment is collected for this transaction. automatic for checkout, manual for invoices. If omitted, defaults to automatic.

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_termsobjectrequired

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

intervalstringrequired

Unit of time.

frequencyintegerrequired

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

RFC 3339 datetime string of when this period ends.

starts_atstring<date-time>required

RFC 3339 datetime string of when this period starts.

checkoutobject or null

Paddle Checkout details for this transaction. You may pass a URL when creating or updating an automatically-collected transaction, or when creating or updating a manually-collected transaction where billing_details.enable_checkout is true.

urlstring or null

Checkout URL to use for the payment link for this transaction. Pass the URL for an approved domain, or omit to use your default payment URL.

Paddle returns a unique payment link composed of the URL passed or your default payment URL + _?txn= and the Paddle ID for this transaction.

Response

dataobject

Represents a transaction entity with included entities.

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.

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.

itemsarray[object]

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

detailsobject

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

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.

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.

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.

addressobject

Address for this transaction. Returned when the include parameter is used with the address value and the transaction has an address_id.

adjustmentsarray[object]

Represents an adjustment entity.

adjustments_totalsobject

Object containing totals for all adjustments on a transaction. Returned when the include parameter is used with the adjustments_totals value.

businessobject

Business for this transaction. Returned when the include parameter is used with the business value and the transaction has a business_id.

customerobject

Customer for this transaction. Returned when the include parameter is used with the customer value and the transaction has a customer_id.

discountobject

Discount for this transaction. Returned when the include parameter is used with the discount value and the transaction has a discount_id.

available_payment_methodsarray[string]

List of available payment methods for this transaction. Returned when the include parameter is used with the available_payment_methods value.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "items": [
3    {
4      "quantity": 20,
5      "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea"
6    },
7    {
8      "quantity": 1,
9      "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg"
10    },
11    {
12      "quantity": 1,
13      "price_id": "pri_01gsz98e27ak2tyhexptwc58yk"
14    }
15  ],
16  "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
17  "address_id": "add_01hv8gq3318ktkfengj2r75gfx",
18  "currency_code": "USD",
19  "collection_mode": "manual",
20  "billing_details": {

Response