Skip to main content

​
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 -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 }
    ]
  }'

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