Create a transaction

To bill a customer, you need a transaction. It holds all the information about a charge you're billing for, including customer details, items, calculated tax and localized pricing, and payments.

Paddle automatically creates transactions for subscription lifecycle events and when checkouts are opened, but you can create your own transactions using the API or Dashboard. You might do this when:

• You have an interactive pricing page where customers can configure their subscription before signing up. You can create a transaction for the items a customer has chosen, then pass to a checkout.
• You create quotes or deals in a CRM or ERP solution and want to integrate with Paddle.

How it works

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

All revenue in Paddle is calculated and captured using transactions. Paddle creates transactions automatically for subscription lifecycle events and when checkouts are opened, and you may also create your own transactions using the API.

Transactions are initially created as draft or ready, depending on the information supplied. As you work with a transaction entity, they move to completed:

1. Draft

   draft transactions are missing required fields for billing. Checkouts opened by Paddle.js with only items create draft transactions, since they're missing customer and address information initially.

2. Ready

   Transactions are ready when they have all the required fields for billing. When Paddle Checkout captures customer name, country and (in some regions) ZIP or postal code, then transactions move to ready.

3. Billed

   You may optionally mark a transaction as billed. At this point, it's considered a financial record and can't be changed. This is typically used as part of an invoicing workflow to issue an invoice, or to prevent a customer from changing items or quantities at checkout.

4. Paid

   When Paddle collects payment successfully, transactions are automatically paid. This is an interim status while completed transaction processing happens. Paddle updates the transaction with information about fees, earnings, and totals for payouts. It also adds the related subscription_id and invoice_number for automatically-collected transactions.

5. Completed

   After all transaction processing is completed, transactions are automatically completed.

Completed transaction processing usually takes less than a second, so you won't typically encounter transactions that are paid when working with the API.

Paddle automatically sets transactions as draft, ready, paid, and completed. You can set transactions as billed or canceled using the API.

This guide focuses on creating automatically-collected transactions. You can also create manually-collected transactions, meaning Paddle sends your customer an invoice document that must be paid manually.

Before you begin

Transactions work with products and prices to say what you're billing for, so you'll need to create a product and a related price.

To create a ready transaction, you'll also need to:

• Create a customer and a related address
• Optionally create a related business

Create a draft transaction

Draft transactions contain an items list, but don't include address or customer details which are required for billing.

Send a POST request to the /transactions endpoint.

Request

Transactions work with price entities to say what you're billing for. Include a list of items, with an object containing price ID and quantity for each in your request.

1
2
3
4
5
6
7
8
1{
2  "items": [
3    {
4      "quantity": 10,
5      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
6    }
7  ]
8}

Response

If successful, Paddle responds with a copy of the new transaction entity with the status of draft.

The new transaction has collection_mode as automatic, which means Paddle collects automatically using a saved payment method. If no payment method is saved, customers must enter one using Paddle Checkout.

There are no calculated taxes, since Paddle doesn't have address information.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01h0qdpy7eme9e58rr7f9dwwy8",
4    "status": "draft",
5    "customer_id": null,
6    "address_id": null,
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "automatic",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "USD",
17    "discount_id": null,
18    "created_at": "2023-05-18T12:35:15.353193168Z",
19    "updated_at": "2023-05-18T12:35:15.353193168Z",
20    "billed_at": null,

Create a ready transaction

Ready transactions contain an items list and all required fields for billing, including address and customer details.

Send a POST request to the /transactions endpoint.

Along with items, you must include:

Request

Transactions work with price entities to say what you're billing for. Include a list of items, with an object containing price ID and quantity for each in your request.

In your request, include customer_id and address_id. You may optionally include a business_id, too.

1
2
3
4
5
6
7
8
9
10
1{
2  "items": [
3    {
4      "quantity": 10,
5      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
6    }
7  ],
8  "customer_id": "ctm_01gw1xk43eqy2rrf0cs93zvm6t",
9  "address_id": "add_01gwprnm56rxj8sbt0cb52972j"
10}

