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 bank or 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 the 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 the 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 the 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 bank or 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
Set your default payment link
Invoices work using manually-collected transactions. Transactions may include a link to pay using Paddle Checkout, so to create a transaction you'll need to:
- Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
- Get your default payment link domain approved, if you're working with the live environment.
We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go live.
Create customers
If you're working with the Paddle dashboard, 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
Create products and prices
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 to bill for an item in your catalog.
You can also add custom items to an invoice to bill for them. Custom items are one-off or bespoke items that are specific to that transaction. They're not part of your product catalog.
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 either:
An item from your catalog
Include a price ID and quantity for each item.
A custom item
Include a price object and quantity for each item.
Custom items are one-off or bespoke items that are specific to that transaction. For example, you may agree a custom price with an enterprise customer at renewal. See: Work with custom items
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 to charge for.
Quantity of this item on the transaction.
Paddle ID of an existing catalog price to add to this transaction, prefixed with pri_
.
List of items to charge for.
Price object for a non-catalog item to charge for. Include a product_id
to relate this non-catalog price to an existing catalog price.
Internal description for this price, not shown to customers. Typically notes for your team.
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
How often this price should be charged. null
if price is non-recurring (one-time).
Trial period for the product related to this price. The billing cycle begins once the trial period is over. null
for no trial period. Requires billing_cycle
.
How tax is calculated for this price.
Base price. This price applies to all customers, except for customers located in countries where you have unit_price_overrides
.
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
Your own structured key-value data.
Paddle ID for the product that this price is for, prefixed with pro_
.
Quantity of this item on the 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. If omitted when creating a transaction, defaults to false
.
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_01hgjw25swyhhdfr29aj43rx1w",
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": null,
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 the 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_01hgjw25swyhhdfr29aj43rx1w",
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_01hgjw26sp5exv8233w3stc3a1",
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",
Response
If successful, Paddle responds with a copy of the updated transaction entity.
232425262728293031323334353637383940414223 "billing_period": {
24 "starts_at": "2023-12-01T00:00:00Z",
25 "ends_at": "2024-11-30T23:59:00Z"
26 },
27 "currency_code": "USD",
28 "discount_id": null,
29 "created_at": "2023-12-01T14:21:01.127846Z",
30 "updated_at": "2023-12-01T14:48:50.514249112Z",
31 "billed_at": null,
32 "items": [
33 {
34 "price": {
35 "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
36 "description": "Annual (per seat)",
37 "name": null,
38 "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
39 "billing_cycle": {
40 "interval": "year",
41 "frequency": 1
42 },
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 the 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
.
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.
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. Automatically-collected transactions may return completed
if payment is captured successfully, or past_due
if payment failed.
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 the customer and any contacts against the related business
- Paddle creates a related subscription if there are recurring products on this invoice (
subscription_id
)
invoice_number
andsubscription_id
are added to a transaction asynchronously as part of completed transaction processing. They may not be returned in your request. Send a follow-up request to get the transaction, or listen for thetransaction.completed
webhook.
12345678910111213141516171819201{
2 "data": {
3 "id": "txn_01hgjw25swyhhdfr29aj43rx1w",
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_01hgjybs66bxwbzz6g1akb9b4n",
12 "invoice_id": "inv_01hgjw26sp5exv8233w3stc3a1",
13 "invoice_number": "325-10301",
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 for recurring items. This lets you provision your app for the 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.
Events
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.
Events
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. |