> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookingshake.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Invoice Events
> Receive a complete, self-contained payload every time an invoice is issued
**Beta** - Invoice events are currently in beta. The payload structure may still evolve before general availability. If you build on them, share your feedback at [support@bookingshake.com](mailto:support@bookingshake.com).
## Overview
The `invoice.created` event is sent every time an invoice document is issued in BookingShake. This covers all invoice document types: standard invoices, deposit invoices, balance invoices, and credit notes.
The **legal invoice** is immutable once issued - its amounts, lines, and seller / account / contact snapshots are frozen - so there is no `invoice.updated` or `invoice.deleted` event. A legal correction is always materialized by a new document (typically a credit note), which triggers its own `invoice.created` event. The only writable part of an invoice is its free-form [`metadata`](/api-reference/invoices-update) (integration key/value pairs); updating it is a silent side-channel write that emits **no** webhook.
Quotes do not trigger this event. Global invoices (issued across multiple bookings at once) are also excluded.
**Common use cases:**
* Sync invoices to your accounting software or ERP
* Archive legal documents in your own document management system
* Track revenue in real-time across venues
* Feed e-invoicing pipelines (the payload is aligned with EN 16931 semantics)
## Conventions
The invoice payload follows strict conventions, shared with [payment events](/api-reference/webhooks/payments):
| Convention | Rule |
| ------------------ | ----------------------------------------------------- |
| **Amounts** | Always integer **cents** (e.g., `150000` = €1,500.00) |
| **Dates** | `YYYY-MM-DD` strings, in the `Europe/Paris` timezone |
| **Timestamps** | Unix milliseconds |
| **Missing values** | Explicit `null`, never omitted |
## Invoice Types
The `type` field identifies the document type. `type_code` carries the corresponding UNTDID 1001 code used in e-invoicing standards:
| `type` | `type_code` | Description |
| --------------------- | ----------- | -------------------------------------------------- |
| `invoice` | 380 | Standard invoice |
| `deposit_invoice` | 386 | Deposit (down payment) invoice |
| `balance_invoice` | 380 | Balance invoice, issued after one or more deposits |
| `credit_note` | 381 | Credit note on a standard invoice |
| `deposit_credit_note` | 503 | Credit note on a deposit invoice |
| `balance_credit_note` | 381 | Credit note on a balance invoice |
`type_code` follows UNTDID 1001 (BT-3 in EN 16931, the basis of the French e-invoicing reform). This coding is broader than our internal types, so several `type` values legitimately share the same code. Only the deposit invoice has a dedicated code (`386`); a balance invoice is a standard invoice (`380`) that references the deposits, consistent with the B4/S4/M4 framework. Credit notes use `381`, except a credit note on a deposit invoice which uses `503`.
## Payload Example
```json theme={null}
{
"event": "invoice.created",
"timestamp": 1749722400000,
"venue_id": "venue123",
"venues_group_id": "group456",
"data": {
"id": "file-789",
"number": "FAC-2026-0042",
"type": "balance_invoice",
"type_code": 380,
"status": "ongoing",
"title": "Séminaire Acme - 12 juin 2026",
"language": "fr",
"currency": "EUR",
"created_at": 1749722400000,
"due_date": "2026-07-12",
"service_start_date": "2026-06-12",
"service_end_date": "2026-06-13",
"purchase_order_number": "PO-2026-1234",
"amount_excl_tax": 175000,
"amount_incl_tax": 210000,
"taxable_breakdown": { "20": 175000 },
"tax_breakdown": { "20": 35000 },
"global_discount_excl_tax": 0,
"lines": [
{
"name": "Location salle plénière",
"description": "Salle de 200 m², vidéoprojecteur et sonorisation inclus",
"accounting_code": "706100",
"quantity": "1.00",
"unit": null,
"unit_price_excl_tax": 150000,
"discount": 0,
"tax_rate": "20.00",
"total_excl_tax": 150000
},
{
"name": "Forfait journée d'étude",
"description": null,
"accounting_code": "707-SEM",
"quantity": "25.00",
"unit": null,
"unit_price_excl_tax": 4000,
"discount": 0,
"tax_rate": "20.00",
"total_excl_tax": 100000
},
{
"name": "Déduction acompte FAC-2026-0021 (TVA 20%)",
"description": null,
"accounting_code": null,
"quantity": "1.00",
"unit": null,
"unit_price_excl_tax": -75000,
"discount": 0,
"tax_rate": "20.00",
"total_excl_tax": -75000
}
],
"booking_id": "booking-abc",
"quote_id": "quote-123",
"linked_invoice_id": null,
"deposit_invoices": [
{
"id": "file-456",
"number": "FAC-2026-0021",
"date": "2026-05-01",
"amount_incl_tax": 90000
}
],
"account_id": "account-123",
"contact_id": "contact-456",
"seller": {
"id": "venue123",
"legal_name": "HOTEL EXAMPLE SAS",
"company_type": "SAS",
"company_registration_id": "123456789",
"vat_number": "FR12345678901",
"share_capital": "10 000 €",
"company_other_id": null,
"address_line_1": "1 place de l'Example",
"address_line_2": null,
"postal_code": "75001",
"city": "Paris",
"country": "France",
"iban": "FR7612345678901234567890123",
"email": "billing@hotel-example.com",
"country_code": "FR"
},
"account": {
"id": "account-123",
"name": "Acme Corp",
"legal_name": "ACME CORPORATION SAS",
"company_type": "SAS",
"company_registration_id": "987654321",
"siret": "98765432100012",
"vat_number": "FR98765432101",
"rcs_number": "RCS Paris 987 654 321",
"address_line_1": "123 rue Example",
"address_line_2": "Bâtiment A",
"postal_code": "75001",
"city": "Paris",
"country": "France",
"billing_address_line_1": "123 rue Example",
"billing_address_line_2": null,
"billing_postal_code": "75001",
"billing_city": "Paris",
"billing_country": "France",
"country_code": "FR",
"billing_country_code": "FR",
"peppol_id": "0009:987654321"
},
"contact": {
"id": "contact-456",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+33612345678",
"landline_phone": null,
"title": "Mr",
"position": "CEO",
"company": "Acme Corp",
"address_line_1": null,
"address_line_2": null,
"postal_code": null,
"city": null,
"country": null,
"country_code": null
},
"pdf_url": "https://storage.googleapis.com/.../FAC-2026-0042.pdf"
}
}
```
## Data Fields
### General
| Field | Type | Description |
| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Unique invoice document ID |
| `number` | string | Invoice number as printed on the PDF |
| `type` | string | Document type (see [Invoice Types](#invoice-types)) |
| `type_code` | number | UNTDID 1001 document type code (`380`, `386`, `381`, or `503`) |
| `status` | string \| null | `ongoing`, `paid`, or `canceled` |
| `title` | string \| null | Title of the related booking |
| `language` | string \| null | Language the document was issued in (e.g., `fr`, `en`). `null` when no language was frozen on the document; in that case line labels fall back to French |
| `currency` | string | Always `EUR` |
| `created_at` | number \| null | Issue timestamp, Unix milliseconds |
| `due_date` | string \| null | Payment due date, `YYYY-MM-DD` |
| `service_start_date` | string \| null | Start of the service period, `YYYY-MM-DD` |
| `service_end_date` | string \| null | End of the service period, `YYYY-MM-DD` |
| `purchase_order_number` | string \| null | Buyer's purchase order reference, if provided |
| `pdf_url` | string \| null | URL of the generated PDF document |
### Amounts
All amounts are integer cents, and are always **the amounts of the document itself**: a balance invoice carries the balance amount, not the total of the full service.
| Field | Type | Description |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `amount_excl_tax` | number | Total excluding tax of this document |
| `amount_incl_tax` | number | Total including tax of this document |
| `taxable_breakdown` | object | Taxable base per VAT rate for this document: `{ "20": 175000 }` (key = rate in %, value = cents) |
| `tax_breakdown` | object | Tax amount per VAT rate, same shape |
| `global_discount_excl_tax` | number | Global discount excluding tax applied to the document (`0` if none). It is **not** distributed into the lines |
On a **balance invoice**, the total of the full service can be recomposed as `amount_incl_tax + sum(deposit_invoices[].amount_incl_tax)`. The deposits deducted from the balance are itemized in `deposit_invoices` and appear as negative deduction lines in `lines`.
### Lines
`lines` contains the invoice line items as printed on the PDF, self-consistent with the document totals: `sum(lines[].total_excl_tax) - global_discount_excl_tax = amount_excl_tax` (within rounding).
Per document type:
* **Deposit invoice**: the deposit lines (one per VAT rate), not the lines of the underlying quote.
* **Balance invoice**: the full service lines, followed by one **negative deduction line** per deposit invoice and VAT rate (e.g., `Déduction acompte FAC-2026-0021 (TVA 20%)` with a negative `total_excl_tax`).
* **Credit notes**: same line structure as the document type they cancel.
| Field | Type | Description |
| --------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string \| null | Line label (EN16931 BT-153). Product title; for accommodation, the categories/occupancies label; for deposit and deduction lines, a generated label. Localized to the invoice `language` (falls back to French). `null` only if no label can be resolved |
| `description` | string \| null | Free-text line description as entered on the product/room and printed on the PDF (EN16931 BT-154). Localized to the invoice `language` (falls back to French). `null` when the line has none, and for aggregated and deduction lines |
| `accounting_code` | string \| null | Accounting code of the line, inherited from the product's accounting tag at generation time. `null` for aggregated and deposit-deduction lines |
| `quantity` | string | Decimal string (e.g., `"25.00"`) |
| `unit` | string \| null | Unit of measure, when applicable (e.g., `day` for accommodation lines) |
| `unit_price_excl_tax` | number | Unit price excluding tax, in cents, **before discount** |
| `discount` | number | Total line discount, in cents (`0` if none) |
| `tax_rate` | string | VAT rate as decimal string (e.g., `"20.00"`) |
| `total_excl_tax` | number | Line net amount in cents: `quantity × unit_price_excl_tax − discount` |
`quantity` and `tax_rate` are decimal **strings** to avoid floating-point precision issues, following EN 16931 conventions.
### Relations
| Field | Type | Description |
| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking_id` | string \| null | Opaque correlation key of the booking: all invoices and [payments](/api-reference/webhooks/payments) of the same booking share the same value |
| `quote_id` | string \| null | ID of the quote this invoice was generated from |
| `linked_invoice_id` | string \| null | For credit notes: ID of the corrected invoice |
| `deposit_invoices` | array | For balance invoices: prior deposit invoices, each with `id`, `number`, `date`, `amount_incl_tax` |
| `account_id` | string \| null | ID of the buyer account (company) |
| `contact_id` | string \| null | ID of the buyer contact |
### Seller, Account, and Contact Blocks
`seller` (your venue), `account` (the buyer company), and `contact` (the buyer contact) are **frozen snapshots** captured when the invoice was issued. They reflect the legal mentions printed on the PDF and will not change if the live account or contact is later edited.
Field names are aligned with the [`account.*`](/api-reference/webhooks/accounts) and [`contact.*`](/api-reference/webhooks/contacts) events: a consumer sees the same account format across all event types.
Fields specific to these blocks:
| Field | Block | Description |
| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country_code` | all | Country normalized to ISO 3166-1 alpha-2 (e.g., `FR`), or `null` when it cannot be resolved. `country` stays verbatim as entered. |
| `billing_country_code` | `account` | Same normalization for the billing country |
| `iban` | `seller` | Bank account printed on the invoice |
| `share_capital` | `seller` | Share capital legal mention, verbatim |
| `peppol_id` | `account` | Peppol participant ID for e-invoicing routing. Unlike the rest of the block, this is always read **live** (routing data, not a frozen legal mention). |
Any of the three blocks can be `null` if the corresponding entity was not set on the booking (e.g., `account` is `null` for an individual customer without a company).
## Next Steps
Track payments with the payment.created, updated, and deleted events
Verify webhook signatures before processing