> ## 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.

# Save Wizard Session

> Create or update a booking wizard session payload.

## Method

`POST` `/v1/bookings/wizard/session`

## Body Parameters

<ParamField name="id" type="uuid">Existing session ID to update (omit to create a new session).</ParamField>
<ParamField name="userId" type="string">Authenticated user identifier associated with the session.</ParamField>
<ParamField name="visitorId" type="string">Anonymous visitor identifier for guest flows.</ParamField>
<ParamField name="language" type="string">Locale code (2–10 chars) used when rendering documents.</ParamField>
<ParamField name="currency" type="string">ISO currency code (3 letters) used for pricing snapshots.</ParamField>
<ParamField name="step" type="integer">Wizard step index (1–10) indicating current progress.</ParamField>
<ParamField name="version" type="integer">Client-side schema version (0–10) for optimistic locking.</ParamField>
<ParamField name="data" type="object">Arbitrary JSON payload (e.g., `step_1`, `step_2` objects).</ParamField>
<ParamField name="expiresAt" type="string">ISO timestamp to override the default expiry.</ParamField>

## Headers

<ParamField header="Authorization" type="string">Bearer token (requires `bookings:write`).</ParamField>
<ParamField header="content-type" type="string">`application/json`</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.voyantcloud.com/v1/bookings/wizard/session" \
    -H "Authorization: Bearer $VOYANT_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "id": "wzd_01J0C6ZFWN6JQM4TP7A1ZA6X0M",
      "language": "en",
      "currency": "EUR",
      "step": 2,
      "data": {
        "step_1": { "productId": "prod_123", "departureId": "dep_456" },
        "step_2": {
          "departureId": "dep_456",
          "rooms": [{ "categoryKey": "double", "occupancy": 2, "quantity": 1 }]
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.voyantcloud.com/v1/bookings/wizard/session", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      visitorId: "anon_987",
      currency: "USD",
      step: 1,
      data: {
        step_1: {
          productId: "prod_123",
          departureId: "dep_456"
        }
      }
    }),
  })
  const payload = await res.json()
  ```

  ```python Python theme={null}
  import os, requests

  payload = {
    "language": "en-GB",
    "currency": "GBP",
    "step": 3,
    "data": {
      "step_3": {
        "extensions": [
          {"id": "ext_abc", "quantity": 1},
          {"id": "ext_wifi", "quantity": 1}
        ]
      }
    }
  }

  resp = requests.post(
    "https://api.voyantcloud.com/v1/bookings/wizard/session",
    headers={
      "Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}",
      "content-type": "application/json",
    },
    json=payload,
  )
  session_res = resp.json()
  ```
</RequestExample>

## Response Fields

<ResponseField name="id" type="uuid" required>Wizard session identifier.</ResponseField>
<ResponseField name="created" type="boolean">Returned when a new session record was inserted.</ResponseField>
<ResponseField name="upserted" type="boolean">Returned when an existing session was merged.</ResponseField>

## Response Example

<ResponseExample>
  ```json 200 OK theme={null}
  { "id": "wzd_01J0C6ZFWN6JQM4TP7A1ZA6X0M", "upserted": true }
  ```

  ```json 201 Created theme={null}
  { "id": "wzd_01J0C6ZFWN6JQM4TP7A1ZA6X0M", "created": true }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Failed to save wizard session",
    "message": "Missing workspace context"
  }
  ```
</ResponseExample>

<Tip>
  When `id` references a consumed or completed session, the API creates a fresh session and returns the new identifier.
</Tip>