Invoices

Beta - Invoice data is currently in beta. The payload structure may still evolve before general availability. Share your feedback at support@bookingshake.com.

List invoices

curl 'https://api.bookingshake.io/api/invoices?type=invoice&created_from=1756000000000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Paginated (limit 1-100 default 25, opaque cursor, response { "items": [...], "next_cursor": "..." }), newest first. Filters: created_from/created_to (Unix ms, issue date), type (invoice, deposit_invoice, balance_invoice, credit_note, deposit_credit_note, balance_credit_note) and status (ongoing, paid, canceled). Items use the full invoice payload below - the natural way to backfill historical invoices before relying on the invoice.created webhook.

Iterate on next_cursor until it is null: a page may contain fewer than limit items even when more data remains. When type and status are combined, status is applied after the indexed query.

Get an invoice

Overview

GET /invoices/{id} returns a single invoice by its document ID - useful to back-fill a missed webhook, reconcile your accounting, or re-fetch a document on demand. The endpoint returns standard invoices, deposit invoices, balance invoices, and their credit notes. Quotes are not exposed by this endpoint.

Amounts are always integer cents, dates are YYYY-MM-DD strings in the Europe/Paris timezone, timestamps are Unix milliseconds, and missing values are explicit null. See the invoice webhook reference for the full field-by-field definition.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The invoice document ID - the id field carried by the invoice.created webhook.

Request

