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

From capability octo/waitlists.

idstring · uuidRequired

Unique identifier for this resource.

Example: f1a5d2e8-8d57-4f0b-9c3f-6a12d7a8bc90

statusstringRequired

Current status value.

Example: ACTIVE

productIdstringOptional

Product identifier.

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

optionIdstringRequired

Option identifier.

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

localDatestringOptional

Local date in YYYY-MM-DD format.

Example: 2026-05-14

createdAtstringOptional

Created at value.

Example: 2026-05-14T10:00:00Z

uuidstring · nullableOptional

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

supplierReferencestring · nullableOptional

Supplier reference value.

Example: SUP-BOOK-7782

sizeintegerOptional

Size numeric value.

Example: 2

visibleContactFieldsstring[]Optional

List of visible contact field values.

Example: ["fullName","emailAddress"]

requiredContactFieldsstring[]Optional

List of required contact field values.

Example: ["fullName","emailAddress"]

utcCreatedAtstring · date-time · nullableOptional

Utc created at timestamp in ISO 8601 format.

Example: 2026-05-14T13:00:00Z

utcUpdatedAtstring · date-time · nullableOptional

Utc updated at timestamp in ISO 8601 format.

Example: 2026-05-14T13:00:00Z

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"
}

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
}