Create and issue an invoice
Create invoices as part of a sales-assisted billing process using manually-collected transactions. Paddle automatically creates a subscription for you once an invoice is issued.
Invoices let you offer sales-assisted billing. Your sales team can draft and send invoices for subscriptions, collecting payment manually rather than by charging a card on file.
They're generally used for bigger-dollar deals, like enterprise plans, and might include one-time or recurring fees for things like implementation or support.

How it works
When customers sign up and pay for a subscription using Paddle Checkout, Paddle collects using an automatically-collected transaction and creates a subscription where the collection mode is automatic. This means that Paddle saves the payment method used and uses it to collect for future renewals and charges.
Invoices work using manually-collected transactions. This means that Paddle sends an invoice that customers must pay themselves by wire transfer or using Paddle Checkout. Paddle creates a subscription when an invoice is issued, and future renewals and charges send new invoices that the customer must pay manually.
Invoice lifecycle
Transaction statuses mirror the invoice lifecycle:
Draft your invoice
When you create an invoice (manually-collected transaction) initially, it's a draft. You can work through changes with your customer, adding or removing items as you scope out their requirements. Draft invoices may have the status
draft
orready
. They'reready
when they have all the required fields to be issued.Issue your invoice
When you and your customer are happy with an invoice (manually-collected transaction), you can issue it by marking the transaction as billed. At this point, it's issued an invoice number and becomes a financial record. Paddle automatically sends a copy to your customer and creates a subscription for them. In Paddle, it has the status of
billed
.Payment received
When a customer pays an invoice (manually-collected transaction), Paddle automatically handles reconciliation and marks the invoice as paid. In Paddle, its status is
completed
.
Payments, including failed payment attempts, are logged against a transaction. Customers can pay invoices by wire transfer, or you can turn Paddle Checkout for an invoice to let customers pay using card, digital wallet, or a local payment method. This is especially handy for lower-value changes, like adding users or modules mid-cycle.
This guide focuses on creating manually-collected transactions. You can also create automatically-collected transactions, then pass them to Paddle.js to open a checkout for the items on them.
Before you begin
If you're working with the Paddle web app, you can create all the entities that you'll be working with as you create your invoice (manually-collected transaction).
If you're working with the API, you'll need to:
- Optionally create a related business for your customer
Transactions work with products and prices to say what you're billing for, so you'll also need to create a product and a related price.
Create a draft invoice
To create an invoice, create a transaction with the collection_mode
set to manual
.
Manually-collected transactions have the status of either draft
or ready
when you first create them. They're draft draft
while they're missing items
, customer_id
, and address_id
, and they automatically change to ready
when you add those fields.
Create an invoice using the API in two steps:
Build a request with information about who your invoice is for and what you're billing for.
Send the request to create your invoice. Paddle creates it. Its status is
draft
orready
depending on the information you supplied.
Build request
Build an array of items
, with an object containing price ID and quantity for each item.
API
List prices by making a GET request to the /prices
endpoint. Work your way through the results to find the price that you'd like to work with.
Dashboard
Head to Paddle > Catalog > Products, click on a product in the list, then click the … menu next to a price and choose Copy ID.
Recurring items on a transaction must have the same billing interval. For example, you can't have a transaction with some prices that are billed monthly and some products that are billed annually.
List of items on this invoice.
Paddle ID for the price to add to this transaction, prefixed with pri_
.
Quantity of this item to add to this transaction.
Set collection_mode
to manual
and include a billing_details
object with invoicing-related information, like purchase order number and payment terms.
If collection_mode
is omitted, Paddle creates an automatically-collected transaction.
How payment is collected. automatic
for checkout, manual
for invoices.
Details for invoicing. Required if collection_mode
is manual
.
Whether the related transaction may be paid using a Paddle Checkout.
Customer purchase order number. Appears on invoice documents.
Notes or other information to include on this invoice. Appears on invoice documents.
How long a customer has to pay this invoice once issued.
Include customer_id
and address_id
to say who this invoice is for.
If you're working with a business, include business_id
too.
Transactions are automatically marked as ready
when they have customer_id
, address_id
, and items
. This means that they're ready to be issued (marked as billed
).
Paddle ID of the customer that this invoice is for, prefixed with ctm_
.
Paddle ID of the address that this invoice is for, prefixed with add_
.
Paddle ID of the business that this invoice is for, prefixed with biz_
.
Request
This example creates a draft invoice for a 50-user enterprise plan with two additional products. It includes a customer and an address.
12345678910111213141516171819201{
2 "items": [
3 {
4 "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
5 "quantity": 50
6 },
7 {
8 "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
9 "quantity": 1
10 },
11 {
12 "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
13 "quantity": 1
14 }
15 ],
16 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
17 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
18 "collection_mode": "manual",
19 "billing_details": {
20 "enable_checkout": false,
Send request
Send a POST
request to the /transactions
endpoint with the request you built.
Response
If successful, Paddle responds with a copy of the new transaction entity.
The created invoice is ready
, since it includes all the required fields for it to be issued.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01h43ccb67vv5qp8gnstsbxxth",
4 "status": "ready",
5 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7 "business_id": null,
8 "custom_data": null,
9 "origin": "api",
10 "collection_mode": "manual",
11 "subscription_id": null,
12 "invoice_id": "inv_01h45nxb21zmsp9ebmbae9ncw8",
13 "invoice_number": null,
14 "billing_details": {
15 "enable_checkout": false,
16 "payment_terms": {
17 "interval": "day",
18 "frequency": 14
19 },
20 "purchase_order_number": null,
Update a draft invoice
While transactions are draft
or ready
, they don't have invoice numbers and aren't considered financial records yet. This means that you can make changes to the transaction and its items.
Update an invoice using the API in two steps:
Build a request with information about who your invoice is for and what you're billing for. If you're adding new items, your request should include any existing items that you'd like to keep.
Send the request to update your invoice. Paddle updates it.
Build request
Build a request with any data that you'd like to change. You can change any writeable fields at this point, including address, customer, and items. It's common to make changes to items as you work with your customer.
When working with items
, you should send the complete list of items that you'd like to be against your invoice — including any existing items. If you omit an item, it's removed from the items list. See: Work with lists
Request
This example changes the purchase order number against a transaction.
123451{
2 "billing_details": {
3 "purchase_order_number": "PO-123"
4 }
5}
This example updates items on a draft invoice.
12345678910111213141516171819201{
2 "items": [
3 {
4 "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
5 "quantity": 50
6 },
7 {
8 "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
9 "quantity": 1
10 },
11 {
12 "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
13 "quantity": 1
14 },
15 {
16 "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
17 "quantity": 1
18 }
19 ]
20}
Update invoice
Send a PATCH
request to the /transactions/{transaction_id}
endpoint with the request you built.
Paddle ID of the transaction entity to work with.
Response
If successful, Paddle responds with a copy of the updated transaction entity.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01h43ccb67vv5qp8gnstsbxxth",
4 "status": "ready",
5 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7 "business_id": null,
8 "custom_data": null,
9 "origin": "api",
10 "collection_mode": "manual",
11 "subscription_id": null,
12 "invoice_id": "inv_01h45nxb21zmsp9ebmbae9ncw8",
13 "invoice_number": null,
14 "billing_details": {
15 "enable_checkout": false,
16 "payment_terms": {
17 "interval": "day",
18 "frequency": 14
19 },
20 "purchase_order_number": "PO-123",
If successful, Paddle responds with a copy of the updated transaction entity.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01h43ccb67vv5qp8gnstsbxxth",
4 "status": "ready",
5 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7 "business_id": null,
8 "custom_data": null,
9 "origin": "api",
10 "collection_mode": "manual",
11 "subscription_id": null,
12 "invoice_id": "inv_01h4dbhkd8hfyvajat69y1t07f",
13 "invoice_number": null,
14 "billing_details": {
15 "enable_checkout": false,
16 "payment_terms": {
17 "interval": "day",
18 "frequency": 14
19 },
20 "purchase_order_number": null,
Issue an invoice
When you're happy with an invoice, issue it to mark it as finalized. At this point, it becomes a financial record so you can't make changes to it. It gets an invoice number and is sent to your customer.
You can create a transaction and mark it as
billed
by including"status": "billed"
in your request to create or update, along with the other required fields — no need to make a separate request.
Issue an invoice using the API in two steps:
Build a request that sets
status
tobilled
. Transaction must beready
.Send the request to issue your invoice. Its status changes to
billed
.
Build request
To issue an invoice, change the status of a manually-collected transaction to billed
.
Paddle automatically assigns an invoice number and creates a related subscription when you send your request.
Status of this transaction. You may set a transaction to billed
or canceled
, other statuses are set automatically by Paddle.
Request
This examples issues an invoice by changing the status
to billed
.
1231{
2 "status": "billed"
3}
Issue your invoice
Send a PATCH
request to the /transactions/{transaction_id}
endpoint with the request you built.
Paddle ID of the transaction entity to work with.
Response
If successful, Paddle responds with a copy of the updated transaction entity with the status of billed
.
At this point:
- Paddle issues it an invoice number (
invoice_number
) - A copy is sent to your customer and any contacts against the related business
- Paddle creates a related subscription if there are recurring products on this invoice (
subscription_id
)
Transactions are financial records. You can't edit them if they're billed, canceled, or completed. Cancel a transaction and create another or create an adjustment if you need to make changes to a billed or completed transaction.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01h43ccb67vv5qp8gnstsbxxth",
4 "status": "billed",
5 "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
6 "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
7 "business_id": null,
8 "custom_data": null,
9 "origin": "api",
10 "collection_mode": "manual",
11 "subscription_id": "sub_01h4dnwf7c6ne77cstxg8yggcw",
12 "invoice_id": "inv_01h4dnwf8wyte66em6hwcp3c11",
13 "invoice_number": "325-10083",
14 "billing_details": {
15 "enable_checkout": false,
16 "payment_terms": {
17 "interval": "day",
18 "frequency": 14
19 },
20 "purchase_order_number": null,
Get created subscription
Paddle automatically creates a subscription when you issue an invoice. This lets you provision access to your app for your customer right away, rather than waiting for payment to complete. This is especially important when working with high-value invoices where payment is by wire transfer.
Notifications
subscription.created
If you've subscribed to a webhook for
subscription.created
, you'll get a notification that includes theid
of the new subscription. Use thetransaction_id
against thesubscription.created
notification to match to the correct transaction.transaction.updated
After
subscription.created
occurs, Paddle updates the transaction with the createdsubscription_id
andtransaction.updated
occurs. Usesubscription_id
against thetransaction.updated
notification to get the related subscription.
API
Use the subscription_id
against the transaction you just marked as billed to find the new subscription. Subscriptions are created asynchronously after a transaction is billed, so this may not be present in the initial response.
Send a
GET
request to the/transactions/{transaction_id}
endpoint, using thetransaction_id
of the manually-collected transaction you marked asbilled
.Extract the
subscription_id
from the response.Send a
GET
request to the/subscriptions/{subscription_id}
endpoint, using thesubscription_id
you just extracted.
Notifications
transaction.created | Occurs when a transaction is first created. |
transaction.updated | Occurs when a transaction is updated. This includes updates made by you, as well as system updates by Paddle. |
transaction.ready | Occurs when a transaction has all of the required fields to be marked as billed . |
transaction.billed | Occurs when a transaction is billed (invoice issued). Paddle issues an invoice number and it's considered final. |
subscription.created | Occurs when a subscription is created as a result of a transaction being billed. |
subscription.activated | Occurs when a subscription is activated as a result of a transaction being billed. This means any trial period has elapsed. |