For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

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.

AI summary

Change a transaction's collection mode between automatic (Paddle collects via saved payment method or checkout) and manual (Paddle sends an invoice the customer pays themselves).

  • • Automatically-collected transactions use Paddle Checkout to capture payment; manually-collected transactions generate invoices paid by bank transfer or via a checkout link.
  • • Only transactions in draft or ready status can have their collection mode changed — billed and completed transactions are financial records and cannot be modified.
  • • Changing collection mode from automatic to manual makes the transaction eligible to be issued as an invoice; changing from manual to automatic makes it eligible for checkout collection.

All purchases are transactions. They hold all the information about a customer purchase, 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

You can create two kinds of 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 that they can pay by bank 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.

Before you begin

To change collection mode for a transaction, you'll need to get the transaction ID for the transaction you want to change. You can only change collection mode for transactions that are draft or ready.

You can use the status query parameter when listing with the value draft,ready to get a list of draft and ready transactions.

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. To learn more, 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 the 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 to update the transaction.

In your request, set collection_mode to manual and include a billing_details object. Billing details must include payment_terms, but you may omit other fields. Optionally include enable_checkout (set to true to allow payment via Paddle Checkout; defaults to false), purchase_order_number, and additional_information.

This example changes the collection mode for an automatically-billed transaction to manual.

The billing_details.enable_checkout field is omitted, which means that this transaction can't be paid using Paddle Checkout. Only bank transfers are accepted.

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

PATCH /transactions/{transaction_id}
Request
{
  "collection_mode": "manual",
  "billing_details": {
    "payment_terms": {
      "interval": "day",
      "frequency": 30
    },
    "purchase_order_number": "PO-1030"
  }
}
Response (200 OK)
{
  "data": {
    "id": "txn_01h0j589qt1nee24210teqtz57",
    "status": "ready",
    "customer_id": "ctm_01gw1xk43eqy2rrf0cs93zvm6t",
    "address_id": "add_01gwprnm56rxj8sbt0cb52972j",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": "inv_01h140bf2esng25zn13h5k4phe",
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 30
      },
      "purchase_order_number": "PO-1030",
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2023-03-29T12:45:08.730136Z",
      "ends_at": "2024-03-29T12:45:08.730136Z"
    },
    "currency_code": "USD",
    "discount_id": "dsc_01gy7qp5pqhnyd22yspwane77h",
    "created_at": "2023-05-16T11:31:15.269265Z",
    "updated_at": "2023-05-23T13:19:12.359939154Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "description": "Annual (per seat) with 30 day trial",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": {
            "interval": "day",
            "frequency": 30
          },
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "31500",
            "currency_code": "GBP"
          },
          "unit_price_overrides": [],
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 20
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0",
          "totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          }
        }
      ],
      "totals": {
        "subtotal": "0",
        "tax": "0",
        "discount": "0",
        "total": "0",
        "fee": null,
        "credit": "0",
        "balance": "0",
        "earnings": null,
        "currency_code": "USD"
      },
      "payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01h0qjgk0t9jfdn8sqv47den3g",
          "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "quantity": 20,
          "totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://twemoji.maxcdn.com/v/latest/72x72/2708.png",
            "status": "active"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "440e3c36-b46b-400a-870c-40bb783702fa"
  }
}

This example changes the collection mode for an automatically-billed transaction to manual.

billing_details.enable_checkout is included and set to true, which means that you can pass this transaction to a checkout to collect for it.

If successful, Paddle responds with a copy of the updated transaction entity. checkout.url is included in the response, 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.

