Create Booking

Create a new booking.

Method

POST /v1/bookings

Body Parameters

code · string

Custom booking code/reference

status · string

Initial status (pending by default)

paymentStatus · string

Initial payment status

fulfillmentStatus · string

Initial fulfillment status

channel · string

Sales channel

source · string

Source system

currency · string

ISO currency (e.g. EUR)

paxAdults · number

Adults count

paxChildren · number

Children count

paxInfants · number

Infants count

roomsCount · number

Number of rooms (if applicable)

billingPersonId · string

Existing person ID for billing contact (TypeID with ppl prefix)

organizationId · string

Existing organization ID (TypeID with org prefix)

observations · string

Public notes

notesInternal · string

Internal notes

attributes · object

Custom attributes

metadata · object

Arbitrary metadata

language · string

Preferred language

productId · string · required

Product to book (TypeID with prod prefix)

departureId · string · required

Departure to book (TypeID with dept prefix)

ratePlanId · string

Override rate plan (TypeID with rate prefix)

addons[].id · string

Addon product identifier (TypeID with prad prefix)

addons[].quantity · number

Addon quantity

rooms[].categoryKey · string

Room category key

rooms[].occupancy · number

Occupancy per room

rooms[].quantity · number

Rooms requested

couponCode · string

Coupon or promotion code

quoteId · string

Quote identifier issued by Voyant (TypeID with qte prefix)

Attributes and metadata

Voyant stores two JSON blobs on every booking: attributes, which the platform extends with workflow state, and metadata, which is left untouched for your own identifiers.

• attributes — send a JSON object with workspace-specific context (for example, the answers from a booking form). The booking service automatically merges in a pricingSnapshot that captures the quote that was used to price the booking.
• metadata — supply any arbitrary JSON you need to round-trip (CRM references, analytics tags, third-party payloads). Voyant never mutates this object.

Example

{
  "attributes": {
    "sourceForm": {
      "version": 3,
      "submittedBy": "csr_7842",
      "customFields": {
        "preferredGuide": "GUIDE-2387",
        "requiresWheelchair": true
      }
    }
  },
  "metadata": {
    "externalReferences": {
      "salesforceOpportunityId": "OPP-0098123",
      "legacyBookingId": "BK-5567"
    },
    "utm": {
      "campaign": "summer-argentina-2025",
      "source": "newsletter"
    }
  }
}

If you omit attributes, Voyant still persists a pricingSnapshot. When you do send an object, avoid overwriting that key unless you intend to replace it.

Totals are calculated on the server from the pricing payload. The booking response includes the computed subtotal, taxes, discounts, and total amount. Items and passengers are created via separate endpoints after the booking is created:

• POST /v1/bookings/:id/items — add items
• POST /v1/bookings/:id/passengers — upsert passengers (by personId)

Headers

Authorization · string · required

Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)

content-type · string

application/json

cURL

curl -X POST https://api.voyantcloud.com/v1/bookings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "currency": "EUR",
    "paxAdults": 2,
    "paxChildren": 1,
    "language": "en",
    "notesInternal": "VIP",
    "productId": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
    "departureId": "dept_01h9xm2n3p4q5r6s7t8v9w0x1y",
    "addons": [
      { "id": "prad_01h9xm3n4p5q6r7s8t9v0w1x2y", "quantity": 1 }
    ],
    "rooms": [
      { "categoryKey": "double", "occupancy": 2, "quantity": 1 }
    ]
  }'

201 Created

{
  "id": "book_01h9xm4n5p6q7r8s9t0v1w2x3y",
  "code": "BKG-2025-0001",
  "status": "pending"
}