Documents

Void a document

POST/v1/documents/{id}/void

Cancels a sent invoice that has no payments. It keeps its number and is stamped VOID.

Voiding is destructive and needs confirm: true and a void_reason. A voided invoice keeps its number (so numbering stays complete), shows a VOID stamp on the PDF, pay page and portal, stops reminders and late fees, and revokes its open pay links. It is never deleted.

An invoice with recorded payments cannot be voided: the request is refused with document_has_payments. Issue a credit note instead. A draft has nothing to void; delete it with Delete a draft.

Every void writes an audit entry with the reason. When a store connector mirrors a cancelled order, the void runs automatically and is audited with the connector as actor. See Void and delete.

Needs confirmation

This action is destructive or moves money. Send "confirm": true in the body; without it you get 428 confirmation_required and a preview of what would happen. See Drafts and confirmations.

Without confirm: true you get the preview and confirmation_required.
Idempotency-Key is required for API-key and MCP calls.

Permission: documents.void
Type: Destructive or money-moving. Needs "confirm": true (or a confirmation in the app).
Auth: API key, MCP token or signed-in session
Capability: void_document
MCP tool: void_document
CLI: freeinvoiceautomation doc void
Available: At launch, 1 January 2027

void_document

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/<id>/void \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "void_reason": "Issued to the wrong client.",
  "confirm": true
}'

{
  "data": {
    "id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
    "type": "invoice",
    "status": "void",
    "number": "INV-2027-0017",
    "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": 1,
    "first_sent_at": "2027-02-01T10:15:00Z",
    "last_sent_at": "2027-02-01T10:15:00Z",
    "accepted_at": null,
    "paid_at": null,
    "overdue_at": null,
    "voided_at": "2027-02-03T12:00:00Z",
    "voided_by": "0193f29d-0f1e-7d2c-8b3a-49586a7b8c9d",
    "void_reason": "Issued to the wrong client.",
    "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-03T12: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 void calls. Any unique string up to 255 characters; a retry with the same key returns the first response. See Idempotency.

Path Parameters

idstring<uuid>required

Id of the document.

Body

application/json

void_reasonstringrequired

Why the document is voided. Stored on the document and in the audit log.

confirmbooleanrequired

Must be true to void the document. Without it nothing changes: you get the preview and confirmation_required. See Drafts and confirmations.

Response

200 - 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

confirmation_required

document_has_payments

document_voided

conflict

idempotency_key_reused

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

Suggest edits Raise issue

Revoke a share linkPrevious Create a credit noteNext

curl --request POST \ --url https://api.freeinvoiceautomation.com/v1/documents/<id>/void \ --header 'Authorization: Bearer <api-key>' \ --header 'Idempotency-Key: <unique-key>' \ --header 'Content-Type: application/json' \ --data '{ "void_reason": "Issued to the wrong client.", "confirm": true }'

{ "data": { "id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a", "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f", "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f", "type": "invoice", "status": "void", "number": "INV-2027-0017", "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": 1, "first_sent_at": "2027-02-01T10:15:00Z", "last_sent_at": "2027-02-01T10:15:00Z", "accepted_at": null, "paid_at": null, "overdue_at": null, "voided_at": "2027-02-03T12:00:00Z", "voided_by": "0193f29d-0f1e-7d2c-8b3a-49586a7b8c9d", "void_reason": "Issued to the wrong client.", "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-03T12:00:00Z" } }