PATCH /transactions/{transaction_id}
Request
{
  "collection_mode": "manual",
  "billing_details": {
    "enable_checkout": true,
    "payment_terms": {
      "interval": "day",
      "frequency": 30
    },
    "purchase_order_number": "PO-1030"
  }
}
Response (200 OK)
{
  "data": {
    "id": "txn_01h0j589qt1nee24210teqtz57",
    "status": "ready",
    "customer_id": "ctm_01gw1xk43eqy2rrf0cs93zvm6t",
    "address_id": "add_01gwprnm56rxj8sbt0cb52972j",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": "inv_01h14c70rkdej2ce47evkphbya",
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": true,
      "payment_terms": {
        "interval": "day",
        "frequency": 30
      },
      "purchase_order_number": "PO-1030",
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2023-03-29T12:45:08.730136Z",
      "ends_at": "2024-03-29T12:45:08.730136Z"
    },
    "currency_code": "USD",
    "discount_id": "dsc_01gy7qp5pqhnyd22yspwane77h",
    "created_at": "2023-05-16T11:31:15.269265Z",
    "updated_at": "2023-05-23T13:23:55.652794642Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "description": "Annual (per seat) with 30 day trial",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": {
            "interval": "day",
            "frequency": 30
          },
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "31500",
            "currency_code": "GBP"
          },
          "unit_price_overrides": [],
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 20
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0",
          "totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          }
        }
      ],
      "totals": {
        "subtotal": "0",
        "tax": "0",
        "discount": "0",
        "total": "0",
        "fee": null,
        "credit": "0",
        "balance": "0",
        "earnings": null,
        "currency_code": "USD"
      },
      "payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01h0qjgk0t9jfdn8sqv47den3g",
          "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "quantity": 20,
          "totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://twemoji.maxcdn.com/v/latest/72x72/2708.png",
            "status": "active"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": "https://aeroedit.com/pay?_ptxn=txn_01h0j589qt1nee24210teqtz57"
    }
  },
  "meta": {
    "request_id": "c6ee1fa1-fb9b-418f-b727-ab445ce93d30"
  }
}

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 to update the transaction.

In your request, set collection_mode to automatic. Automatically-collected transactions don't need the billing_details object — Paddle automatically sets this to null when you change collection mode to automatic.

If successful, Paddle responds with a copy of the updated transaction entity. billing_details is automatically set to null.

PATCH /transactions/{transaction_id}
Request
{
  "collection_mode": "automatic"
}
Response (200 OK)
{
  "data": {
    "id": "txn_01h0j589qt1nee24210teqtz57",
    "status": "ready",
    "customer_id": "ctm_01gw1xk43eqy2rrf0cs93zvm6t",
    "address_id": "add_01gwprnm56rxj8sbt0cb52972j",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "automatic",
    "subscription_id": null,
    "invoice_id": "inv_01h14cfndr1pbkgbvc3bgz2gnn",
    "invoice_number": null,
    "billing_details": null,
    "billing_period": {
      "starts_at": "2023-03-29T12:45:08.730136Z",
      "ends_at": "2024-03-29T12:45:08.730136Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-05-16T11:31:15.269265Z",
    "updated_at": "2023-05-23T15:24:09.155895Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "description": "Annual (per seat) with 30 day trial",
          "type": "standard",
          "name": null,
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": {
            "interval": "day",
            "frequency": 30
          },
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "31500",
            "currency_code": "GBP"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 10,
            "maximum": 999
          },
          "status": "active"
        },
        "quantity": 20
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0",
          "totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          }
        }
      ],
      "totals": {
        "subtotal": "0",
        "tax": "0",
        "discount": "0",
        "total": "0",
        "grand_total": "0",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "0",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "0",
        "tax": "0",
        "total": "0",
        "grand_total": "0",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01h14kbshp9brrpybe0d9ckb2v",
          "price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "quantity": 20,
          "totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": {
              "features": {
                "crm": true,
                "data_retention": false,
                "reports": true
              },
              "suggested_addons": [
                "pro_01h1vjes1y163xfj1rh1tkfb65",
                "pro_01gsz97mq9pa4fkyy0wqenepkz"
              ],
              "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting."
            },
            "status": "active"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": "https://aeroedit.com/pay?_ptxn=txn_01h0j589qt1nee24210teqtz57"
    },
    "receipt_data": null
  },
  "meta": {
    "request_id": "5c389c18-1170-4f37-af8f-51704757a2f8"
  }
}

Events

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

Was this page helpful?