DocumentsCreate an estimate

Documents

Create an estimate

POST/v1/documents

Creates a draft estimate (quote) with the same lines and maths as an invoice. Send type: "estimate".

An estimate has its own type and its own number sequence (EST-{YYYY}-{SEQ:4} by default) and uses the same line maths as invoices. It is created as a draft with no number and takes its number when first sent.

After sending, the client opens the estimate link to accept it or request changes. Turn an estimate into an invoice with Convert an estimate. See Estimates.

  • Idempotency-Key is required for API-key and MCP calls.
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_estimate
MCP tool
create_estimate
CLI
freeinvoiceautomation estimate create
Available
At launch, 1 January 2027
create_estimate
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": "estimate",
  "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
  "currency": "USD",
  "issue_date": "2027-02-01",
  "expires_at": "2027-03-03",
  "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"
    }
  ],
  "notes": "Valid for 30 days."
}'
{
  "data": {
    "id": "0193f2b2-8e7d-7c6b-9a50-4f3e2d1c0b9a",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
    "type": "estimate",
    "status": "draft",
    "number": null,
    "issue_date": "2027-02-01",
    "due_date": null,
    "expires_at": "2027-03-03",
    "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": null,
    "notes": "Thank you for your business.",
    "accepted_methods": null,
    "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-01-31T15:00:00Z",
    "updated_at": "2027-01-31T15:00:00Z"
  }
}

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/json
typeenum<string>required
Document type. Send estimate 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.
expires_atstring<date>
Date the estimate expires. Defaults from the business's estimate expiry setting.
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/json
idstring<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

validation_failed
idempotency_key_reused
idempotency_in_progress
business_out_of_scope
conflict

Plus the common errors every call can return. See Errors.

Suggest editsRaise issue
Create an invoicePreviousCreate a receiptNext