Overview

Create a new invoice for a customer. Invoices can be created manually for one-time charges or custom billing scenarios outside of the normal subscription cycle.

Example: Create a manual invoice for a customer who requested additional services not covered by their subscription.

Conditional Requirements

Taxes

A tax is a set of three fields: tax_name, tax_rate (percentage, 0–100) and tax_amount (minor units, e.g. cents). When tax_amount is sent it is stored exactly as provided instead of being calculated from the rate, which is useful when importing invoices from another system.

Multiple taxes. Add more taxes by repeating the set with a numeric suffix, _1 to _5, or the same number without the underscore:

• tax_name_1, tax_rate_1, tax_amount_1
• tax_name2, tax_rate2, tax_amount2

Each tax is attached to the same line item. The account's tax setting still applies: with exclusive tax the tax is added to the total, with inclusive tax the total is treated as already including it.

Several taxes on the subscription line

When subscription_id is provided without line_items, one line item is created from the subscription and every complete top-level tax set (name, rate and amount) is attached to it.

{
  "customer_id": 1234,
  "subscription_id": 5678,
  "currency": "cad",
  "total": 10000,
  "tax_name": "GST",   "tax_rate": 5,    "tax_amount": 500,
  "tax_name_1": "QST", "tax_rate_1": 10, "tax_amount_1": 1000,
  "tax_name2": "PST",  "tax_rate2": 7,   "tax_amount2": 700
}

Result: one line item, subtotal 10000, tax 2200, total 12200.

Several taxes per line item

Each entry in line_items can carry its own taxes. On a line item, tax_amount is optional; when omitted it is calculated from the rate.

{
  "customer_id": 1234,
  "currency": "cad",
  "line_items": [
    {
      "description": "Print subscription",
      "unit_price": 10000,
      "quantity": 1,
      "tax_name": "GST",   "tax_rate": 5,    "tax_amount": 500,
      "tax_name_1": "QST", "tax_rate_1": 10, "tax_amount_1": 1000
    },
    {
      "description": "Digital add-on",
      "unit_price": 4000,
      "quantity": 1,
      "tax_name_1": "GST", "tax_rate_1": 5, "tax_amount_1": 200
    }
  ]
}

Flat line item keys (CSV imports)

Line items can also be sent as flat keys named line_N_<field>, so one CSV row can describe a whole invoice. Each N becomes one line item, ordered by N, with all of its taxes. A group whose values are all empty is ignored, so a CSV can keep unused columns. Flat line items are added after any line_items in the same request.

line_1_description, line_1_unit_price, line_1_quantity,
line_1_tax_name, line_1_tax_rate, line_1_tax_amount,
line_1_tax_name_1, line_1_tax_rate_1, line_1_tax_amount_1,
line_2_description, line_2_unit_price, line_2_quantity

{
  "customer_id": 1234,
  "currency": "cad",
  "line_1_description": "Print subscription",
  "line_1_unit_price": 10000,
  "line_1_quantity": 1,
  "line_1_tax_name": "GST",
  "line_1_tax_rate": 5,
  "line_1_tax_amount": 500,
  "line_1_tax_name_1": "QST",
  "line_1_tax_rate_1": 10,
  "line_1_tax_amount_1": 1000,
  "line_2_description": "Digital add-on",
  "line_2_unit_price": 4000,
  "line_2_quantity": 1
}