Skip to main content
POST
/
v1
/
invoices
Error
A valid request URL is required to generate request examples
{
  "id": "a3f1d7d0-ef1d-4b2e-aad2-123456789abc",
  "tenantId": "b4e2d8e1-fg2e-5c3f-bbe3-234567890bcd",
  "customerId": "c5f3e9f2-gh3f-6d4g-ccf4-345678901cde",
  "status": "draft",
  "issuedAt": "2024-01-15T10:00:00.000Z",
  "netTotal": 100,
  "vatRate": 20,
  "taxTotal": 20,
  "grossTotal": 120,
  "currency": "EUR",
  "sendByEmail": true,
  "pdfVersion": 1,
  "createdAt": "2024-01-15T09:00:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "lineItems": [
    {
      "id": "item_1",
      "type": "booking",
      "description": "Meeting Room - January 15, 2024",
      "unitPrice": 25,
      "quantity": 1,
      "total": 25
    }
  ],
  "quoteId": "d6g4f0g3-hi4g-7e5h-ddg5-456789012def",
  "dueDate": "2024-02-15T00:00:00.000Z",
  "paidAt": "2024-01-20T14:30:00.000Z",
  "paymentMethod": "stripe_card",
  "paymentReference": "ch_1234567890abcdef",
  "pdfUrl": "https://storage.example.com/invoices/inv_123456.pdf"
}

Body

application/json
​
customerId
string<uuid>
required

Unique identifier (UUID) of the customer this invoice is billed to

Example:

"c5f3e9f2-gh3f-6d4g-ccf4-345678901cde"

​
vatRate
number
required

VAT (Value Added Tax) rate applied to the invoice, expressed as a percentage (e.g., 20 for 20% VAT).

Required range: 0 <= x <= 100
Example:

20

​
currency
enum<string>
required

ISO 4217 currency code used for all amounts in this invoice. Defaults to EUR if not specified.

Available options:
EUR,
USD,
GBP,
CAD,
AUD
Example:

"EUR"

​
netTotal
number
required

Total amount excluding VAT (HT - Hors Taxes). Sum of all line item totals before tax.

Required range: x >= 0
Example:

100

​
taxTotal
number
required

Total VAT amount (TVA - Taxe sur la Valeur Ajoutée) calculated on the net total.

Required range: x >= 0
Example:

20

​
grossTotal
number
required

Total amount including VAT (TTC - Toutes Taxes Comprises). This is the final amount the customer must pay.

Required range: x >= 0
Example:

120

​
lineItems
object[]
required

List of line items to include in the invoice. Each line item must have a description, quantity, and unit price. At least one item is required.

Example:
[
  {
    "description": "Meeting Room - January 15, 2024",
    "unitPrice": 25,
    "quantity": 1
  }
]
​
quoteId
string<uuid>

Optional reference to a quote that was converted to this invoice. Only present if the invoice was created from a quote.

Example:

"d6g4f0g3-hi4g-7e5h-ddg5-456789012def"

​
dueDate
string<date-time>

Optional due date by which payment should be received. If not set, payment terms may be defined elsewhere.

Example:

"2024-02-15T00:00:00.000Z"

​
sendByEmail
boolean
default:false

Whether the invoice should be automatically sent to the customer via email when finalized. If true, an email will be sent when the invoice status changes to SENT.

Example:

false

Response

Invoice created successfully in DRAFT status. Use the PATCH endpoint to update or finalize it.

​
id
string<uuid>
required

Unique identifier (UUID) of the invoice

Example:

"a3f1d7d0-ef1d-4b2e-aad2-123456789abc"

​
tenantId
string<uuid>
required

Unique identifier of the tenant (organization) that owns this invoice

Example:

"b4e2d8e1-fg2e-5c3f-bbe3-234567890bcd"

​
customerId
string<uuid>
required

Unique identifier of the customer this invoice is billed to

Example:

"c5f3e9f2-gh3f-6d4g-ccf4-345678901cde"

​
status
enum<string>
required

Current status of the invoice. DRAFT: being prepared, SENT: sent to customer, PAID: payment received, OVERDUE: past due date, CANCELLED: cancelled.

Available options:
draft,
sent,
paid,
overdue,
cancelled
Example:

"draft"

​
issuedAt
string<date-time>
required

Date and time when the invoice was issued to the customer. Format: ISO 8601 date-time.

Example:

"2024-01-15T10:00:00.000Z"

​
netTotal
number
required

Total amount excluding VAT (HT - Hors Taxes). Sum of all line item totals before tax.

Required range: x >= 0
Example:

100

​
vatRate
number
required

VAT (Value Added Tax) rate applied to the invoice, expressed as a percentage (e.g., 20 for 20% VAT).

Required range: 0 <= x <= 100
Example:

20

​
taxTotal
number
required

Total VAT amount (TVA - Taxe sur la Valeur Ajoutée) calculated on the net total.

Required range: x >= 0
Example:

20

​
grossTotal
number
required

Total amount including VAT (TTC - Toutes Taxes Comprises). This is the final amount the customer must pay.

Required range: x >= 0
Example:

120

​
currency
enum<string>
required

ISO 4217 currency code used for all amounts in this invoice. Defaults to EUR if not specified.

Available options:
EUR,
USD,
GBP,
CAD,
AUD
Example:

"EUR"

​
sendByEmail
boolean
required

Whether the invoice should be automatically sent to the customer via email when finalized. If true, an email will be sent when the invoice status changes to SENT.

Example:

true

​
pdfVersion
number
required

Version number of the PDF document. Increments each time the invoice PDF is regenerated, allowing tracking of document versions.

Required range: x >= 1
Example:

1

​
createdAt
string<date-time>
required

Date and time when the invoice was first created in the system. Format: ISO 8601 date-time.

Example:

"2024-01-15T09:00:00.000Z"

​
updatedAt
string<date-time>
required

Date and time when the invoice was last modified. Format: ISO 8601 date-time.

Example:

"2024-01-15T10:30:00.000Z"

​
lineItems
object[]
required

List of line items included in this invoice. Each line item represents a product, service, or booking being invoiced.

Example:
[
  {
    "id": "item_1",
    "type": "booking",
    "description": "Meeting Room - January 15, 2024",
    "unitPrice": 25,
    "quantity": 1,
    "total": 25
  }
]
​
quoteId
string<uuid>

Optional reference to a quote that was converted to this invoice. Only present if the invoice was created from a quote.

Example:

"d6g4f0g3-hi4g-7e5h-ddg5-456789012def"

​
dueDate
string<date-time>

Optional due date by which payment should be received. If not set, payment terms may be defined elsewhere.

Example:

"2024-02-15T00:00:00.000Z"

​
paidAt
string<date-time>

Date and time when payment was received. Only present for paid invoices.

Example:

"2024-01-20T14:30:00.000Z"

​
paymentMethod
enum<string>

Payment method used for this invoice. Only present for paid invoices. STRIPE methods use Stripe payment processing, SEPA and BANK_TRANSFER are manual methods.

Available options:
stripe_card,
stripe_google_pay,
stripe_apple_pay,
sepa,
bank_transfer
Example:

"stripe_card"

​
paymentReference
string

Optional transaction reference or payment ID from the payment processor. Used for reconciliation and tracking.

Example:

"ch_1234567890abcdef"

​
pdfUrl
string

URL to download the generated PDF version of the invoice. Only available after the invoice has been finalized and PDF generation is complete.

Example:

"https://storage.example.com/invoices/inv_123456.pdf"