Invoicing
Discounts and shipping
Give a percentage or fixed discount on any line. The engine totals every discount on the document, and delivery charges are added as ordinary lines.
A discount lowers what the client pays for a line, either by a percentage or by a fixed amount. Discounts are part of the same totals engine as taxes and prices, so they are calculated exactly, in integer minor units, the same way in the web app, the API, MCP, the AI agent and the free generator.
Line discounts
Every line can carry one discount, set with two fields:
| Field | Values | Example |
|---|---|---|
discount_type | percent or amount | "percent" |
discount_value | the percentage, or the amount for the line | "10" |
- Percent takes that percentage off the line. A line of 500.00 with a 10% discount is reduced by 50.00.
- Amount takes a fixed sum off the line, in the document's currency.
Leave both fields empty for a line with no discount.
The document's discount total
The document shows the sum of its discounts as discount_minor, next to the subtotal, tax and total. The totals always follow one rule, tested on thousands of random documents: the total equals the sum of the line totals plus taxes minus discounts, after rounding, and rounding never creates or loses a minor unit.
Add a discount in the web app
Open the draft
Open the invoice, estimate or receipt in the editor.
Set the discount on a line
In the line's discount field, choose percent or amount and type the value.
Check the preview
The live PDF preview on the right shows the discount and the new totals before you save or send.
Discounts through the API and MCP
Send the discount on each line when you create or update a document:
{
"currency": "USD",
"lines": [
{
"description": "Annual maintenance",
"quantity": "1",
"unit_price_minor": "50000",
"discount_type": "percent",
"discount_value": "10"
},
{
"description": "Logo files",
"quantity": "1",
"unit_price_minor": "8000"
}
]
}The response includes discount_minor for the document and the computed subtotal_minor, tax_minor and total_minor for every line. Use Create an invoice or Update an invoice; over MCP, create_invoice, create_estimate and update_invoice accept the same fields.
Prices and totals are always strings of integer minor units, such as "50000" for 500.00 USD. The discount value is stored as a decimal number, because it can be a percentage. The Update an invoice reference shows the exact format for amount discounts.
Shipping and delivery charges
Documents have no separate shipping or delivery field. If you charge for delivery, postage of goods, or a similar fee, add it as an ordinary line, for example "Delivery" with a quantity of 1 and the price. As a line, it can carry its own tax rate and discount like any other charge, and it is copied into the snapshot when the document is sent.
To use the same delivery charge often, save it as a saved item and pick it from the editor.
When the Shopify app or WooCommerce plugin creates documents from store orders, the connector builds the lines from the order through the same API.
Rules and edge cases
- Discounts are frozen with the document. When a document is first sent, its lines, including their discounts, are stored in the snapshot. Changing a discount afterwards is a revision, and the earlier version stays readable.
- Credit notes, not negative discounts. To reduce what a client owes on an invoice that was already sent, issue a credit note rather than revising the price down. The credit note is a separate numbered record that both of you keep.
- Same maths everywhere. The PDF, the pay page, reports and the API all show amounts computed by the same engine, so totals never disagree between surfaces.
Permissions
| Action | Permission key |
|---|---|
| Set discounts on a draft | documents.create or documents.edit |
| Change discounts on a sent document (revision) | documents.edit |
Errors you may see
| Code | Meaning |
|---|---|
validation_failed | For example a discount_type other than percent or amount. |
document_not_editable | The document was sent; change it by revision or issue a credit note. |