Change collection mode for a transaction

Change collection mode to determine whether Paddle tries to collect payment for a transaction automatically using a saved payment method or sends an invoice that must be paid manually.

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.

Change collection mode for a transaction to determine whether Paddle tries to collect automatically using a saved payment method, or sends an invoice to a customer that they must pay manually.

How it works

There are two kinds of collection mode for transactions:

Automatically-collected transactions
Paddle collects using a saved payment method. If no payment method is saved, customers must enter one using Paddle Checkout. Typically part of a self-service workflow.
Manually-collected transactions
Paddle collects by sending an invoice that the customer must pay by bank transfer or using Paddle Checkout. Typically part of a sales-assisted invoicing workflow.

Before a transaction is billed, you can switch between automatic and manual collection modes. This means that you can do things like:

Move higher-dollar deals to manually-collected, sending invoices to customers and accepting payment by bank or wire transfer.
Automatically collect for smaller amounts for sales-assisted customers, like changes to seats or addons mid-billing cycle.

You can change a transaction collection mode for draft and ready transactions.

Subscriptions also have a collection_mode field. Change the collection mode against a subscription to determine the collection mode for transactions created from that subscription.

Before you begin

To change collection mode for a transaction, you'll need to get an existing transaction that's draft or ready.

You can't change collection mode for a transaction that's billed or completed:

Billed transactions have been marked as finalized, so they're considered financial records. Cancel a billed transaction to say that it's no longer needed, then create another.
Completed transactions have payments against them, so there's no need to change their collection mode.

If you've not yet created a transaction, you can set a collection mode when creating a transaction. See:

Change from automatic to manual

Change an automatically-collected transaction to a manually-collected transaction when you want to send an invoice to customers. Collection for payment happens manually, which means customers must pay by bank transfer or Paddle Checkout. Paddle doesn't automatically collect for the balance.

You'll need to mark your transaction as billed to issue your invoice. Paddle assigns an invoice number and sends an invoice document.

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

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

transaction_idstring

Paddle ID of the transaction entity to work with.

Find transaction ID

Manually-collected transactions require the billing_details object, which is where you can set information like payment terms and purchase order number.

billing_detailsobject

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

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.

Change collection mode to manual, payment by bank transfer only

Change collection mode to manual, payment by bank transfer or Paddle Checkout

Change from manual to automatic

Change a manually-collected transaction to an automatically-collected transaction when you want to collect using a saved payment method. If no payment method is saved, customers must enter one using Paddle Checkout.

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

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

transaction_idstring

Paddle ID of the transaction entity to work with.

Automatically-collected transactions don't need the billing_details object. Paddle automatically nulls this when you change collection mode to automatic.

Request

This example changes the collection mode for a manually-billed transaction to automatic.

PATCH https://api.paddle.com/transactions/txn_01h0j589qt1nee24210teqtz57

1
2
3
1{
2  "collection_mode": "automatic"
3}

Response

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

billing_details is automatically set to null.

200 OK

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_01h0j589qt1nee24210teqtz57",
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": "inv_01h14cfndr1pbkgbvc3bgz2gnn",
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": {
16      "starts_at": "2023-03-29T12:45:08.730136Z",
17      "ends_at": "2024-03-29T12:45:08.730136Z"
18    },
19    "currency_code": "USD",
20    "discount_id": null,

Events

`transaction.updated`	Occurs when the collection mode for a transaction is updated.

Create a transaction

Create and issue an invoice (a manually-collected transaction)

Pass a transaction to a checkout

Sign up to get notified when our API evolves