Documents
Create an invoice
POST/v1/documents
Creates a draft invoice with lines, taxes and discounts. Send type: "invoice".
Invoices, estimates and receipts are all created with POST /v1/documents; the type field picks the kind. The invoice is created as a draft with no number. Totals are computed on the server in integer minor units: line amounts, discounts, exclusive, inclusive and compound taxes, and the grand total. When the currency differs from the business base currency, the exchange rate is frozen on the document.
Nothing is sent to the client. Integrations, MCP clients and the AI agent always create drafts; you send with Send a document, which also gives the invoice its number. Lines can be filled from saved items; each line keeps a copy of the values.
See Invoices and Line items.
Idempotency-Keyis required for API-key and MCP calls, so a retry never creates two invoices.- Floating-point amounts are rejected; send minor units as strings.
- Permission
documents.create- Type
- Write. Creates or changes data and writes an audit entry.
- Auth
- API key, MCP token or signed-in session
- Capability
create_invoice- MCP tool
- create_invoice
- CLI
freeinvoiceautomation invoice create- Available
- At launch, 1 January 2027
create_invoice
curl --request POST \
--url https://api.freeinvoiceautomation.com/v1/documents \
--header 'Authorization: Bearer <api-key>' \
--header 'Idempotency-Key: <unique-key>' \
--header 'Content-Type: application/json' \
--data '{
"type": "invoice",
"client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
"currency": "USD",
"issue_date": "2027-02-01",
"due_date": "2027-02-15",
"lines": [
{
"item_id": "0193f2a1-7c4e-7b9a-9f10-3c2d1e0a4b51",
"description": "Logo design",
"quantity": "1",
"unit": "piece",
"unit_price_minor": "45000"
},
{
"description": "Brand guidelines, 12 pages",
"quantity": "1",
"unit_price_minor": "75000"
}
],
"terms": "Payment due within 14 days.",
"notes": "Thank you for your business."
}'{
"data": {
"id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
"business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
"client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
"type": "invoice",
"status": "draft",
"number": null,
"issue_date": "2027-02-01",
"due_date": "2027-02-15",
"expires_at": null,
"currency": "USD",
"fx_rate": "0.7900000000",
"fx_rate_source": "ecb:2027-02-01",
"subtotal_minor": "120000",
"discount_minor": "0",
"tax_minor": "0",
"total_minor": "120000",
"amount_paid_minor": "0",
"amount_credited_minor": "0",
"balance_minor": "120000",
"terms": "Payment due within 14 days.",
"notes": "Thank you for your business.",
"accepted_methods": [
"0193f29f-55aa-7b66-8c77-9d88e99f0a01",
"0193f29f-55aa-7b66-8c77-9d88e99f0a02"
],
"pdf_template_id": null,
"late_fees_enabled": false,
"reminder_sequence_id": null,
"promise_to_pay_date": null,
"recurring_schedule_id": null,
"current_version": 0,
"first_sent_at": null,
"last_sent_at": null,
"accepted_at": null,
"paid_at": null,
"overdue_at": null,
"voided_at": null,
"voided_by": null,
"void_reason": null,
"source": "api",
"external_ref": null,
"client_generated_id": null,
"lines": [
{
"id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e01",
"position": 1,
"kind": "item",
"item_id": "0193f2a1-7c4e-7b9a-9f10-3c2d1e0a4b51",
"description": "Logo design",
"quantity": "1",
"unit": "piece",
"unit_price_minor": "45000",
"discount_type": null,
"discount_value": null,
"tax_rate_id": null,
"tax_name": null,
"tax_rate": null,
"tax_calculation": null,
"subtotal_minor": "45000",
"tax_minor": "0",
"total_minor": "45000",
"credited_line_id": null
},
{
"id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e02",
"position": 2,
"kind": "item",
"item_id": null,
"description": "Brand guidelines, 12 pages",
"quantity": "1",
"unit": null,
"unit_price_minor": "75000",
"discount_type": null,
"discount_value": null,
"tax_rate_id": null,
"tax_name": null,
"tax_rate": null,
"tax_calculation": null,
"subtotal_minor": "75000",
"tax_minor": "0",
"total_minor": "75000",
"credited_line_id": null
}
],
"links": [],
"pay_url": null,
"created_at": "2027-02-01T09:12:44Z",
"updated_at": "2027-02-01T09:12:44Z"
}
}Authorizations
Authorizationstringrequired
Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.Headers
Idempotency-Keystringrequired
Required for API-key and MCP calls on create calls. Any unique string up to 255 characters; a retry with the same key returns the first response. See Idempotency.
Body
application/jsontypeenum<string>required
Document type. Send
invoice for this capability.Available options: invoice, estimate, receipt
business_idstring<uuid>
Issuing business. May be left out when you can reach exactly one business.
client_idstring<uuid>required
Client of the same business. Its defaults (currency, language, terms) fill the document unless you send them.
currencystring
ISO 4217 code. Defaults to the client's default currency, then the business base currency. When it differs from the base currency, the exchange rate is frozen on the document.
issue_datestring<date>
Issue date,
YYYY-MM-DD.due_datestring<date>
Due date. Defaults from the payment terms setting of the client or business.
linesobject[]required
At least one line. Totals are computed by the server in integer minor units.
termsstring
Payment terms printed on the document.
notesstring
Notes printed on the document.
accepted_methodsstring<uuid>[]
Payment connections offered on the pay page. Defaults to every enabled payment method of the business that fits the document.
pdf_template_idstring<uuid>
PDF template to use instead of the default.
external_refstring
Your own reference, e.g. a store order id. A second create with the same reference and source is refused, so connectors never create duplicates.
client_generated_idstring<uuid>
Id from the free generator, so a document synced on sign-up is created only once.
Response
201 - application/jsonidstring<uuid>
Unique id of the document (uuid v7).
business_idstring<uuid>
The issuing business.
client_idstring<uuid>
The client the document is for.
typeenum<string>
Document type.
Available options: invoice, estimate, credit_note, receipt
statusenum<string>
Current status. Invoices:
draft, sent, partially_paid, paid, overdue, void. Estimates: draft, sent, changes_requested, accepted, expired, converted, void. Credit notes: draft, issued, applied, refunded. Receipts: issued, void. See Document statuses.Available options: draft, sent, partially_paid, paid, overdue, void, changes_requested, accepted, expired, converted, issued, applied, refunded
numberstring | null
Human number such as
INV-2027-0017. null until the document is first sent.issue_datestring<date> | null
Issue date,
YYYY-MM-DD.due_datestring<date> | null
Due date for invoices.
expires_atstring<date> | null
Expiry date for estimates.
currencystring
ISO 4217 code of every amount on the document.
fx_ratestring | null
Exchange rate to the business base currency, frozen on the document when its currency differs.
fx_rate_sourcestring | null
Where the frozen rate came from and its date.
subtotal_minorstring
Sum of line amounts before tax.
discount_minorstring
Total discount.
tax_minorstring
Total tax.
total_minorstring
Grand total.
amount_paid_minorstring
Payments received so far.
amount_credited_minorstring
Credit notes and client credit applied.
balance_minorstring
What is still owed: total minus paid minus credited.
termsstring | null
Payment terms printed on the document.
notesstring | null
Notes printed on the document.
accepted_methodsstring<uuid>[] | null
Payment connections offered on this document's pay page.
pdf_template_idstring<uuid> | null
PDF template used to render the document.
late_fees_enabledboolean
Late fees on or off for this invoice (January 2027). Off by default.
reminder_sequence_idstring<uuid> | null
Reminder sequence override for this document (January 2027).
promise_to_pay_datestring<date> | null
Date the client promised to pay; stops reminders (January 2027).
recurring_schedule_idstring<uuid> | null
Recurring schedule that created the document (January 2027).
current_versioninteger
0 for a draft, 1 after the first send, then one more for each revision.first_sent_atstring<date-time> | null
When the document was first sent.
last_sent_atstring<date-time> | null
When the document was last sent.
accepted_atstring<date-time> | null
When the client accepted the estimate.
paid_atstring<date-time> | null
When the invoice became fully paid.
overdue_atstring<date-time> | null
When the invoice was marked overdue.
voided_atstring<date-time> | null
When the document was voided.
voided_bystring<uuid> | null
Who voided it.
void_reasonstring | null
Reason given when voiding.
sourceenum<string>
Where the document was created.
Available options: app, api, mcp, cli, agent, shopify, woocommerce, generator_sync, recurring
external_refstring | null
Your own reference, e.g. a store order id. Unique per business and source, so a connector cannot create the same document twice.
client_generated_idstring<uuid> | null
Id given by the free generator for documents synced on sign-up.
linesobject[]
The document lines, in order.
linksobject[]
Linked documents: credit notes, source estimate, contract.
pay_urlstring | null
Pay page link, present when an active share link exists.
created_atstring<date-time>
When the document was created (RFC 3339, UTC).
updated_atstring<date-time>
When the document was last changed.
Errors
Plus the common errors every call can return. See Errors.