Bookings

When you save a calculation it becomes a booking: the request that produced it, the full tax response, the amounts, and a status. The tax components are a snapshot — captured at booking time, not re-evaluated against today's rates — so the record stays stable even as reference data evolves. Each booking also belongs to either the Live or Test series, set by the mode active when it was saved.

There are two ways to create one:

1. 1
   From the calculator

   Run a calculation, then choose Save & open booking in the Save-as-booking card. See the calculator.
2. 2
   From the API

   Post the calculation to /v1/bookings with an idempotency_key. The key makes retries safe: the same key always returns the same booking instead of creating a duplicate. See Bookings (API).

The list shows ID, external reference, status, tax, total, jurisdiction, and created date, filterable by status and paginated. It's scoped to the active Test/Live mode. Click a row to open the detail page, which lays out:

• Summary — status, whether it's a test booking, the idempotency key (with a copy button), and an issuance badge linking to the issued invoice if one exists.
• Stay details — the calculation inputs (jurisdiction, dates, nights, rate, property, guests, and any multi-actor fields).
• Amounts — subtotal, tax, total with tax, effective rate, and any settlement-currency projection.
• Tax Components — the snapshot breakdown, marked as a snapshot.
• Refund History — each refund, when any exist.
• the raw request and response payloads, collapsible.

A booking moves through a small set of statuses, shown as a badge and used by the list filter:

• Confirmed — the normal state of a saved booking.
• Adjusted — the calculation was re-run and the change appended to the booking's adjustment history.
• Voided — cancelled. Voids are sticky.
• Refunded — a refund (full or partial) was processed.

Three operations change a booking, and it's worth keeping them straight:

• Adjust re-runs the tax engine with changed inputs and appends to the booking's adjustment_history. The number can change.
• Refund records a full or partial refund and returns the per-jurisdiction tax delta. You can simulate one straight from the calculator's Save-as-booking card; programmatically it's a dedicated endpoint, idempotent via a refund key.
• Edit invoice details changes invoice-only metadata — buyer name and address, references, the attached legal issuer — with no engine re-run and no adjustment-history entry. It's exposed as the “Edit invoice details” form on the booking's document modal (see Invoices).

# Re-runs the engine; appends to adjustment_history
curl -X PATCH https://api.taxlens.getdynamiq.ai/v1/bookings/123 \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "calculation": { "nightly_rate": 220, "nights": 3, "...": "..." } }'

Issuing a live invoice (a 380 commercial or 389 self-billed document) freezes the booking. From that point, adjust, void, refund, and edit invoice details all refuse with a 409 — corrections must go through a credit note instead. (Once the original is credited or cancelled, it no longer constrains the booking.)

To turn a send-ready booking into an invoice, continue to Invoices.