> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Booking
> Create a new booking.
## Method
`POST` `/v1/bookings`
## Body Parameters
Custom booking code/reference
Initial status (`pending` by default)
Initial payment status
Initial fulfillment status
Sales channel
Source system
ISO currency (e.g. EUR)
Adults count
Children count
Infants count
Number of rooms (if applicable)
Existing person ID for billing contact ([TypeID](/concepts/identifiers) with `ppl` prefix)
Existing organization ID ([TypeID](/concepts/identifiers) with `org` prefix)
Public notes
Internal notes
Custom attributes
Arbitrary metadata
Preferred language
Product to book ([TypeID](/concepts/identifiers) with `prod` prefix)
Departure to book ([TypeID](/concepts/identifiers) with `dept` prefix)
Override rate plan ([TypeID](/concepts/identifiers) with `rate` prefix)
Addon product identifier ([TypeID](/concepts/identifiers) with `prad` prefix)
Addon quantity
Room category key
Occupancy per room
Rooms requested
Coupon or promotion code
Quote identifier issued by Voyant ([TypeID](/concepts/identifiers) 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.
```json Example theme={null}
{
"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 itemsPOST /v1/bookings/:id/passengers — upsert passengers (by personId)
## Headers
Bearer token (e.g. Authorization: Bearer YOUR\_API\_KEY)
application/json
```bash cURL theme={null}
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 }
]
}'
```
```javascript Node.js theme={null}
await fetch("https://api.voyantcloud.com/v1/bookings", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}`, "content-type": "application/json" },
body: JSON.stringify({
currency: "EUR",
paxAdults: 2,
paxChildren: 1,
language: "en",
productId: "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
departureId: "dept_01h9xm2n3p4q5r6s7t8v9w0x1y",
rooms: [{ categoryKey: "double", occupancy: 2, quantity: 1 }],
}),
})
```
```python Python theme={null}
import os, requests
requests.post(
"https://api.voyantcloud.com/v1/bookings",
headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}", "content-type": "application/json"},
json={
"currency": "EUR",
"paxAdults": 2,
"paxChildren": 1,
"language": "en",
"productId": "prod_01h8z3y4x2w1v0u9t8s7r6q5p4",
"departureId": "dept_01h9xm2n3p4q5r6s7t8v9w0x1y",
"addons": [{"id": "prad_01h9xm3n4p5q6r7s8t9v0w1x2y", "quantity": 1}],
},
)
```
```json 201 Created theme={null}
{
"id": "book_01h9xm4n5p6q7r8s9t0v1w2x3y",
"code": "BKG-2025-0001",
"status": "pending"
}
```