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

Create and issue invoices

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.

AI summary

Create manually-collected transactions as draft invoices, iterate on them with customers, then issue them by setting status to billed — at which point Paddle assigns an invoice number, emails the customer, and creates a subscription.

  • • Set collection_mode: 'manual' to create an invoice — transactions are draft until they have items, customer_id, and address_id, then become ready.
  • • subscription_id and invoice_number may not appear in the initial response — listen for subscription.created to confirm the subscription was created.
  • • Invoices can be paid by bank transfer or via Paddle Checkout — pass billing_details when creating the transaction to set payment terms and purchase order numbers shown on the 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.

Illustration of an invoice from Paddle

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:

Draft your invoice

When you create an invoice (manually-collected transaction), it's initially 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.

Issue your invoice

Once 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 is assigned an invoice number and becomes a financial record. Paddle automatically sends a copy to the customer and creates a subscription for them. In Paddle, the status updates to billed.

Payment received

When the customer pays an invoice (manually-collected transaction), Paddle automatically handles reconciliation and marks the invoice as paid. The status in Paddle is now 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.

Before you begin

  • Set your default payment link
    Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link and get it approved.
  • 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.

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 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. Go to Paddle > Invoices.
  2. Click New invoice
  3. Choose or create a customer, business, and address for the customer.
  4. Choose whether to bill in USD, EUR, or GBP.
  5. Choose a product, related price, and quantity for your first item.
  6. Click the Add line item link to add items new items to the items list. Choose a product, related price, and quantity for each item.
  7. Click Save draft to save as a draft.

Send a POST request to the /transactions endpoint to create a manually-collected transaction.

Set collection_mode to manual to say this is an invoice, rather than a transaction for a checkout.

In your request, include:

  • items: an array of price IDs and quantities from your catalog, or custom items with inline price objects
  • billing_details: invoicing-specific fields like purchase order number and payment terms
  • customer_id and address_id: who the invoice is for; include business_id if billing a business

Transactions are automatically marked ready (eligible to issue) when they have customer_id, address_id, and items.

POST /transactions
Request
{
  "items": [
    {
      "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
      "quantity": 50
    },
    {
      "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
      "quantity": 1
    },
    {
      "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
      "quantity": 1
    }
  ],
  "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
  "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
  "collection_mode": "manual",
  "billing_details": {
    "enable_checkout": false,
    "payment_terms": {
      "interval": "day",
      "frequency": 14
    }
  }
}
Response (201 Created)
{
  "data": {
    "id": "txn_01hgjw25swyhhdfr29aj43rx1w",
    "status": "ready",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": null,
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": null,
      "additional_information": null
    },
    "billing_period": null,
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-12-01T14:21:01.127846913Z",
    "updated_at": "2023-12-01T14:21:01.127846913Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual (per seat)",
          "name": null,
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active"
        },
        "quantity": 50
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time charge",
          "name": "One-time charge",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["AU"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "AUD"
              }
            }
          ],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "description": "Annual (recurring addon)",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "100000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "2619900",
            "discount": "0",
            "tax": "232516",
            "total": "2852416"
          }
        }
      ],
      "totals": {
        "subtotal": "2619900",
        "tax": "232516",
        "discount": "0",
        "total": "2852416",
        "grand_total": "2852416",
        "fee": null,
        "credit": "0",
        "balance": "2852416",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "2619900",
        "tax": "232516",
        "total": "2852416",
        "grand_total": "2852416",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01hgjw269kayg28zp7gm15sfy6",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 50,
          "totals": {
            "subtotal": "2500000",
            "tax": "221875",
            "discount": "0",
            "total": "2721875"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "ChatApp Enterprise",
            "description": "The ultimate solution for businesses that require top-of-the-line features and customizations. Includes all the features of the Pro plan, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01hgjw269kayg28zp7gnjef73r",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make ChatApp truly your own with custom domains! Custom domains reinforce your brand identity and make it easy for your team to access ChatApp.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": {
              "crm_id": "ABC"
            },
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        },
        {
          "id": "txnitm_01hgjw269kayg28zp7gpndy87v",
          "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "quantity": 1,
          "totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "d57e8d4d-dc31-488e-b87f-a1993c9744a3"
  }
}

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. Go to Paddle > Invoices.
  2. Search for the invoice that you want to change.
  3. Click the next to an invoice in the list, then choose Edit invoice from the menu.
  4. Change customer details or items on your invoice.
  5. Click Save draft to save as a draft.

Send a PATCH request to the /transactions/{transaction_id} endpoint to update a manually-collected transaction.

Send the complete list of items you want on the invoice — including any existing items you want to keep. Omitting an item removes it. See work with lists.

