Waitlists

Create waitlist entries for unavailable dates

To use this capability, add octo/waitlists to your Octo-Capabilities header.

All waitlist paths below are under /octo.

Create Waitlist

post

Creates a waitlist record for a product/option/date and requested unit quantities.

Waitlist creation is checkout-context behavior (the waitlist record requires an associated checkout).

Body

application/json

From capability octo/waitlists.

productIdstringRequired

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681

optionIdstringRequired

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b

availabilityIdstringOptional

Availability identifier (local date or local date-time).

Example: 2026-05-14T09:00:00-04:00

localDatestringOptional

Local date in YYYY-MM-DD format.

Example: 2026-05-14

returnUrlstring · uriOptional

Return url URL.

Example: https://checkout.city-sightseeing.com/return

uuidstringOptional

User-submitted UUID field that can be used to uniquely reference this resource and provide idempotency against repeat requests with the same UUID.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2

resellerReferencestringOptional

Reseller reference value.

Example: RES-BOOK-10045

Responses

200

Returns a Waitlist object.

application/json

post

/waitlists

HTTPcURLJavaScriptPython

POST /octo/waitlists HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 936

{
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
  "availabilityId": "2026-05-14T09:00:00-04:00",
  "localDate": "2026-05-14",
  "units": [
    {
      "id": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "quantity": 2,
      "weightValue": 20,
      "weightUnit": "kg"
    }
  ],
  "contact": {
    "tags": [
      "vip",
      "partner"
    ],
    "fullName": "Jane Doe",
    "title": "Ms",
    "firstName": "Jane",
    "lastName": "Doe",
    "emailAddress": "[email protected]",
    "phoneNumber": "[phone]",
    "age": 34,
    "birthdate": "1992-04-23",
    "streetAddress": "223 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US",
    "locales": [
      "en"
    ],
    "notes": "Vegetarian meal requested",
    "allowMarketing": false,
    "taxId": "US1234567",
    "company": "Golden Gate Tours LLC",
    "photoUrl": "https://images.ventrata.com/profiles/jane-doe.jpg"
  },
  "returnUrl": "https://checkout.city-sightseeing.com/return",
  "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
  "resellerReference": "RES-BOOK-10045"
}

200

Returns a Waitlist object.

{
  "id": "f1a5d2e8-8d57-4f0b-9c3f-6a12d7a8bc90",
  "status": "ACTIVE",
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
  "localDate": "2026-05-14",
  "units": [
    {
      "unitId": "unit_adult",
      "quantity": 2
    }
  ],
  "contact": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "tags": [
      "vip",
      "partner"
    ],
    "fullName": "Jane Doe",
    "title": "Ms",
    "firstName": "Jane",
    "lastName": "Doe",
    "emailAddress": "[email protected]",
    "phoneNumber": "[phone]",
    "age": 34,
    "birthdate": "1992-04-23",
    "streetAddress": "223 Market Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US",
    "locales": [
      "en"
    ],
    "notes": "Vegetarian meal requested",
    "allowMarketing": false,
    "taxId": "US1234567",
    "company": "Golden Gate Tours LLC",
    "photoUrl": "https://images.ventrata.com/profiles/jane-doe.jpg"
  },
  "createdAt": "2026-05-14T10:00:00Z",
  "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
  "supplierReference": "SUP-BOOK-7782",
  "size": 2,
  "visibleContactFields": [
    "fullName",
    "emailAddress"
  ],
  "requiredContactFields": [
    "fullName",
    "emailAddress"
  ],
  "utcCreatedAt": "2026-05-14T13:00:00Z",
  "utcUpdatedAt": "2026-05-14T13:00:00Z"
}

Request Body

At least one non-item unit quantity must resolve to a total waitlist size greater than 0 (entries resolved to item_... do not add to waitlist size).

Response Fields

When personal information masking is enabled on the connection, the same contact fields are returned but personal values are null.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Waitlist

{
  "// ...rest of waitlist object": "...",
  "id": "f1a5d2e8-8d57-4f0b-9c3f-6a12d7a8bc90",
  "status": "ACTIVE",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
  "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
  "localDate": "2026-05-14",
  "units": [
    {
      "unitId": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "quantity": 2
    }
  ],
  "contact": {
    "fullName": "Jane Doe",
    "emailAddress": "[email protected]"
  },
  "createdAt": "2026-05-14T10:00:00Z",
  "uuid": "89fe0192-ddcd-430a-b285-e1396a4725d2",
  "supplierReference": "SUP-BOOK-7782",
  "size": 2,
  "visibleContactFields": [
    "fullName",
    "emailAddress"
  ],
  "requiredContactFields": [
    "fullName",
    "emailAddress"
  ],
  "utcCreatedAt": "2026-05-14T13:00:00Z",
  "utcUpdatedAt": "2026-05-14T13:00:00Z"
}

WaitlistRequest

{
  "// ...rest of waitlist request object": "...",
  "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b"
}

WaitlistUnit

{
  "// ...rest of waitlist unit object": "...",
  "unitId": "unit_adult",
  "quantity": 2
}