Create and issue an invoice

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. The payment method used is stored internally for renewals and other subscription-related charges; it's only saved as a saved payment method if the customer opts in.

Invoices work using manually-collected transactions. This means that Paddle sends an invoice that customers must pay themselves by bank 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:

1. 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 or ready. They're ready when they have all the required fields to be issued.

2. 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 the customer and creates a subscription for them. In Paddle, it has the status of billed.

3. 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 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:

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

Create products and prices

Transactions work with products and prices to say what a customer is purchasing, 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
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,

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_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.

1
2
3
4
5
1{
2  "billing_details": {
3    "purchase_order_number": "PO-123"
4  }
5}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
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}

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_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",

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
23    "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.

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

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_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 bank transfer.

Events

• subscription.created

  If you've subscribed to a webhook for subscription.created, you'll get a notification that includes the id of the new subscription. Use the transaction_id against the subscription.created notification to match to the correct transaction.

• transaction.updated

  After subscription.created occurs, Paddle updates the transaction with the created subscription_id and transaction.updated occurs. Use subscription_id against the transaction.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.

1. Send a GET request to the /transactions/{transaction_id} endpoint, using the transaction_id of the manually-collected transaction you marked as billed.

2. Extract the subscription_id from the response.

3. Send a GET request to the /subscriptions/{subscription_id} endpoint, using the subscription_id you just extracted.

Events

Related pages