PATCH /transactions/{transaction_id}
Request
{
  "billing_details": {
    "purchase_order_number": "PO-123"
  }
}
Response (200 OK)
{
  "data": {
    "id": "txn_01hgjw25swyhhdfr29aj43rx1w",
    "status": "ready",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": "inv_01hgjw26sp5exv8233w3stc3a1",
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": "PO-123",
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2023-12-01T00:00:00Z",
      "ends_at": "2024-11-30T23:59:00Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-12-01T14:21:01.127846Z",
    "updated_at": "2023-12-01T14:36:24.408358Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual (per seat)",
          "name": null,
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active"
        },
        "quantity": 50
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time charge",
          "name": "One-time charge",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["AU"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "AUD"
              }
            }
          ],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "description": "Annual (recurring addon)",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "100000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "2619900",
            "discount": "0",
            "tax": "232516",
            "total": "2852416"
          }
        }
      ],
      "totals": {
        "subtotal": "2619900",
        "tax": "232516",
        "discount": "0",
        "total": "2852416",
        "grand_total": "2852416",
        "fee": null,
        "credit": "0",
        "balance": "2852416",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "2619900",
        "tax": "232516",
        "total": "2852416",
        "grand_total": "2852416",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01hgjw269kayg28zp7gm15sfy6",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 50,
          "totals": {
            "subtotal": "2500000",
            "tax": "221875",
            "discount": "0",
            "total": "2721875"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "ChatApp Enterprise",
            "description": "The ultimate solution for businesses that require top-of-the-line features and customizations. Includes all the features of the Pro plan, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01hgjw269kayg28zp7gnjef73r",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make ChatApp truly your own with custom domains! Custom domains reinforce your brand identity and make it easy for your team to access ChatApp.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": {
              "crm_id": "ABC"
            },
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        },
        {
          "id": "txnitm_01hgjw269kayg28zp7gpndy87v",
          "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "quantity": 1,
          "totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "c9e31d4b-e776-4495-8535-3be1a836e6fe"
  }
}
PATCH /transactions/{transaction_id}
Request
{
  "items": [
    {
      "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
      "quantity": 50
    },
    {
      "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
      "quantity": 1
    },
    {
      "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
      "quantity": 1
    },
    {
      "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
      "quantity": 1
    }
  ]
}
Response (200 OK)
{
  "data": {
    "id": "txn_01hgjw25swyhhdfr29aj43rx1w",
    "status": "ready",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": null,
    "invoice_id": "inv_01hgjw26sp5exv8233w3stc3a1",
    "invoice_number": null,
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": null,
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2023-12-01T00:00:00Z",
      "ends_at": "2024-11-30T23:59:00Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-12-01T14:21:01.127846Z",
    "updated_at": "2023-12-01T14:48:50.514249112Z",
    "billed_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual (per seat)",
          "name": null,
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active"
        },
        "quantity": 50
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time charge",
          "name": "One-time charge",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["AU"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "AUD"
              }
            }
          ],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "description": "Annual (recurring addon)",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "100000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "description": "Annual (recurring addon)",
          "name": null,
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "300000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "2919900",
            "discount": "0",
            "tax": "259141",
            "total": "3179041"
          }
        }
      ],
      "totals": {
        "subtotal": "2919900",
        "tax": "259141",
        "discount": "0",
        "total": "3179041",
        "grand_total": "3179041",
        "fee": null,
        "credit": "0",
        "balance": "3179041",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "2919900",
        "tax": "259141",
        "total": "3179041",
        "grand_total": "3179041",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16r67pc60",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 50,
          "totals": {
            "subtotal": "2500000",
            "tax": "221875",
            "discount": "0",
            "total": "2721875"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "ChatApp Enterprise",
            "description": "The ultimate solution for businesses that require top-of-the-line features and customizations. Includes all the features of the Pro plan, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16thb9ahg",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make ChatApp truly your own with custom domains! Custom domains reinforce your brand identity and make it easy for your team to access ChatApp.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": {
              "crm_id": "ABC"
            },
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16ty9m70d",
          "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "quantity": 1,
          "totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k170m19nnv",
          "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "quantity": 1,
          "totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          },
          "product": {
            "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
            "name": "Reporting module",
            "description": "Get access to comprehensive reports and customizable analytics dashboards.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "6f0a5cd0-3b3f-4ca7-aaa2-d9cfc5f9ef2b"
  }
}

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.

  1. Go to Paddle > Invoices.
  2. Search for the invoice that you want to issue.
  3. Click the next to an invoice in the list, then choose Edit invoice from the menu.
  4. Click Continue
  5. Review the summary of your invoice.
  6. Click Send invoice to issue and send.

