Booking Schema

The booking is one of the four primary Versa event types. It shares the same underlying structure as a receipt, but with fewer required fields — payment has typically not yet occurred at the time of booking, so totals and payment details may be partial or absent.

A JSON Schema document and corresponding TypeScript Types are available on GitHub or via the @versa/schema package.

Differences from the Receipt Schema

Bookings relax a number of fields that are required on a receipt:

• Header: Only currency and total are required. subtotal, paid, and invoiced_at are all optional on a booking (they become required once the transaction settles as a receipt). A booked_at timestamp is available for the time at which the booking was made.
• Payments: The payments array may be omitted or set to null. header.paid is typically 0 until payment occurs.
• Footer: The footer may be omitted or set to null.
• Lodging itemization: items is optional — the itemization breakdown is often not known at the time of booking.

All other objects and primitives are shared with the receipt schema; the sections below document a booking in full for convenience.

Sections

Booking objects are composed of four sections:

1. Header: Top-level fields, e.g. merchant details, totals, booking date.
2. Itemization: Description, quantity, unit cost, and total for each line item. Type-specific templates describe different purchase types, e.g. flight, lodging, car rental.
3. Footer: Optional merchant-defined actions and supplemental text. For example: 'Cancel Booking,' 'Manage Reservation,' 'Contact Support.'
4. Payments: Optional payment status and details.

Wrapper

Booking objects are wrapped in a top-level envelope that includes the schema version:

{
  "schema_version": "2.3.0",
  "header": { ... },
  "itemization": { ... },
  "payments": null,
  "footer": null
}

Header

The header provides a high-level view of the booking, describing the "who," "when," and "where" (the "what" is covered in the itemization section). On a booking, only currency and total are required; totals not yet known can be left null. An example header:

"header": {
  "currency": "usd",
  "total": 6332,
  "subtotal": null,
  "paid": 0,
  "booked_at": 1713295619,
  "invoiced_at": null,
  "invoice_number": "BK-1024",
  "lifecycle_status": "active",
  "customer": null,
  "location": null
}

Itemization

The Itemization section describes the goods and services that compose the booking. Based on the type of booking, the object conforms to one of eight templates: General, Car Rental, E-commerce, Flight, Lodging, Service, Subscription, or Transit Route. Exactly one itemization template should be non-null. When in doubt for a travel booking, use flight, lodging, car_rental, or transit_route.

"itemization": {
  "general": null,
  "car_rental": null,
  "ecommerce": null,
  "flight": { ... },
  "lodging": null,
  "service": null,
  "subscription": null,
  "transit_route": null
}

"car_rental": {
  "rental_at": 1713196492,
  "return_at": 1713415500,
  "confirmation_number": null,
  "record_locator": null,
  "vendor_code": null,
  "rental_location": { ... },
  "return_location": { ... },
  "vehicle": {
    "description": "Polestar 2",
    "image": null,
    "license_plate_number": null,
    "vehicle_class": "EDAE"
  },
  "drivers": [{ ... }],
  "odometer_reading_in": null,
  "odometer_reading_out": null,
  "items": [ ... ],
  "metadata": [],
  "invoice_level_adjustments": []
}

"lodging": {
  "check_in": 1713196492,
  "check_out": 1713473361,
  "confirmation_number": "ABC123",
  "chain_code": "MC",
  "property_id": null,
  "record_locator": null,
  "guests": [{
    "first_name": "Susan",
    "last_name": "Doe",
    "email": "sdoe@platform.co",
    "phone": "+14155552671",
    "metadata": []
  }],
  "room": null,
  "location": { ... },
  "items": null,
  "metadata": [],
  "invoice_level_adjustments": []
}

Footer

The footer on a booking is optional (it may be set to null or omitted).

Actions

Merchants have the option to provide useful next actions in the Actions section. On a booking, common actions include 'Manage Reservation,' 'Cancel Booking,' or 'Contact Support.' There is a limit of three actions.

"actions": [
  {
    "name": "Manage Reservation",
    "url": "https://yourco.com/reservations/be1e1b57-8fe9-4729-8b7d-f9a4690bb2cd"
  },
  {
    "name": "Cancel Booking",
    "url": "https://yourco.com/cancel/ad058b82-d0dd-4534-a915-d448df098167"
  }
]

Payments

Payments are optional on a booking — the payments field may be null or omitted entirely when the transaction has not yet been paid. When a payment (e.g. a deposit or a pre-pay) has been collected, record it here as you would on a receipt.

"payments": [
  {
    "paid_at": 1679609767,
    "payment_type": "card",
    "amount": 234,
    "card_payment": {
      "last_four": "7806",
      "network": "mastercard"
    },
    "ach_payment": null
  }
]

Primitives

Foundational objects used throughout the schema. These are identical to the corresponding primitives on the Receipt Schema.

Definitions & Formatting

Currency Values

All API requests expect amounts to be provided in a currency's smallest unit. For example, to represent 10 USD, provide an amount value of 1000 (that is, 1000 cents). For zero-decimal currencies, still provide amounts as an integer but without multiplying by 100. For example, to represent ¥500, provide an amount value of 500.

Images

Images must be hosted at public URLs. The images are likely to be indexed by the receiver. For best results, no image dimension should be less than 400px, or greater than 2,000px.

Cancelations

To mark a booking as canceled, send an update event with header.lifecycle_status set to canceled. You may also send a terminal update with an empty itemization as with a receipt — see the Receipt Cancelations section for details.

{
  "schema_version": "2.3.0",
  "header": {
    "currency": "usd",
    "total": 0,
    "paid": 0,
    "booked_at": 1713295619,
    "lifecycle_status": "canceled"
  },
  "itemization": {},
  "footer": null,
  "payments": null
}