Invoice Events

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.

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 (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:

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

{
  "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
      }
    ],
    "payments": [
      {
        "id": "payment-321",
        "amount": 210000,
        "status": "waiting",
        "name": "Solde",
        "method_id": null,
        "received_date": null,
        "due_date": "2026-07-12",
        "created_at": 1749722400000,
        "updated_at": null
      }
    ],
    "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)
`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 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`
`payments`	array	Payment schedule attached to the invoice, snapshotted at issue time (see Payments)
`account_id`	string \| null	ID of the buyer account (company)
`contact_id`	string \| null	ID of the buyer contact

Payments

payments contains the payment schedule attached to the invoice, as it stood when the invoice was issued. Since there is no invoice.updated event, this array is a snapshot: to follow the lifecycle of each payment afterwards (marked as paid, rescheduled, canceled), subscribe to payment events and join them on id — each entry here has the exact same shape as the data block of payment.* events, minus the join keys (invoice_id, invoice_number, quote_id, booking_id) already carried at the invoice level. Entries are sorted by due_date (then created_at). Security deposits (holds) are excluded, consistent with payment events. Credit notes carry an empty array.

Field	Type	Description
`id`	string	Unique payment ID, matches the `id` of `payment.*` events
`amount`	number \| null	Amount in integer cents
`status`	string \| null	`waiting`, `paid`, or `canceled`
`name`	string \| null	Payment label
`method_id`	string \| null	Stable ID of the method in the venue catalog - see payment events
`received_date`	string \| null	Date the payment was received, `YYYY-MM-DD`
`due_date`	string \| null	Date the payment is expected, `YYYY-MM-DD`
`created_at`	number \| null	Creation timestamp, Unix milliseconds
`updated_at`	number \| null	Last update timestamp, Unix milliseconds

Amounts are signed: a negative amount with status paid represents a refund - see Refunds.

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.* and contact.* 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).

Getting Started

Webhooks

REST API

Guides

Overview

Conventions

Invoice Types

Payload Example

Data Fields

General

Amounts

Lines

Relations

Payments

Seller, Account, and Contact Blocks

Next Steps

Payment Events

Security & Verification

​Overview

​Conventions

​Invoice Types

​Payload Example

​Data Fields

​General

​Amounts

​Lines

​Relations

​Payments

​Seller, Account, and Contact Blocks

​Next Steps

Payment Events

Security & Verification

Overview

Conventions

Invoice Types

Payload Example

Data Fields

General

Amounts

Lines

Relations

Payments

Seller, Account, and Contact Blocks

Next Steps