Send a PATCH request to the /transactions/{transaction_id} endpoint to update a manually-collected transaction, setting status to billed in your request.

The transaction must be ready. If successful,Paddle automatically assigns an invoice number and creates a related subscription.

PATCH /transactions/{transaction_id}
Request
{
  "status": "billed"
}
Response (200 OK)
{
  "data": {
    "id": "txn_01hgjw25swyhhdfr29aj43rx1w",
    "status": "billed",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "custom_data": null,
    "origin": "api",
    "collection_mode": "manual",
    "subscription_id": "sub_01hgjybs66bxwbzz6g1akb9b4n",
    "invoice_id": "inv_01hgjw26sp5exv8233w3stc3a1",
    "invoice_number": "325-10301",
    "billing_details": {
      "enable_checkout": false,
      "payment_terms": {
        "interval": "day",
        "frequency": 14
      },
      "purchase_order_number": null,
      "additional_information": null
    },
    "billing_period": {
      "starts_at": "2023-12-01T00:00:00Z",
      "ends_at": "2024-11-30T23:59:00Z"
    },
    "currency_code": "USD",
    "discount_id": null,
    "created_at": "2023-12-01T14:21:01.127846Z",
    "updated_at": "2023-12-01T15:01:16.161268Z",
    "billed_at": "2023-12-01T15:01:11.658471Z",
    "items": [
      {
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "description": "Annual (per seat)",
          "name": null,
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active"
        },
        "quantity": 50
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time charge",
          "name": "One-time charge",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [
            {
              "country_codes": ["AU"],
              "unit_price": {
                "amount": "40000",
                "currency_code": "AUD"
              }
            }
          ],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "description": "Annual (recurring addon)",
          "name": "Annual (recurring addon)",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "100000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      },
      {
        "price": {
          "id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "description": "Annual (recurring addon)",
          "name": null,
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "billing_cycle": {
            "interval": "year",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "300000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active"
        },
        "quantity": 1
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "2919900",
            "discount": "0",
            "tax": "259141",
            "total": "3179041"
          }
        }
      ],
      "totals": {
        "subtotal": "2919900",
        "tax": "259141",
        "discount": "0",
        "total": "3179041",
        "grand_total": "3179041",
        "fee": null,
        "credit": "0",
        "balance": "3179041",
        "earnings": null,
        "currency_code": "USD"
      },
      "adjusted_totals": {
        "subtotal": "2919900",
        "tax": "259141",
        "total": "3179041",
        "grand_total": "3179041",
        "fee": "0",
        "earnings": "0",
        "currency_code": "USD"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16r67pc60",
          "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "quantity": 50,
          "totals": {
            "subtotal": "2500000",
            "tax": "221875",
            "discount": "0",
            "total": "2721875"
          },
          "product": {
            "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
            "name": "ChatApp Enterprise",
            "description": "The ultimate solution for businesses that require top-of-the-line features and customizations. Includes all the features of the Pro plan, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "50000",
            "tax": "4437",
            "discount": "0",
            "total": "54437"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16thb9ahg",
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make ChatApp truly your own with custom domains! Custom domains reinforce your brand identity and make it easy for your team to access ChatApp.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": {
              "crm_id": "ABC"
            },
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "1766",
            "discount": "0",
            "total": "21666"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k16ty9m70d",
          "price_id": "pri_01h1vjg3sqjj1y9tvazkdqe5vt",
          "quantity": 1,
          "totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "100000",
            "tax": "8875",
            "discount": "0",
            "total": "108875"
          }
        },
        {
          "id": "txnitm_01hgjxn4j5mkbmn8k170m19nnv",
          "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg",
          "quantity": 1,
          "totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          },
          "product": {
            "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
            "name": "Reporting module",
            "description": "Get access to comprehensive reports and customizable analytics dashboards.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "custom_data": null,
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "300000",
            "tax": "26625",
            "discount": "0",
            "total": "326625"
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": null
    }
  },
  "meta": {
    "request_id": "40beae18-b4ef-488c-8332-16bf3d5d5a9c"
  }
}

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.

Using webhooks

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

Using the 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

transaction.created Occurs when a transaction is created.
transaction.updated Occurs when a transaction is updated.
transaction.ready Occurs when a transaction is ready to be billed. Its status field changes to ready.
transaction.billed Occurs when a transaction is billed. Its status field changes to billed and billed_at is populated.
subscription.created Occurs when a subscription is created.
subscription.activated Occurs when a subscription becomes active.

Was this page helpful?