curl https://api.bookingshake.io/api/invoices/file-789 \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.bookingshake.io/api/invoices/file-789", {
  headers: { Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}` },
});
const { data: invoice } = await res.json();

import os, requests

res = requests.get(
    "https://api.bookingshake.io/api/invoices/file-789",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
)
invoice = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/invoices/file-789");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
]);
$invoice = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

Response

The invoice is returned wrapped in the standard { message, data } envelope. The data object follows the Invoice schema.

{
  "message": "success",
  "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", "...": "..." },
    "account": { "id": "account-123", "name": "Acme Corp", "...": "..." },
    "contact": { "id": "contact-456", "first_name": "John", "last_name": "Doe", "...": "..." },
    "pdf_url": "https://storage.googleapis.com/.../FAC-2026-0042.pdf",
    "metadata": { "external_ref": "MEWS-2026-0042" }
  }
}

Key Fields

Field	Type	Description
`id`	string	Unique invoice document ID
`number`	string	Invoice number as printed on the PDF
`type` / `type_code`	string / number	Document type and its UNTDID 1001 code (see Invoice Types)
`status`	string \| null	`ongoing`, `paid`, or `canceled`
`amount_excl_tax` / `amount_incl_tax`	number	Document totals, in cents
`lines`	array	Line items, self-consistent with the totals
`deposit_invoices`	array	For balance invoices: prior deposits deducted
`booking_id`	string \| null	Correlation key shared with payment and invoice events of the same booking
`seller` / `account` / `contact`	object \| null	Frozen legal-mention snapshots captured at issue time
`pdf_url`	string \| null	URL of the generated PDF
`metadata`	object	Free-form integration key/value pairs (strings), editable via `PATCH /invoices/{id}`. Empty `{}` when unset

For the complete field reference (amounts, lines, snapshot blocks), see the invoice webhook documentation.

Errors

Status	Meaning
`400`	Missing/invalid token, or missing invoice id
`404`	Invoice not found - it does not exist, belongs to another venue, or is not an invoice (e.g. a quote)
`429`	Rate limit exceeded (60 requests/minute)
`500`	Internal server error

A 404 is returned uniformly whenever the invoice is outside your scope, so the existence of another venue’s invoice is never disclosed.

Next Steps

Invoice Events

Receive invoices in real time via the invoice.created webhook

Payment Events

Track payments tied to the same booking

Update invoice metadata

Overview

PATCH /invoices/{id} updates the metadata of an issued invoice - a free-form bag of string key/value pairs you can use to attach your own references (an external accounting ID, a Mews record, a sync state…). An issued invoice is legally immutable: its amounts, lines, and the seller / account / contact snapshots are frozen at issue time and cannot be changed through this endpoint. metadata is the only writable field; it lives alongside the legal invoice and never affects it. A legal correction is always materialized by a new document (typically a credit note), never by editing an invoice.

This endpoint does not emit any webhook - there is no invoice.updated event. Updating metadata is a silent, side-channel write. Any attempt to modify a legal field is rejected with 422.

The merge is per key:

metadata: { "ref": "ABC" } upserts the ref key, leaving every other key untouched.
metadata: { "ref": null } deletes the ref key.

Authentication

All requests require a Bearer token (your BookingShake API key):

Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The invoice document ID - the id field carried by the invoice.created webhook.

Body Parameters

object

required

A flat object of string values. Pass null as a value to delete that key. Keys present in the object are merged into the existing metadata; keys you omit are left untouched.Limits: up to 50 keys per invoice, each key ≤ 40 characters, each value ≤ 500 characters. Nested objects, arrays, and non-string values are rejected with 422.

Request

curl -X PATCH https://api.bookingshake.io/api/invoices/file-789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "external_ref": "MEWS-2026-0042", "synced_at": "2026-06-18" } }'

const res = await fetch("https://api.bookingshake.io/api/invoices/file-789", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BOOKINGSHAKE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    metadata: { external_ref: "MEWS-2026-0042", synced_at: "2026-06-18" },
  }),
});
const { data: invoice } = await res.json();

import os, requests

res = requests.patch(
    "https://api.bookingshake.io/api/invoices/file-789",
    headers={"Authorization": f"Bearer {os.environ['BOOKINGSHAKE_API_KEY']}"},
    json={"metadata": {"external_ref": "MEWS-2026-0042", "synced_at": "2026-06-18"}},
)
invoice = res.json()["data"]

<?php
$ch = curl_init("https://api.bookingshake.io/api/invoices/file-789");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "metadata" => [
        "external_ref" => "MEWS-2026-0042",
        "synced_at" => "2026-06-18",
    ],
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("BOOKINGSHAKE_API_KEY"),
    "Content-Type: application/json",
]);
$invoice = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);

Response

The full invoice is returned in its post-update state, wrapped in the standard { message, data } envelope - identical in shape to GET /invoices/{id}, with the updated metadata.

{
  "message": "success",
  "data": {
    "id": "file-789",
    "number": "FAC-2026-0042",
    "type": "balance_invoice",
    "type_code": 380,
    "status": "ongoing",
    "...": "... (all legal fields, unchanged)",
    "pdf_url": "https://storage.googleapis.com/.../FAC-2026-0042.pdf",
    "metadata": {
      "external_ref": "MEWS-2026-0042",
      "synced_at": "2026-06-18"
    }
  }
}

See the Get an Invoice reference for the full field descriptions.

Errors

Status	Meaning
`400`	Missing/invalid token, missing invoice id, empty/invalid body, or no `metadata` provided
`422`	A field other than `metadata` was sent (legal fields are immutable), `metadata` is not a flat object of strings, or a limit was exceeded (50 keys, key ≤ 40 chars, value ≤ 500 chars)
`404`	Invoice not found - it does not exist, belongs to another venue, or is not an invoice (e.g. a quote)
`429`	Rate limit exceeded (30 requests/minute)
`500`	Internal server error

A 404 is returned uniformly whenever the invoice is outside your scope, so the existence of another venue’s invoice is never disclosed.

Getting Started

Webhooks

REST API

Guides

List invoices

Get an invoice

Overview

Authentication

Path Parameters

Request

Response

Key Fields

Errors

Next Steps

Invoice Events

Payment Events

Update invoice metadata

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps

Get an Invoice

Invoice Events

​List invoices

​Get an invoice

​Overview

​Authentication

​Path Parameters

​Request

​Response

​Key Fields

​Errors

​Next Steps

Invoice Events

Payment Events

​Update invoice metadata

​Overview

​Authentication

​Path Parameters

​Body Parameters

​Request

​Response

​Errors

​Next Steps

Get an Invoice

Invoice Events

List invoices

Get an invoice

Overview

Authentication

Path Parameters

Request

Response

Key Fields

Errors

Next Steps

Update invoice metadata

Overview

Authentication

Path Parameters

Body Parameters

Request

Response

Errors

Next Steps