Invoices

Full update an invoice

Replace all fields on an existing invoice. All required fields must be provided.

put/v1/invoices/{invoiceId}

Request

  • Base URL: https://api.frihet.io
  • URL: https://api.frihet.io/v1/invoices/{invoiceId}
  • Auth: API key in header X-API-Key

Path parameters

invoiceIdstring required

Invoice unique identifier

Request body

clientIdstring

Client document ID. When provided, the API auto-snapshots clientTaxId, clientAddress, clientLocation, clientName, and clientEmail from the referenced client at create time (immutable post-create — VeriFactu RD 1007/2023). Caller-provided values for those fields override the snapshot.

clientNamestring required

Client name (snapshot field — frozen at create)

clientTaxIdstring

Client tax ID / NIF / VAT (snapshot field — frozen at create). Auto-populated from clientId reference if not provided.

clientAddressstring

Client billing address — single-line or structured. Snapshot field, frozen at create.

clientLocation'peninsula' | 'canarias' | 'ceuta_melilla' | 'eu' | 'world'

Fiscal zone — drives tax label rendering on PDF + tax math (IVA/IGIC/IPSI/Reverse charge/Exempt). Snapshot field, frozen at create. Auto-populated from clientId reference if absent.

clientEmailstring email

Client email (snapshot field — frozen at create).

documentNumberstring

Optional caller-supplied invoice number (e.g. migration or import flows carrying an externally-issued number). When provided it is honored verbatim and the workspace auto-numbering counter is NOT advanced. When omitted, a gapless sequential number is generated from your numbering settings (VeriFactu RD 1007/2023).

issueDatestring date

Issue date in ISO format

dueDatestring date

Due date in ISO format

status'draft' | 'sent' | 'partial' | 'paid' | 'overdue' | 'cancelled'
notesstring

Additional notes

taxRatenumber

Tax rate percentage. Combined with clientLocation to produce the label (IGIC for canarias, IPSI for ceuta_melilla, etc.).

irpfRatenumber

IRPF withholding rate percentage (Spain).

discountRatenumber

Invoice-level discount percentage.

Example request

{
  "clientId": "client_abc123",
  "clientName": "Acme Corp",
  "clientTaxId": "B12345678",
  "clientAddress": "Calle Mayor 12, 38001 Santa Cruz de Tenerife",
  "clientLocation": "canarias",
  "documentNumber": "FAC-2026-0042",
  "items": [
    {
      "description": "Web development services",
      "quantity": 10,
      "unitPrice": 85
    }
  ],
  "issueDate": "2026-03-09",
  "dueDate": "2026-04-09",
  "notes": "Payment due within 30 days",
  "taxRate": 21,
  "irpfRate": 15,
  "discountRate": 10,
  "recurring": {
    "enabled": true,
    "frequency": "monthly",
    "nextDate": "2026-04-01",
    "endDate": "2027-03-31",
    "maxOccurrences": 12
  }
}

Response

Invoice updated

idstring

Unique identifier

createdAtstring date-time

Creation timestamp

updatedAtstring date-time

Last update timestamp

clientIdstring

Client document ID. When provided, the API auto-snapshots clientTaxId, clientAddress, clientLocation, clientName, and clientEmail from the referenced client at create time (immutable post-create — VeriFactu RD 1007/2023). Caller-provided values for those fields override the snapshot.

clientNamestring required

Client name (snapshot field — frozen at create)

clientTaxIdstring

Client tax ID / NIF / VAT (snapshot field — frozen at create). Auto-populated from clientId reference if not provided.

clientAddressstring

Client billing address — single-line or structured. Snapshot field, frozen at create.

clientLocation'peninsula' | 'canarias' | 'ceuta_melilla' | 'eu' | 'world'

Fiscal zone — drives tax label rendering on PDF + tax math (IVA/IGIC/IPSI/Reverse charge/Exempt). Snapshot field, frozen at create. Auto-populated from clientId reference if absent.

clientEmailstring email

Client email (snapshot field — frozen at create).

documentNumberstring

Auto-generated invoice number

issueDatestring date

Issue date in ISO format

dueDatestring date

Due date in ISO format

status'draft' | 'sent' | 'partial' | 'paid' | 'overdue' | 'cancelled'
notesstring

Additional notes

taxRatenumber

Tax rate percentage. Combined with clientLocation to produce the label (IGIC for canarias, IPSI for ceuta_melilla, etc.).

irpfRatenumber

IRPF withholding rate percentage (Spain).

discountRatenumber

Invoice-level discount percentage.

subtotalnumber

Subtotal before tax

taxnumber

Tax amount

totalnumber

Total amount including tax

currencystring

Currency code

verifactuHashstring

VeriFactu SHA-256 hash (Spanish tax compliance)

Example response

{
  "id": "abc123def456",
  "clientId": "client_abc123",
  "clientName": "Acme Corp",
  "clientTaxId": "B12345678",
  "clientAddress": "Calle Mayor 12, 38001 Santa Cruz de Tenerife",
  "clientLocation": "canarias",
  "documentNumber": "FAC-2026-0042",
  "items": [
    {
      "description": "Web development services",
      "quantity": 10,
      "unitPrice": 85
    }
  ],
  "issueDate": "2026-03-09",
  "dueDate": "2026-04-09",
  "notes": "Payment due within 30 days",
  "taxRate": 21,
  "irpfRate": 15,
  "discountRate": 10,
  "recurring": {
    "enabled": true,
    "frequency": "monthly",
    "nextDate": "2026-04-01",
    "endDate": "2027-03-31",
    "maxOccurrences": 12
  },
  "subtotal": 850,
  "tax": 178.5,
  "total": 1028.5,
  "currency": "EUR"
}

Changes

No recorded changes to this operation across all 1 revision of this API.