Response

If successful, Paddle responds with a copy of the new transaction entity with the status of ready.

The new transaction has collection_mode as automatic, which means Paddle collects automatically using a saved payment method. If no payment method is saved, customers must enter one using Paddle Checkout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01h0qhdz18x1gf06v9c0fgj2rx",
4    "status": "ready",
5    "customer_id": "ctm_01gw1xk43eqy2rrf0cs93zvm6t",
6    "address_id": "add_01gwprnm56rxj8sbt0cb52972j",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "automatic",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "USD",
17    "discount_id": null,
18    "created_at": "2023-05-18T13:40:15.984782889Z",
19    "updated_at": "2023-05-18T13:40:15.984782889Z",
20    "billed_at": null,

Update a transaction

While your transaction is draft or ready, you can make changes to it and the items on it. You can work with items, apply a discount, change customer information, or add or remove custom data.

If you're working with a draft transaction, when it includes items, customer_id, and address_id then Paddle automatically marks it as ready.

Send a PATCH request to the /transactions/{transaction_id} endpoint.

Request

This example adds a discount to a transaction. Apply a discount by including discount_id in your request.

1
2
3
1{
2  "discount_id": "dsc_01gy7qp5pqhnyd22yspwane77h"
3}

Response

If successful, Paddle responds with a copy of the updated transaction entity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01gzkcdstcwq4cj8waj812v9my",
4    "status": "ready",
5    "customer_id": "ctm_01gzgmxdmgkgc7p94b5kgqq82p",
6    "address_id": "add_01gzkce0amtjsqv8xxd1rv3dna",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "automatic",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "GBP",
17    "discount_id": "dsc_01gy7qp5pqhnyd22yspwane77h",
18    "created_at": "2023-05-04T12:40:07.834144Z",
19    "updated_at": "2023-05-18T13:59:56.611406607Z",
20    "billed_at": null,

Update transaction items

To update transaction items, include the items array in your request.

Change collection mode

While your transaction is draft or ready, you can switch between automatic and manual collection modes.

See: Change transaction collection mode

Mark a transaction as billed

You can mark a transaction as billed to say it's finalized, meaning it's considered a financial record and cannot be changed.

This is typically used for manually-collected transactions (invoices), as part of an invoicing workflow. Marking a transaction as billed is essentially issuing an invoice. It gets an invoice number and is sent to your customer.

You don't need to mark an automatically-collected transaction as billed, and it's not typically part of a self-service workflow. However, you may like to do this if you plan to create a checkout for this transaction to prevent a customer from changing items or quantities at checkout.

You can create a transaction and mark it as billed by including "status": "billed" in your initial request, along with the other required fields — no need to make a separate request.

Request

This example marks a transaction as billed.

1
2
3
1{
2  "status": "billed"
3}

Response

If successful, Paddle responds with a copy of the updated transaction entity with the status of billed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01gzkcdstcwq4cj8waj812v9my",
4    "status": "billed",
5    "customer_id": "ctm_01gzgmxdmgkgc7p94b5kgqq82p",
6    "address_id": "add_01gzkce0amtjsqv8xxd1rv3dna",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "api",
10    "collection_mode": "automatic",
11    "subscription_id": null,
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "GBP",
17    "discount_id": "dsc_01gy7qp5pqhnyd22yspwane77h",
18    "created_at": "2023-05-04T12:40:07.834144Z",
19    "updated_at": "2023-05-18T14:50:37.499310274Z",
20    "billed_at": "2023-05-18T14:50:37.499251541Z",

Pass a transaction to a checkout

Automatically-collected transactions include checkout.url, which you can send to customers to open a checkout to capture payment details for this transaction.

You can also pass a transaction ID to a checkout using Paddle.js to collect for it.

See: Pass a transaction to a checkout

Notifications

Related pages