DocumentsCreate a receipt

Documents

Create a receipt

POST/v1/documents

Creates a receipt for a sale that was already paid, e.g. a store order paid at checkout. Send type: "receipt".

A receipt confirms a payment that already happened. It has no draft status: it is created as issued with the next number of the business's receipt sequence (RCT-{YYYY}-{SEQ:4} by default). A receipt can later be voided, never deleted.

Store connectors create receipts or invoices for orders depending on the install settings, using external_ref with the order id so the same order never creates two documents. See Receipts.

  • 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_receipt
CLI
freeinvoiceautomation receipt create
Available
At launch, 1 January 2027
create_receipt
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": "receipt",
  "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
  "currency": "USD",
  "issue_date": "2027-02-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"
    }
  ],
  "external_ref": "order-10482"
}'
{
  "data": {
    "id": "0193f2d1-6a5b-7c4d-8e3f-2a1b0c9d8e7f",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
    "type": "receipt",
    "status": "issued",
    "number": "RCT-2027-0004",
    "issue_date": "2027-02-03",
    "due_date": null,
    "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": "120000",
    "amount_credited_minor": "0",
    "balance_minor": "0",
    "terms": null,
    "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": null,
    "last_sent_at": null,
    "accepted_at": null,
    "paid_at": "2027-02-03T16:20:00Z",
    "overdue_at": null,
    "voided_at": null,
    "voided_by": null,
    "void_reason": null,
    "source": "api",
    "external_ref": "order-10482",
    "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-03T16:20:00Z",
    "updated_at": "2027-02-03T16:20: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 receipt 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.
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.
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 estimatePreviousUpdate an invoiceNext