API docs by Redocly

Xola API (2025.07.07)

Download OpenAPI specification:

URL: https://developers.xola.com License: Proprietary

Xola booking and experience management platform API.

This API provides comprehensive functionality for managing experiences, bookings, users, events, and all aspects of the booking lifecycle for tour and activity operators.

Authentication

This API supports two authentication mechanisms:

  1. API Key Authentication: Include your API key in the X-API-KEY header
  2. Basic Authentication: Use HTTP Basic authentication with username and password

Use the Authorization header for Basic auth or the X-API-KEY header for API key authentication.

Versioning

Xola's API uses a versioning scheme based on dates. The latest available version is 2025-07-07.

  • Specify the desired API version in the x-api-version header for all requests:

    x-api-version: 2025-07-07

  • Recommended: Always include the x-api-version header in your requests to ensure consistent and predictable responses.

  • If the x-api-version header is not provided, the API will use the version configured for the seller account associated with the request. This default version may differ between seller accounts, which can lead to inconsistent behavior across accounts.

  • For best results and to avoid unexpected changes, always specify the API version explicitly in your requests.

assets

File asset upload and management

Upload an asset file

Uploads a file and stores it as an Asset. Returns the created Asset object.

Supported file types:

  • Images: JPEG, PNG, GIF, WebP
  • Documents: PDF (maximum size 5MB)

The file must be sent as multipart/form-data with the field name file.

Authorization: Requires a valid authenticated user (ROLE_USER).

Authorizations:
apiKeybasicAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

The file to upload (JPEG, PNG, GIF, WebP, or PDF)

Responses

Response samples

Content type
application/json
{}

Abandoned Purchases

Abandoned purchase tracking and recovery

Retrieve list of abandoned purchases

Fetches a paginated list of abandoned purchases for the authenticated seller.

Abandoned purchases are draft purchases that customers started but didn't complete. They're automatically filtered to exclude soft-deleted purchases.

Results are ordered by creation date (newest first).

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

object (DateTimeFilterSchema)
Examples: createdAt[summary]=Find records where field exists (not null)&createdAt[value]=[object Object] createdAt[summary]=Find records where field is null/missing&createdAt[value]=[object Object] createdAt[summary]=Date range filtering&createdAt[value]=[object Object] createdAt[summary]=Range using comma-separated string&createdAt[value]=[object Object] createdAt[summary]=Using period for today&createdAt[value]=[object Object] createdAt[summary]=Using period for last week&createdAt[value]=[object Object] createdAt[summary]=Exact date-time match&createdAt[value]=[object Object] createdAt[summary]=After specific date&createdAt[value]=[object Object]

Filter by creation timestamp. Supports date-time filtering operations.

object (DateTimeFilterSchema)
Examples: updatedAt[summary]=Find records where field exists (not null)&updatedAt[value]=[object Object] updatedAt[summary]=Find records where field is null/missing&updatedAt[value]=[object Object] updatedAt[summary]=Date range filtering&updatedAt[value]=[object Object] updatedAt[summary]=Range using comma-separated string&updatedAt[value]=[object Object] updatedAt[summary]=Using period for today&updatedAt[value]=[object Object] updatedAt[summary]=Using period for last week&updatedAt[value]=[object Object] updatedAt[summary]=Exact date-time match&updatedAt[value]=[object Object] updatedAt[summary]=After specific date&updatedAt[value]=[object Object]

Filter by last update timestamp. Supports date-time filtering operations.

customerEmail
string <email>
Example: customerEmail=john.doe@example.com

Filter by customer email address

customerName
string
Example: customerName=John Doe

Filter by customer name (partial match)

status
string
Default: "abandon"
Value: "abandon"
Example: status=abandon

Filter by purchase status

expand
string
Example: expand=items,reminders

Comma-separated list of fields to expand in response

include
string
Example: include=audits

Comma-separated list of additional fields to include

sort
string
Example: sort=createdAt,-updatedAt

Sort order (comma-separated fields)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Retrieve abandoned purchase by ID

Fetches a specific abandoned purchase by its unique identifier.

This endpoint provides detailed information about an abandoned purchase, including all items, customer information, and associated reminders.

Authentication: Requires either seller authentication OR customer authentication using client secret. When authenticated as a customer, only purchases belonging to that customer are accessible.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Unique identifier of the abandoned purchase

Responses

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "abandon",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerPhone": "+1-555-123-4567",
  • "currency": "USD",
  • "amount": 150,
  • "created": "2024-01-15T14:30:00Z",
  • "updated": "2024-01-15T15:45:00Z",
  • "seller": {
    },
  • "organizer": {
    },
  • "items": [
    ],
  • "reminders": [ ]
}

Update abandoned purchase

Updates specific properties of an abandoned purchase.

This endpoint supports updating the status of individual purchase items, particularly for marking items as "emailed" or "dismissed" for tracking recovery campaign effectiveness.

Authentication: Requires seller authentication only.

Authorizations:
apiKey
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Unique identifier of the abandoned purchase

Request Body schema: application/json
required
required
Array of objects non-empty

Items to update with new status

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "abandon",
  • "internalStatus": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerLocale": "en-US",
  • "customerTimezoneName": "America/New_York",
  • "phone": "+1234567890",
  • "phoneCanonical": "1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "amounts": {
    },
  • "balances": {
    },
  • "balance": 0,
  • "payNow": 50,
  • "dueNow": 50,
  • "minimumDue": 25,
  • "affiliatePayment": 15,
  • "referenceId": "EXT-BOOKING-123",
  • "source": "website",
  • "seller": {
    },
  • "organizer": {
    },
  • "partnerSeller": {
    },
  • "partner": {
    },
  • "affiliate": {
    },
  • "conversation": {
    },
  • "waitlist": {
    },
  • "travelers": [
    ],
  • "items": [
    ],
  • "lineItems": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "reminders": [
    ],
  • "paymentReminders": [
    ],
  • "splitPayment": {
    },
  • "trackingData": {
    },
  • "telemetry": {
    },
  • "meta": { },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "requiresCaptcha": false,
  • "termsAgreedAt": "2023-12-07T10:25:00Z",
  • "releaseHoldAt": "2023-12-07T12:00:00Z",
  • "notifyAt": "2023-12-07T09:00:00Z",
  • "migratedAt": "2023-12-07T08:00:00Z",
  • "commissionRefundProcessedAt": "2023-12-07T16:00:00Z",
  • "rollbackReason": "payment_failed",
  • "draftCreatedAt": "2024-01-15T09:30:00Z",
  • "convertedAt": "2024-01-15T10:45:00Z",
  • "deletedAt": "2024-01-15T11:00:00Z",
  • "deletedBy": {
    }
}

Affiliates

Affiliates are partners who make bookings on behalf of guests where there is either a discounting or commission component to the relationship. Each affiliate is given a unique code so that you can track commissions, accounts receivable, and accounts payable for each affiliate.

List affiliates

Retrieve a list of affiliates. Access is controlled based on authentication and authorization.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

expand
string
Value: "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

code
string
Example: code=JTA001

Filter affiliates by their internal code. This performs a case-insensitive exact match. When used without authentication, only exact matches are returned. When used with authentication, partial matches may be supported.

status
string
Enum: "active" "inactive" "pending"
Example: status=active

Filter affiliates by their current status

seller
string
Example: seller=507f1f77bcf86cd799439011

Filter affiliates by seller ID (required when using code filter without authentication)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create affiliate

Create a new affiliate for the authenticated user's seller account.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required

Affiliate data to create

object
string

Object type identifier

Value: "affiliate"
name
required
string

Full name of the affiliate

email
string or null <email>

Email address of the affiliate

code
string or null

Internal code referring to this affiliate (cannot contain spaces, quotes, <, >, &)

status
required
string
Enum: "active" "inactive" "pending"

Current status of the affiliate:

  • active: Affiliate is active and can generate bookings
  • inactive: Affiliate is deactivated
  • pending: Affiliate registration is pending approval
phone
string or null

Phone number of the affiliate

address
string or null

Physical address of the affiliate

url
string or null <uri>

Website URL of the affiliate

notes
string or null

Internal notes about the affiliate

allowChildren
boolean

Whether this affiliate is allowed to create child affiliates

children
Array of strings or null

List of child affiliate IDs that report under this affiliate

parent
string or null

ID of the parent affiliate if this is a child affiliate

voucher
boolean

Whether this affiliate operates as a voucher-based partner

delegated
boolean

Whether this affiliate has delegated access rights

purchaseRulesPermanentIds
Array of strings or null

List of purchase rule permanent IDs associated with this affiliate

required
object (ObjectReference)

Seller this affiliate belongs to

Responses

Request samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    },
  • "id": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2023-07-15T10:30:00Z",
  • "createdBy": {
    },
  • "updatedAt": "2023-07-20T14:45:00Z",
  • "updatedBy": {
    },
  • "deletedAt": null,
  • "deletedBy": {
    }
}

Get affiliate

Retrieve a specific affiliate by ID.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Value: "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

Responses

Response samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    },
  • "id": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2023-07-15T10:30:00Z",
  • "createdBy": {
    },
  • "updatedAt": "2023-07-20T14:45:00Z",
  • "updatedBy": {
    },
  • "deletedAt": null,
  • "deletedBy": {
    }
}

Update affiliate

Update an existing affiliate's information.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Updated affiliate data

object
string

Object type identifier

Value: "affiliate"
name
required
string

Full name of the affiliate

email
string or null <email>

Email address of the affiliate

code
string or null

Internal code referring to this affiliate (cannot contain spaces, quotes, <, >, &)

status
required
string
Enum: "active" "inactive" "pending"

Current status of the affiliate:

  • active: Affiliate is active and can generate bookings
  • inactive: Affiliate is deactivated
  • pending: Affiliate registration is pending approval
phone
string or null

Phone number of the affiliate

address
string or null

Physical address of the affiliate

url
string or null <uri>

Website URL of the affiliate

notes
string or null

Internal notes about the affiliate

allowChildren
boolean

Whether this affiliate is allowed to create child affiliates

children
Array of strings or null

List of child affiliate IDs that report under this affiliate

parent
string or null

ID of the parent affiliate if this is a child affiliate

voucher
boolean

Whether this affiliate operates as a voucher-based partner

delegated
boolean

Whether this affiliate has delegated access rights

purchaseRulesPermanentIds
Array of strings or null

List of purchase rule permanent IDs associated with this affiliate

required
object (ObjectReference)

Seller this affiliate belongs to

Responses

Request samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    },
  • "id": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2023-07-15T10:30:00Z",
  • "createdBy": {
    },
  • "updatedAt": "2023-07-20T14:45:00Z",
  • "updatedBy": {
    },
  • "deletedAt": null,
  • "deletedBy": {
    }
}

Delete affiliate

Soft delete an affiliate.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Pay affiliate

Create a payment transaction to pay an affiliate.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Payment transaction details

amount
required
number <float>

Transaction amount (positive for collect, will be negated for pay operations)

description
string or null

Description of the transaction

reference
string or null

External reference for the transaction

Responses

Request samples

Content type
application/json
{
  • "amount": 100.5,
  • "description": "Commission payment for July bookings",
  • "reference": "PAY-2023-001"
}

Response samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    },
  • "id": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2023-07-15T10:30:00Z",
  • "createdBy": {
    },
  • "updatedAt": "2023-07-20T14:45:00Z",
  • "updatedBy": {
    },
  • "deletedAt": null,
  • "deletedBy": {
    }
}

Collect from affiliate

Create a collection transaction to collect money from an affiliate.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Collection transaction details

amount
required
number <float>

Transaction amount (positive for collect, will be negated for pay operations)

description
string or null

Description of the transaction

reference
string or null

External reference for the transaction

Responses

Request samples

Content type
application/json
{
  • "amount": 100.5,
  • "description": "Commission payment for July bookings",
  • "reference": "PAY-2023-001"
}

Response samples

Content type
application/json
{
  • "object": "affiliate",
  • "name": "John's Travel Agency",
  • "email": "john@travelagency.com",
  • "code": "JTA001",
  • "status": "active",
  • "phone": "+1234567890",
  • "address": "123 Main St, City, State 12345",
  • "url": "https://www.travelagency.com",
  • "notes": "Preferred partner for corporate bookings",
  • "allowChildren": false,
  • "children": [
    ],
  • "parent": "60f7b3c4e4b0a1234567890d",
  • "voucher": false,
  • "delegated": true,
  • "purchaseRulesPermanentIds": [
    ],
  • "seller": {
    },
  • "id": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2023-07-15T10:30:00Z",
  • "createdBy": {
    },
  • "updatedAt": "2023-07-20T14:45:00Z",
  • "updatedBy": {
    },
  • "deletedAt": null,
  • "deletedBy": {
    }
}

api-key-users

API key user management for programmatic access

Create a new API key user

Create a new named API key user for the specified seller. An API key is automatically generated and assigned to the user. The API key user can then authenticate using the generated key via the X-API-KEY header.

Authorization Requirements:

  • Must have CREATE_API_KEY_USER permission on the seller

Validation Rules:

  • name is required and must be unique (case-insensitive) among all delegates of the seller
  • roles is required and must contain at least one valid role
  • Only the restricted set of API key allowed roles can be assigned

Behavior:

  • Creates the API key user document with type 4
  • Generates an API key automatically
  • Assigns ROLE_API_KEY as a direct role
  • Creates a delegate on the seller with the specified permissions
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID to create the API key user for

Request Body schema: application/json
required
name
required
string

Human-readable name for the API key user. Must be unique (case-insensitive) among all delegates of the seller.

roles
required
Array of strings
Items Enum: "ROLE_RESERVATION" "ROLE_GUIDE_MANAGER" "ROLE_ACCOUNTANT" "ROLE_CURATOR" "ROLE_GUIDE" "ROLE_SELLER_ADMIN" "ROLE_RESERVATION_LITE" "ROLE_MARKETER" "ROLE_EQUIPMENT_MANAGER"

List of permission roles to assign. At least one role is required. Only the following roles are allowed for API key users:

  • ROLE_RESERVATION - Booking and reservation management
  • ROLE_GUIDE_MANAGER - Guide management and scheduling
  • ROLE_ACCOUNTANT - Financial and accounting access
  • ROLE_CURATOR - Content and experience management
  • ROLE_GUIDE - Guide-specific access
  • ROLE_SELLER_ADMIN - Full administrative access
  • ROLE_RESERVATION_LITE - Limited reservation access
  • ROLE_MARKETER - Marketing and promotion tools
  • ROLE_EQUIPMENT_MANAGER - Equipment and resource management

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My Integration",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "api_key_user",
  • "type": 4,
  • "name": "My Integration",
  • "enabled": true,
  • "seller": {
    },
  • "roles": [
    ]
}

List all API key users for a seller

Retrieve a list of all API key users for the specified seller. The API keys in the response are masked (only first 4 characters shown, followed by ******).

Authorization Requirements:

  • Must have VIEW_API_KEY_USERS permission on the seller

Note: To retrieve the full (unmasked) API key, use the single GET endpoint (GET /sellers/{id}/apiKeys/{apiKeyId}).

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID to list API key users for

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Get a specific API key user

Retrieve details for a specific API key user, including the full (unmasked) API key.

Authorization Requirements:

  • Must have VIEW_API_KEY_USERS permission on the seller

Important: This is the only endpoint that returns the full API key value. The list endpoint returns masked keys.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID that owns the API key user

apiKeyId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the API key user to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "object": "api_key_user",
  • "type": 4,
  • "name": "My Integration",
  • "enabled": true,
  • "seller": {
    },
  • "roles": [
    ],
  • "apiKey": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Update an API key user

Update the name or enabled status of an API key user.

Authorization Requirements:

  • Must have EDIT_API_KEY_USER permission on the seller

Note: Permissions/roles are NOT updated through this endpoint. Use the dedicated permission endpoints to add or remove permissions:

  • PUT /sellers/{id}/apiKeys/{apiKeyId}/permissions/{permissionId} to add a permission
  • DELETE /sellers/{id}/apiKeys/{apiKeyId}/permissions/{permissionId} to remove a permission
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID that owns the API key user

apiKeyId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the API key user to update

Request Body schema: application/json
required
name
string

Updated human-readable name for the API key user

enabled
boolean

Enable or disable the API key user

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Updated Integration Name"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "object": "api_key_user",
  • "type": 4,
  • "name": "Updated Integration Name",
  • "enabled": true,
  • "seller": {
    },
  • "roles": [
    ]
}

Delete an API key user

Delete an API key user and revoke their access. This permanently removes the API key user's delegate from the seller, nulls out the API key, and disables the user account.

Authorization Requirements:

  • Must have DELETE_API_KEY_USER permission on the seller

Side Effects:

  • Removes the delegate entry from the seller
  • Nulls out the API key field on the user document
  • Sets the user to disabled
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID that owns the API key user

apiKeyId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the API key user to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Add a permission to an API key user

Grant a specific permission to an API key user. The permission must be from the restricted set of roles allowed for API key users.

Authorization Requirements:

  • Must have EDIT_API_KEY_USER permission on the seller

Allowed Permissions:

  • ROLE_RESERVATION - Booking and reservation management
  • ROLE_GUIDE_MANAGER - Guide management and scheduling
  • ROLE_ACCOUNTANT - Financial and accounting access
  • ROLE_CURATOR - Content and experience management
  • ROLE_GUIDE - Guide-specific access
  • ROLE_SELLER_ADMIN - Full administrative access
  • ROLE_RESERVATION_LITE - Limited reservation access
  • ROLE_MARKETER - Marketing and promotion tools
  • ROLE_EQUIPMENT_MANAGER - Equipment and resource management
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID that owns the API key user

apiKeyId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the API key user

permissionId
required
string
Enum: "ROLE_RESERVATION" "ROLE_GUIDE_MANAGER" "ROLE_ACCOUNTANT" "ROLE_CURATOR" "ROLE_GUIDE" "ROLE_SELLER_ADMIN" "ROLE_RESERVATION_LITE" "ROLE_MARKETER" "ROLE_EQUIPMENT_MANAGER"
Example: ROLE_CURATOR

The permission role to add

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Remove a permission from an API key user

Remove a specific permission from an API key user.

Authorization Requirements:

  • Must have EDIT_API_KEY_USER permission on the seller
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

Seller ID that owns the API key user

apiKeyId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the API key user

permissionId
required
string
Enum: "ROLE_RESERVATION" "ROLE_GUIDE_MANAGER" "ROLE_ACCOUNTANT" "ROLE_CURATOR" "ROLE_GUIDE" "ROLE_SELLER_ADMIN" "ROLE_RESERVATION_LITE" "ROLE_MARKETER" "ROLE_EQUIPMENT_MANAGER"
Example: ROLE_CURATOR

The permission role to remove

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Blackout Schedules

Blackout schedule management for experiences and resources

Get user blackout schedules

Retrieve all blackout schedules for a specific user. Blackout schedules define periods when experiences are unavailable.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Create user blackout schedule

Create a new blackout schedule for a user. This is the primary endpoint. Blackout schedules automatically set the type to 'unavailable' and affect all user experiences.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

Request Body schema: application/json
required

Blackout schedule data to create

name
string

Human readable name for the blackout schedule

repeat
required
string
Enum: "weekly" "custom"

The repeating frequency of this blackout schedule

days
Array of integers[ items [ 0 .. 6 ] ]

Days of the week for weekly schedules. 0 = Sunday, 6 = Saturday

start
string <date>

Start date in YYYY-MM-DD format

end
string or null <date>

End date in YYYY-MM-DD format, or null for no end date

dates
Array of strings <date> [ items <date >^(19|20)\d\d-(0[1-9]|1[012])-(0[1-9]|[12][0-9... ]

Custom dates in YYYY-MM-DD format (required if repeat = "custom")

Array of objects (TimeRange)

Optional time ranges for more granular blackout control

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Weekday Maintenance",
  • "repeat": "weekly",
  • "days": [
    ],
  • "start": "2024-12-01",
  • "end": "2024-12-31"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439014",
  • "name": "Weekday Maintenance",
  • "repeat": "weekly",
  • "days": [
    ],
  • "start": "2024-12-01T00:00:00-08:00",
  • "end": "2024-12-31T23:59:59-08:00",
  • "type": "unavailable",
  • "timeRanges": [ ],
  • "createdAt": "2024-01-16T15:30:00Z",
  • "updatedAt": "2024-01-16T15:30:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    }
}

Update user blackout schedule

Update an existing blackout schedule for a user. All provided fields will be updated, and any omitted fields will retain their current values.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

scheduleId
required
string
Example: 507f1f77bcf86cd799439013

Unique identifier for the blackout schedule

Request Body schema: application/json
required

Blackout schedule data to update

name
string

Human readable name for the blackout schedule

repeat
string
Enum: "weekly" "custom"

The repeating frequency of this blackout schedule

days
Array of integers[ items [ 0 .. 6 ] ]

Days of the week for weekly schedules. 0 = Sunday, 6 = Saturday

start
string <date>

Start date in YYYY-MM-DD format

end
string or null <date>

End date in YYYY-MM-DD format, or null for no end date

dates
Array of strings <date> [ items <date >^(19|20)\d\d-(0[1-9]|1[012])-(0[1-9]|[12][0-9... ]

Custom dates in YYYY-MM-DD format (applicable if repeat = "custom")

type
string
Value: "unavailable"

Blackout schedules are always unavailable type (may be included in request)

Array of objects (TimeRange)

Time ranges for granular blackout control

Responses

Request samples

Content type
application/json
Example
{
  • "dates": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "68a2d4524046afeb370e0e98",
  • "name": "Updated Schedule",
  • "days": [
    ],
  • "start": "2025-08-30T00:00:00-04:00",
  • "repeat": "weekly",
  • "type": "unavailable",
  • "createdAt": "2025-08-18T07:20:50+00:00",
  • "updatedAt": "2025-08-29T13:00:02+00:00",
  • "timeRanges": [
    ]
}

Delete user blackout schedule

Delete an existing blackout schedule for a user. This will remove the blackout and make previously blocked times available again according to other schedules.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

scheduleId
required
string
Example: 507f1f77bcf86cd799439013

Unique identifier for the blackout schedule to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get user blackout schedules (alternative endpoint)

Alternative endpoint to retrieve all blackout schedules for a specific user. Same functionality as /blackout but with different URL pattern.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create user blackout schedule (alternative endpoint)

Alternative endpoint for creating a new blackout schedule for a user. This endpoint only creates new schedules and does not update existing ones.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier for the user

Request Body schema: application/json
required

Blackout schedule data to create

name
string

Human readable name for the blackout schedule

repeat
required
string
Enum: "weekly" "custom"

The repeating frequency of this blackout schedule

days
Array of integers[ items [ 0 .. 6 ] ]

Days of the week for weekly schedules. 0 = Sunday, 6 = Saturday

start
string <date>

Start date in YYYY-MM-DD format

end
string or null <date>

End date in YYYY-MM-DD format, or null for no end date

dates
Array of strings <date> [ items <date >^(19|20)\d\d-(0[1-9]|1[012])-(0[1-9]|[12][0-9... ]

Custom dates in YYYY-MM-DD format (required if repeat = "custom")

Array of objects (TimeRange)

Optional time ranges for more granular blackout control

Responses

Request samples

Content type
application/json
Example
{
  • "repeat": "weekly",
  • "days": [
    ],
  • "start": "2076-12-14",
  • "end": "2076-12-14"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439015",
  • "repeat": "weekly",
  • "days": [
    ],
  • "start": "2076-12-14T00:00:00-10:00",
  • "end": "2076-12-14T23:59:59-10:00",
  • "type": "unavailable",
  • "timeRanges": [ ],
  • "createdAt": "2024-01-16T17:00:00Z",
  • "updatedAt": "2024-01-16T17:00:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    }
}

Update user blackout schedule (alternative endpoint)

Alternative endpoint for updating an existing blackout schedule for a user. This endpoint matches the actual API usage pattern with /blackoutSchedules.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 65bbde2d1b8c18afc407eee6

Unique identifier for the user

scheduleId
required
string
Example: 68a2d4524046afeb370e0e98

Unique identifier for the blackout schedule

query Parameters
seller
string
Example: seller=65bbde2d1b8c18afc407eee6

Seller ID for authorization context

Request Body schema: application/json
required

Blackout schedule data to update

name
string

Human readable name for the blackout schedule

repeat
string
Enum: "weekly" "custom"

The repeating frequency of this blackout schedule

days
Array of integers[ items [ 0 .. 6 ] ]

Days of the week for weekly schedules. 0 = Sunday, 6 = Saturday

start
string <date>

Start date in YYYY-MM-DD format

end
string or null <date>

End date in YYYY-MM-DD format, or null for no end date

dates
Array of strings <date> [ items <date >^(19|20)\d\d-(0[1-9]|1[012])-(0[1-9]|[12][0-9... ]

Custom dates in YYYY-MM-DD format (applicable if repeat = "custom")

type
string
Value: "unavailable"

Blackout schedules are always unavailable type (may be included in request)

Array of objects (TimeRange)

Time ranges for granular blackout control

Responses

Request samples

Content type
application/json
{
  • "id": "68a2d4524046afeb370e0e98",
  • "days": [
    ],
  • "start": "2025-08-30",
  • "repeat": "weekly",
  • "type": "unavailable",
  • "createdAt": "2025-08-18T03:20:50-04:00",
  • "updatedAt": "2025-08-29T08:13:15-04:00",
  • "name": "name",
  • "timeRanges": [
    ],
  • "end": null
}

Response samples

Content type
application/json
{
  • "id": "68a2d4524046afeb370e0e98",
  • "name": "name",
  • "days": [
    ],
  • "start": "2025-08-30T00:00:00-04:00",
  • "repeat": "weekly",
  • "type": "unavailable",
  • "createdAt": "2025-08-18T07:20:50+00:00",
  • "updatedAt": "2025-08-29T13:00:02+00:00",
  • "timeRanges": [
    ]
}

Delete user blackout schedule (alternative endpoint)

Alternative endpoint for deleting an existing blackout schedule for a user. This endpoint matches the /blackoutSchedules URL pattern.

Authorizations:
apiKeybasicAuth
path Parameters
userId
required
string
Example: 65bbde2d1b8c18afc407eee6

Unique identifier for the user

scheduleId
required
string
Example: 68a2d4524046afeb370e0e98

Unique identifier for the blackout schedule to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Buttons

Buttons allow you to logically group experiences or gifts for use on websites and are a great way to have themed landing pages with checkout offerings mirroring the theme.

Each button can be embedded on your website by following the instructions to implement our JavaScript-based checkout widget.

Xola offers four kinds of online checkout options:

  • Single Item Checkout: Pulls up checkout for one listing.
  • Multi-Item Checkout: You choose which listings should appear for checkout in this button, and your customers can check out for more than one listing at a time.
  • Timeline Checkout: A scrollable timeline that shows upcoming trip times across all of your listings. You choose which listings appear in checkout for this button.
  • Gifts Checkout: Pulls up the listings you offer for Gifts as well as a custom dollar amount. Your customers can purchase these gifts and send them to recipients.

List all buttons

Retrieve all buttons for a seller with optional filtering

Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string

Filter by seller ID

type
string
Enum: "gift" "checkout" "timeline" "day"

Filter by button type

expand
string

Expand related objects. You can expand multiple objects by providing a comma-separated list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new button

Create a new button for a seller

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
name
required
string

Name of the button

type
required
string
Enum: "gift" "checkout" "timeline" "day"

Type of button

required
object (ObjectReference)

Reference to the seller

Array of objects (ButtonItemRequest)

List of items in this button

autoApplyCode
string or null

Coupon code to auto-apply when button is used

CheckoutPreference (object) or null

Checkout preferences for this button. Overrides seller-level checkout preferences when set. Set to null to clear and fall back to seller-level preferences.

Responses

Request samples

Content type
application/json
{
  • "name": "Summer Tours",
  • "type": "checkout",
  • "seller": {
    },
  • "items": [
    ],
  • "autoApplyCode": null,
  • "checkoutPreference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "button",
  • "name": "Summer Tours",
  • "type": "checkout",
  • "seller": {
    },
  • "items": [
    ],
  • "autoApplyCode": null,
  • "createdAt": "2024-01-15T10:30:00+00:00",
  • "createdBy": {
    },
  • "updatedAt": "2024-01-15T10:30:00+00:00"
}

Get a specific button

Retrieve a button by its ID.

This endpoint is publicly accessible and cached for performance.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
seller
string (id) ^[0-9a-fA-F]{24}$
Example: seller=507f191e810c19729de860ea

Seller ID. When provided, the button is returned in the context of this seller. For partner experiences, this authorizes the seller's access to the product and enriches the response with seller.id and product.partner.id on items where the product belongs to a different seller. Returns 403 if the seller is not authorized to access the product.

expand
string

Expand related objects. You can expand multiple objects by providing a comma-separated list.

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "button",
  • "name": "Summer Tours",
  • "type": "checkout",
  • "seller": {
    },
  • "items": [
    ],
  • "autoApplyCode": "SUMMER20",
  • "checkoutPreference": {
    },
  • "createdAt": "2024-01-15T10:30:00+00:00",
  • "createdBy": {
    },
  • "updatedAt": "2024-01-20T14:00:00+00:00",
  • "updatedBy": {
    }
}

Update a button

Update an existing button

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
string

Name of the button

type
string
Enum: "gift" "checkout" "timeline" "day"

Type of button

Array of objects (ButtonItemRequest)

List of items in this button

autoApplyCode
string or null

Coupon code to auto-apply when button is used

CheckoutPreference (object) or null

Checkout preferences for this button. Overrides seller-level checkout preferences when set. Set to null to clear and fall back to seller-level preferences.

Responses

Request samples

Content type
application/json
{
  • "name": "Summer Tours - Updated",
  • "items": [
    ],
  • "autoApplyCode": "SUMMER25",
  • "checkoutPreference": {
    }
}

Response samples

Content type
application/json
{
  • "name": "Summer Tours",
  • "type": "checkout",
  • "seller": {
    },
  • "autoApplyCode": "SUMMER20",
  • "id": "507f1f77bcf86cd799439011",
  • "object": "button",
  • "items": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": {
    },
  • "checkoutPreference": {
    },
  • "archivedAt": "2019-08-24T14:15:22Z",
  • "archivedBy": {
    }
}

Archive a button

Soft delete a button (sets archivedAt timestamp)

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{ }

catalog-items

Catalog item management for experiences and products

List catalog items

Retrieve a paginated list of catalog items with optional filtering

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

seller
string
Example: seller=507f1f77bcf86cd799439011

Filter by seller ID

product
string
Example: product=507f1f77bcf86cd799439011

Filter by product ID

unitType
string
Enum: "demographic" "merchandise" "pickup" "membership"
Example: unitType=demographic

Filter by unit type

type
string
Enum: "quantity" "choices" "boolean"
Example: type=quantity

Filter by catalog item type

visibility
string
Enum: "public" "private"
Example: visibility=public

Filter by visibility level

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": null
}

Create a new catalog item

Create a new global or product-specific catalog item

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
One of
name
required
string

Display name of the catalog item

type
required
string
Enum: "quantity" "choices" "choices_item" "boolean"

Type of catalog item input control

unitType
required
string
Enum: "demographic" "merchandise" "pickup" "membership"

Unit type classification for the catalog item

object
required
string

Discriminator field identifying the catalog item type

Value: "global_catalog_item"
required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

caption
string

Additional descriptive text for the catalog item

visibility
string
Default: "public"
Enum: "public" "private" "none"

Visibility level of the catalog item. Use none to hide from all views.

required
boolean
Default: false

Whether this catalog item is required for purchase

sequence
integer >= 0

Sort order sequence for displaying catalog items

defaultChoice
string

Default selection for choice-type catalog items

Responses

Request samples

Content type
application/json
{
  • "name": "Adults",
  • "type": "quantity",
  • "unitType": "demographic",
  • "object": "global_catalog_item",
  • "seller": {
    },
  • "template": {
    },
  • "caption": "Adult participants",
  • "required": false,
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "global_catalog_item",
  • "name": "Adults",
  • "type": "quantity",
  • "caption": "Adult participants",
  • "unitType": "demographic",
  • "template": {
    },
  • "seller": {
    },
  • "required": false,
  • "visibility": "public",
  • "createdBy": {
    },
  • "createdAt": "2024-02-01T18:08:45+00:00",
  • "updatedAt": "2024-02-01T18:08:45+00:00"
}

Bulk update catalog items

Bulk update ware catalog items (price, SKU, barcode, status) using an ops array.

All catalog items in the batch must belong to the same seller and the same ware. The ware must not have updatesPending set to true.

Validation Rules:

  • Each operation must have a unique id (alphanumeric, hyphens, underscores), op: "update", and a data object with id plus at least one additional field.
  • Op id values must not be duplicated across operations.
  • Catalog item IDs must not be duplicated across operations.
  • Stale catalog items cannot be updated.
  • SKU must be unique per seller (checked within batch and against existing records).
  • Status transitions: only draft ↔ published are allowed. Publishing requires both a price and a SKU.
  • pricePerUnit.price must be non-negative.
  • strikeThroughPrice must be non-negative if provided.

Authorization:

  • Requires ROLE_USER with EDIT_CATALOG_ITEM permission.
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
Array of objects non-empty

Array of update operations to perform. All items must belong to the same seller and ware.

Responses

Request samples

Content type
application/json
{
  • "ops": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get catalog item by ID

Retrieve a specific catalog item by its unique identifier.

Ware catalog items: Returns a 422 validation error if the item has status: "stale".

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "product_catalog_item",
  • "name": "Adults",
  • "type": "quantity",
  • "caption": "Caption Adult",
  • "unitType": "demographic",
  • "template": {
    },
  • "seller": {
    },
  • "required": false,
  • "visibility": "public",
  • "createdBy": {
    },
  • "createdAt": "2024-02-01T18:08:45+00:00",
  • "updatedAt": "2025-03-04T13:45:31+00:00",
  • "overrideParent": false,
  • "parent": {
    },
  • "product": {
    },
  • "prices": {
    },
  • "sequence": 10000
}

Update catalog item

Update an existing catalog item by ID.

Ware catalog items (ware_catalog_item):

  • Allowed update fields: status, photo, pricePerUnit, strikeThroughPrice, barcode, sku. Unknown keys are rejected.
  • Returns 422 with reason updates_pending if the parent ware has pending updates or is locked.
  • Stale (status: "stale") and deleted (status: "deleted") items cannot be updated.
  • Status transitions: only draft ↔ published are allowed. Publishing requires both a valid price and a SKU.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
string

Display name of the catalog item

caption
string

Additional descriptive text for the catalog item

visibility
string
Enum: "public" "private"

Visibility level of the catalog item

required
boolean

Whether this catalog item is required for purchase

sequence
integer >= 0

Sort order sequence for displaying catalog items

defaultChoice
string

Default selection for choice-type catalog items

price
number <float> >= 0

Price override for this catalog item

overrideParent
boolean

Whether this item overrides its global parent

status
string
Enum: "draft" "published"

Status of the ware catalog item. Only draft ↔ published transitions are allowed. Publishing requires both a valid price and a SKU.

sku
string

Stock keeping unit identifier. Must be unique per seller. Required to publish.

string or null

Barcode for the catalog item

object

Price per unit for ware catalog items

number or null

Display-only original price (for showing discounts)

Responses

Request samples

Content type
application/json
{
  • "name": "Adults updated name",
  • "caption": "Updated caption",
  • "price": 50,
  • "sequence": 10050000
}

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "product_catalog_item",
  • "name": "Adults updated name",
  • "type": "quantity",
  • "caption": "Updated caption",
  • "unitType": "demographic",
  • "template": {
    },
  • "seller": {
    },
  • "required": false,
  • "visibility": "public",
  • "createdBy": {
    },
  • "createdAt": "2024-02-01T18:08:45+00:00",
  • "updatedAt": "2025-03-04T13:45:31+00:00",
  • "sequence": 10050000
}

Delete catalog item

Soft delete a catalog item by ID. The item will be marked as deleted but not permanently removed. If the catalog item is linked to products, the deletion will be rejected with a 409 conflict error.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
cascade
boolean
Default: false

Whether to cascade delete related items

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Add media to catalog item

Upload and attach a photo to a catalog item

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Image file to upload

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get catalog item photo

Retrieve the photo for a catalog item. Returns a redirect to the actual image URL. Supports optional size parameter for image resizing.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
size
string
Example: size=bg

Image size filter:

  • bg: Large blurred image suitable for backgrounds
  • Other values may resize the image accordingly

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get catalog item media by ID

Retrieve a specific media item for a catalog item by media ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string
Example: 507f1f77bcf86cd799439011

Media ID to retrieve

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Delete catalog item media

Remove a specific media item from a catalog item

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string
Example: 507f1f77bcf86cd799439011

Media ID to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

collectionNodes

Collection node management

List collection nodes

Retrieve a paginated list of collection nodes.

Authorization:

  • Authenticated users see collection nodes for their own seller and any sellers they are delegated to (with ROLE_SELLER_ADMIN, ROLE_CURATOR, ROLE_RESERVATION, or ROLE_MARKETER permissions) where the seller has ROLE_PRODUCT_COLLECTIONS enabled.
  • Admin users can see collection nodes for any seller.
  • If no seller filter is specified, the user must be authenticated.
Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

seller
string
Example: seller=507f1f77bcf86cd799439011

Filter by seller ID

object
string
Enum: "group_collection_node" "product_collection_node" "catalog_item_collection_node"
Example: object=group_collection_node

Filter by collection node type

product
string
Example: product=507f1f77bcf86cd799439011

Filter by product ID (for product_collection_node)

catalogItem
string
Example: catalogItem=507f1f77bcf86cd799439011

Filter by catalog item ID (for catalog_item_collection_node)

path
string
Example: path=507f1f77bcf86cd799439011

Filter by node path (exact match or prefix)

expand
string
Example: expand=children

Comma-separated list of fields to expand

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": null
}

Create a collection node

Create a new collection node. Supports group nodes (for organizing other nodes) as well as product and catalog item leaf nodes.

Group collection nodes may include a children array to create child nodes in the same request.

Authorization:

  • Requires ROLE_USER.
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
object
required
string
Enum: "group_collection_node" "product_collection_node" "catalog_item_collection_node"

The type of collection node to create

name
string

Display name of the collection node

description
string

Optional description

sequence
integer

Ordering sequence number (auto-assigned if not provided)

path
string

Hierarchical path of ancestor IDs. Omit for root-level nodes.

required
object (CollectionNodeSeller)

Seller reference

object (CollectionNodeProduct)

Product reference

object (CollectionNodeCatalogItem)

Catalog item reference

children
Array of objects (CollectionNodeRequest)

Child nodes to create (only valid for group_collection_node)

Responses

Request samples

Content type
application/json
{
  • "object": "group_collection_node",
  • "name": "Summer Collection",
  • "description": "Products for the summer season",
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "group_collection_node",
  • "name": "Summer Collection",
  • "description": "Products for the summer season",
  • "sequence": 101000,
  • "seller": {
    },
  • "createdAt": "2025-01-15T10:00:00+00:00",
  • "updatedAt": "2025-01-15T10:00:00+00:00"
}

Bulk operations on collection nodes

Perform bulk create and/or delete operations on collection nodes.

Each operation in ops must include a client-supplied id (for identifying errors in the response), an op type (create or delete), and a data object.

Supported operations:

  • create: Create a new collection node. data must include object and other required create fields. Only product_collection_node and catalog_item_collection_node are supported for bulk create.
  • delete: Delete an existing collection node by data.id.

Op id rules:

  • Each id must be a non-empty string of letters, digits, hyphens, or underscores.
  • id values must be unique within the request.

Error handling:

  • If one or more operations fail, a 422 response is returned with details keyed by op id. Individual operation errors include the op id and error information.

Authorization:

  • Requires ROLE_USER.
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
Array of objects non-empty

Array of operations to perform

Responses

Request samples

Content type
application/json
{
  • "ops": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get collection node by ID

Retrieve a specific collection node by its unique identifier.

Authorization:

  • Requires VIEW_COLLECTION_NODE permission on the node.
  • The seller must have ROLE_PRODUCT_COLLECTIONS enabled.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Example: expand=children

Comma-separated list of fields to expand

Responses

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "group_collection_node",
  • "name": "Summer Collection",
  • "description": "Products for the summer season",
  • "sequence": 101000,
  • "seller": {
    },
  • "childrenCount": {
    },
  • "createdAt": "2025-01-15T10:00:00+00:00",
  • "updatedAt": "2025-01-15T10:00:00+00:00"
}

Update a collection node

Update an existing collection node by ID.

Allowed fields: name, description, sequence, photo, path. For group_collection_node, children updates are also allowed.

Authorization:

  • Requires EDIT_COLLECTION_NODE permission on the node.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Example: expand=children

Comma-separated list of fields to expand

Request Body schema: application/json
required
name
string

Display name of the collection node

description
string

Optional description

sequence
integer

Ordering sequence number

path
string

Hierarchical path (used to move node to a different parent)

Media (object) or null

Set to null to remove the photo (group nodes only)

Array of objects

Child node operations (only valid for group_collection_node). Each item must include an operation field (create, update, delete) and data.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Summer Collection",
  • "description": "Updated description",
  • "sequence": 102000
}

Response samples

Content type
application/json
{
  • "id": "6721deb1accdc7036a0dd34b",
  • "object": "group_collection_node",
  • "name": "Updated Summer Collection",
  • "description": "Updated description",
  • "sequence": 102000,
  • "seller": {
    },
  • "createdAt": "2025-01-15T10:00:00+00:00",
  • "updatedAt": "2025-01-16T09:00:00+00:00"
}

Delete a collection node

Soft delete a collection node by ID.

For group_collection_node, all descendant nodes are also deleted recursively.

Authorization:

  • Requires DELETE_COLLECTION_NODE permission on the node.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Add photo to collection node

Upload and attach a photo to a group collection node.

Authorization:

  • Requires EDIT_COLLECTION_NODE permission on the node.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: multipart/form-data
required
file
required
string <binary>

Image file to upload

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get collection node photo

Retrieve the photo for a collection node. Returns a redirect to the actual image URL. Supports optional size parameters for image resizing.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
size
string
Example: size=bg

Image size filter:

  • bg: Large blurred image suitable for backgrounds
  • Other values may resize the image accordingly
width
integer
Example: width=800

Desired image width in pixels

height
integer
Example: height=600

Desired image height in pixels

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

conversations

Conversations are lists of messages exchanged between Sellers and Travelers that are related to a specific Order. For example, Xola commonly sends booking confirmation notifications via email or SMS, and Sellers may opt to send additional reminder and check-in notices before the start of an Event. Each of these will show up as a message inside of the Conversation history attached to the Purchase.

List conversations

Retrieve a paginated list of conversations

Authorizations:
apiKeybasicAuth
query Parameters
participant
required
string

ID of participant to filter conversations by

seller
string

Filter conversations by seller ID

tag
string
Value: "unread"

Filter conversations by participant tag (e.g., 'unread')

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {}
}

Create a conversation

Create a new conversation for a specific purchase. The conversation will automatically include participants based on the purchase (seller and traveler/organizer).

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
object

Purchase to associate with the conversation

Responses

Request samples

Content type
application/json
{
  • "purchase": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "purchase": {
    },
  • "seller": {
    },
  • "participants": [
    ],
  • "messages": [ ],
  • "createdAt": "2024-01-15T10:00:00Z",
  • "updatedAt": "2024-01-15T10:00:00Z"
}

Broadcast message to multiple conversations

Broadcast messages to participants across multiple conversations based on filtering criteria. This endpoint allows sending either email or SMS messages to participants (travelers, guides, etc.) with reservations matching the specified filters.

Filtering Logic:

  • If events array is provided, messages are sent to participants with reservations for those specific events
  • If events is not provided, date parameter is required to filter by reservation date
  • experiences array is ignored if events is provided
  • future flag can include future reservations when using date-based filtering
Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string

Seller ID to send messages from

Request Body schema: application/json
required
subject
string

Message subject (required for email messages)

body
required
string

Message body content

type
string
Default: "email"
Enum: "email" "sms"

Message type (defaults to email if not specified)

includeGuides
boolean
Default: false

Whether to include guides in the message broadcast

required
object

Filters for selecting which conversations to send messages to. Either 'events' or 'date' must be provided.

Responses

Request samples

Content type
application/json
Example
{
  • "subject": "Important Trip Update",
  • "body": "Due to weather conditions, your trip departure time has changed to 9:30 AM.",
  • "type": "email",
  • "includeGuides": false,
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Retrieve a conversation

Get detailed information about a specific conversation including all messages and participants.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Conversation ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "purchase": {
    },
  • "seller": {
    },
  • "participants": [
    ],
  • "messages": [
    ],
  • "createdAt": "2024-01-15T10:00:00Z",
  • "updatedAt": "2024-01-15T14:15:00Z"
}

Remove tag from participant

Remove a specific tag from a conversation participant. This is commonly used to mark conversations as read by removing the "unread" tag.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Conversation ID

participantId
required
string

Participant ID

tag
required
string
Value: "unread"

Tag to remove

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Coupons

Coupon Types

Xola offers the following varieties of coupons:

  1. Discount: Reduces the order amount by a percentage or absolute value.
  2. Unlock: Specify an ad-hoc order amount.
  3. Demographic Discount: Reduces the order amount by an absolute value based on the quantity of guests.
  4. Buy X Get Y: Advanced demographic discount coupon that helps incentivize group bookings.
  5. Voucher: Applied as a payment method (unlike other types, which are applied as a discount). Vouchers are a great way to handle campaigns from daily deal sites like Groupon.

Taxes & Fees

All coupons, with the exception of Vouchers, are applied before taxes & fees. Vouchers are applied after taxes & fees, just like a method of payment.

Purchase Restrictions

All coupon types support the ability to place the following restrictions at redemption:

  1. Purchase Window: Limits the dates within which this coupon can be redeemed.
  2. Arrival Window: Limits the arrival date on which the activity takes place.
  3. Listing Restriction: Limits the coupon to a subset of your listings.

Coupon Codes

A coupon cannot be directly used. It must have "codes" associated with it. A code may be configured to be limited use or unlimited use. Xola will keep track of the number of code usages.

{
  "id": "5acc4fa307876c4f798b4567",
  "name": "Winter Sale",
  "amount": 20,
  "type": "discount",
  "algorithm": "percent",
  "source": "xola",
  "seller": {
    "id": "57e4a620c683b1c01e8b4575"
  },
  "bookBySchedule": {
    "id": "5b05c8ed07876c8a108b457e",
    "repeat": "weekly",
    "days": [0, 1, 2, 3, 4, 5, 6],
    "start": "2018-08-31T15:00:00+00:00",
    "end": "2018-12-31T14:59:59+00:00",
    "type": "available",
    "timeRanges": [],
    "blackouts": []
  },
  "arrivalSchedule": {
    "id": "5b05c8ed07876c8a108b457f",
    "repeat": "weekly",
    "days": [0, 1, 2, 3, 4, 5, 6],
    "start": "2018-10-31T15:00:00+00:00",
    "end": "2018-12-31T14:59:59+00:00",
    "type": "available",
    "timeRanges": [],
    "blackouts": [
      {
        "repeat": "weekly",
        "days": [2],
        "start": "2018-12-24T15:00:00+00:00",
        "end": "2018-12-25T14:59:59+00:00",
        "type": "unavailable",
        "timeRanges": [],
        "id": "5b05c8ed07876c8a108b4580"
      }
    ]
  },
  "createdAt": "2018-04-10T05:46:11+00:00",
  "createdBy": {
    "id": "4f293e17536e86bc66000000"
  },
  "updatedAt": "2018-05-23T20:02:53+00:00",
  "experiences": {
    "all": true,
    "experiences": []
  },
  "tags": [
    {
      "system": true,
      "id": "winter is coming"
    }
  ]
}

List coupons

Get all coupons based on filters. This endpoint will NOT return coupon codes but it will return total uses for all codes in this coupon.

To retrieve coupons, either the seller or experience must be specified as a filter. Optionally you may specify arrival or arrivalTime filters to restrict the response to coupons that can only be applied to orders with the specified arrival date & time.

There are two varieties of coupon:

  • Discount: Allows a seller to specify rules around which the coupon value is calculated.
  • Unlock: Allows the consumer to specify an arbitrary order amount. Any discount value will be accepted as long as it does not reduce the total order amount below zero.

Rules to calculate a discount coupon

Discount coupons rely on the type and algorithm attributes that determine how the coupon value is calculated:

  • algorithm: Determines if the calculation treats the amount as an absolute value or a percent value
  • type: Determines if the calculation is applicable per person (person) or a flat discount for the entire booking (discount)
Authorizations:
apiKeybasicAuth
query Parameters
expand
string
Value: "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

seller
string
Example: seller=65bbde2d1b8c18afc407eee6

Seller ID to filter coupons by (required unless experience is specified)

experience
string
Example: experience=68652ca5ff69705d380c1ef0

Experience ID to filter coupons by (required unless seller is specified)

code
string
Example: code=SUMMER2025

Specific coupon code to search for

arrival
string <date>
Example: arrival=2025-09-15

Arrival date to filter applicable coupons

arrivalTime
string <date-time>
Example: arrivalTime=2025-09-15T14:30:00Z

Arrival date and time to filter applicable coupons

limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

skip
integer >= 0
Default: 0

Number of results to skip for pagination

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new coupon

Create a new coupon with purchase rules and optional initial coupon codes.

Sample request for discount coupon:

  • Give a flat $10 discount per booking
  • Include purchase rule configuration for filtering and actions
  • Optionally create initial coupon codes

Purchase Rules: Modern coupons use purchase rules instead of the deprecated triggers/rewards system. Purchase rules define:

  • Filters: Conditions when the coupon can be applied (schedule, experience, privacy, etc.)
  • Actions: What happens when the coupon is applied (discount calculation)
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
name
required
string

Name of the coupon

type
required
string
Enum: "discount" "person" "unlock" "voucher" "bxgy"

Type of coupon:

  • discount: Flat discount for the entire booking
  • person: Discount applied per person
  • unlock: Consumer can specify arbitrary order amount
  • voucher: Voucher with purchase amount restrictions
  • bxgy: Buy X Get Y discount
algorithm
string
Enum: "percent" "absolute"

Algorithm used to calculate discount:

  • percent: Percentage-based discount
  • absolute: Fixed amount discount
amount
number <float> >= 0

Discount amount (percentage or absolute value based on algorithm)

integer or null

Maximum number of times the coupon can be used (null for unlimited)

source
string
Enum: "xola" "gift" "store_credit" "groupon" "membership"

Source/origin of the coupon:

  • xola: Standard Xola coupon
  • gift: Generated from gift offer
  • store_credit: Store credit coupon
  • groupon: Groupon voucher
  • membership: Membership-based coupon
excludeTaxFee
boolean
Default: false

Whether to exclude taxes and fees when applying the coupon

Array of objects (Tag)

Tags associated with the coupon

object (SelectedExperiences)

Experiences this coupon can be applied to

required
object (ObjectReference)

Seller who owns this coupon

Discount Coupon Purchase Rule (object) or BXGY Coupon Purchase Rule (object) or Voucher Coupon Purchase Rule (object)

Purchase rule configuration for the coupon

Array of objects (CouponCodeInput)

Initial coupon codes to create with the coupon

string or null

How to handle duplicate codes:

  • void: Void existing duplicate codes
  • skip: Skip duplicate codes
  • null: Throw error on duplicates
purchaseAmount
number <float> >= 0

Original purchase amount for voucher coupons

maxDemographics
integer >= 1

Maximum number of demographics the voucher can be applied to

paymentMethod
string

Payment method used for voucher (e.g., Groupon, Living Social)

Array of strings or null

Permissions required to use this coupon

Responses

Request samples

Content type
application/json
Example
{
  • "type": "discount",
  • "name": "Summer Sale 10% Off",
  • "limit": 100,
  • "tags": [
    ],
  • "excludeTaxFee": true,
  • "seller": {
    },
  • "algorithm": "absolute",
  • "amount": 10,
  • "source": "xola",
  • "experiences": {
    },
  • "codes": [
    ],
  • "duplicate": null
}

Response samples

Content type
application/json
{
  • "name": "Summer Sale 20% Off",
  • "type": "discount",
  • "algorithm": "absolute",
  • "amount": 10,
  • "limit": 100,
  • "source": "xola",
  • "excludeTaxFee": false,
  • "tags": [
    ],
  • "experiences": {
    },
  • "seller": {
    },
  • "id": "68b704c3bc33ee2ba00b07e2",
  • "purchaseRulePermanentId": "68b704c4bc33ee2ba00b07e5",
  • "purchaseRule": {
    },
  • "balance": 0.1,
  • "triggers": [
    ],
  • "rewards": [
    ],
  • "terms": [
    ],
  • "promotions": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    },
  • "purchaseAmount": 80,
  • "maxDemographics": 2,
  • "paymentMethod": "Groupon",
  • "permissions": [
    ]
}

Get coupon details

Retrieve a specific coupon by its ID. To retrieve a coupon, you must have VIEW_COUPON permission.

The response includes complete coupon details including associated purchase rules (when expanded).

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

query Parameters
expand
string
Value: "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

Responses

Response samples

Content type
application/json
{
  • "id": "68b704c3bc33ee2ba00b07e2",
  • "name": "Summer Sale",
  • "limit": 100,
  • "type": "discount",
  • "source": "xola",
  • "excludeTaxFee": true,
  • "amount": 10,
  • "algorithm": "absolute",
  • "experiences": {
    },
  • "seller": {
    },
  • "purchaseRulePermanentId": "68b704c4bc33ee2ba00b07e5",
  • "purchaseRule": {
    },
  • "createdAt": "2025-09-02T14:52:51+00:00",
  • "createdBy": {
    },
  • "tags": [ ],
  • "triggers": [ ],
  • "rewards": [ ],
  • "terms": [ ],
  • "promotions": [ ]
}

Update an existing coupon

Update an existing coupon's properties. You must have EDIT_COUPON permission.

Note: Some fields like purchase rules may have restrictions on updates depending on usage.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

Request Body schema: application/json
required
name
required
string

Name of the coupon

type
required
string
Enum: "discount" "person" "unlock" "voucher" "bxgy"

Type of coupon:

  • discount: Flat discount for the entire booking
  • person: Discount applied per person
  • unlock: Consumer can specify arbitrary order amount
  • voucher: Voucher with purchase amount restrictions
  • bxgy: Buy X Get Y discount
algorithm
string
Enum: "percent" "absolute"

Algorithm used to calculate discount:

  • percent: Percentage-based discount
  • absolute: Fixed amount discount
amount
number <float> >= 0

Discount amount (percentage or absolute value based on algorithm)

integer or null

Maximum number of times the coupon can be used (null for unlimited)

source
string
Enum: "xola" "gift" "store_credit" "groupon" "membership"

Source/origin of the coupon:

  • xola: Standard Xola coupon
  • gift: Generated from gift offer
  • store_credit: Store credit coupon
  • groupon: Groupon voucher
  • membership: Membership-based coupon
excludeTaxFee
boolean
Default: false

Whether to exclude taxes and fees when applying the coupon

Array of objects (Tag)

Tags associated with the coupon

object (SelectedExperiences)

Experiences this coupon can be applied to

required
object (ObjectReference)

Seller who owns this coupon

Discount Coupon Purchase Rule (object) or BXGY Coupon Purchase Rule (object) or Voucher Coupon Purchase Rule (object)

Purchase rule configuration for the coupon

Array of objects (CouponCodeInput)

Initial coupon codes to create with the coupon

string or null

How to handle duplicate codes:

  • void: Void existing duplicate codes
  • skip: Skip duplicate codes
  • null: Throw error on duplicates
purchaseAmount
number <float> >= 0

Original purchase amount for voucher coupons

maxDemographics
integer >= 1

Maximum number of demographics the voucher can be applied to

paymentMethod
string

Payment method used for voucher (e.g., Groupon, Living Social)

Array of strings or null

Permissions required to use this coupon

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Summer Sale",
  • "type": "discount",
  • "limit": 200,
  • "excludeTaxFee": false,
  • "algorithm": "percent",
  • "amount": 15,
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "name": "Summer Sale 20% Off",
  • "type": "discount",
  • "algorithm": "absolute",
  • "amount": 10,
  • "limit": 100,
  • "source": "xola",
  • "excludeTaxFee": false,
  • "tags": [
    ],
  • "experiences": {
    },
  • "seller": {
    },
  • "id": "68b704c3bc33ee2ba00b07e2",
  • "purchaseRulePermanentId": "68b704c4bc33ee2ba00b07e5",
  • "purchaseRule": {
    },
  • "balance": 0.1,
  • "triggers": [
    ],
  • "rewards": [
    ],
  • "terms": [
    ],
  • "promotions": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    },
  • "purchaseAmount": 80,
  • "maxDemographics": 2,
  • "paymentMethod": "Groupon",
  • "permissions": [
    ]
}

Delete a coupon

Soft delete a coupon by setting the deletedAt timestamp. You must have EDIT_COUPON permission.

Note: This does not immediately void associated coupon codes.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Coupon Codes

A Coupon cannot be used unless it has codes associated with it.

Each coupon code has a user-specified identifier (code) that must be unique across all active coupon campaigns. Its usage may be limited or left open for unlimited use. Usage of coupons is tracked at the code level to measure the efficacy of your coupon campaign.

The list of codes for a given coupon would typically be specified during coupon creation within the codes property. Alternately, you may use these endpoints to operate at a per-code level.

{
  "id": "5acc50ef07876cf24d8b456f",
  "code": "23voucher",
  "coupon": {
    "id": "5acc50ef07876cf24d8b456c"
  },
  "status": 100,
  "orders": [],
  "uses": 0
}

List coupon codes for a specific coupon

Returns a paginated list of coupon codes associated with a specific coupon. You must have VIEW_COUPON permission for the parent coupon.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

skip
integer >= 0
Default: 0

Number of results to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create coupon codes for a specific coupon

Create one or more coupon codes for a specific coupon. You must have EDIT_COUPON permission.

Batch Creation:

  • Use batch=true query parameter to create multiple codes at once
  • Large batches may be processed in the background (returns 202)

Duplicate Handling:

  • Use duplicate query parameter to control behavior when codes already exist
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

query Parameters
batch
boolean
Default: false

Whether to create multiple codes in batch mode

duplicate
string
Enum: "void" "skip"

How to handle duplicate codes:

  • void: Void existing duplicate codes
  • skip: Skip duplicate codes
  • omit: Throw error on duplicates
Request Body schema: application/json
required
One of
code
required
string^[^\s<>&"']+$

The coupon code to create

uses
integer >= 0
Default: 0

Initial usage count (typically 0)

Responses

Request samples

Content type
application/json
Example
{
  • "code": "NEWCODE123",
  • "uses": 0
}

Response samples

Content type
application/json
""

Get coupon code details

Retrieve details of a specific coupon code. You must have VIEW_COUPON permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

codeId
required
string
Example: 68b704c5bc33ee2ba00b07e3

Coupon code ID

Responses

Response samples

Content type
application/json
{
  • "id": "68b704c5bc33ee2ba00b07e3",
  • "code": "SUMMER10",
  • "status": 100,
  • "uses": 3,
  • "limit": null,
  • "coupon": {
    },
  • "objects": [
    ],
  • "createdAt": "2025-09-02T14:52:52+00:00",
  • "updatedAt": "2025-09-02T15:30:15+00:00"
}

Update a coupon code

Update a specific coupon code. You must have EDIT_COUPON permission.

Restrictions:

  • Cannot change code if it has been used
  • Cannot change to/from the special 'iin-discount' code
  • Status can only be set to void (400)
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

codeId
required
string
Example: 68b704c5bc33ee2ba00b07e3

Coupon code ID

Request Body schema: application/json
required
code
required
string^[^\s<>&"']+$

Updated coupon code

status
integer
Value: 400

Status can only be set to void (400)

Responses

Request samples

Content type
application/json
{
  • "code": "UPDATEDCODE"
}

Response samples

Content type
application/json
{
  • "code": "SUMMER2025",
  • "status": 100,
  • "uses": 5,
  • "limit": 10,
  • "id": "68b704c5bc33ee2ba00b07e3",
  • "coupon": {
    },
  • "objects": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": {
    },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    }
}

Void a coupon code

Void a specific coupon code to prevent it from being used against future orders. You must have EDIT_COUPON permission.

Note: Cannot void the special 'iin-discount' code.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 68b704c3bc33ee2ba00b07e2

Coupon ID

codeId
required
string
Example: 68b704c5bc33ee2ba00b07e3

Coupon code ID

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Search coupon codes globally

Search for coupon codes across all coupons. This is a utility endpoint for code lookup. Results depend on user permissions and seller access.

Required Parameters:

  • Either seller must be specified, or code must be provided for unauthenticated searches

Permissions:

  • With VIEW_COUPON_CODE permission: Can search all codes for the seller
  • Without permission: Can only search for specific active codes that are publicly available
  • Affiliates: Can only search for the special "iin-discount" code
Authorizations:
apiKeybasicAuth
query Parameters
expand
string
Value: "coupon"

You can expand multiple objects at the same time by providing a comma-separated list of values

code
string
Example: code=SUMMER10

Specific code to search for (required for unauthenticated searches)

seller
string
Example: seller=65bbde2d1b8c18afc407eee6

Seller ID to filter by (required unless searching by code only)

coupon
string
Example: coupon=68b704c3bc33ee2ba00b07e2

Coupon ID to filter codes by specific coupon

status
integer
Enum: 100 200 400
Example: status=100

Filter by coupon code status:

  • 100: Active/Valid
  • 200: Redeemed
  • 400: Void
limit
integer [ 1 .. 100 ]
Default: 20

Maximum number of results to return

skip
integer >= 0
Default: 0

Number of results to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

delegates

User delegation and permission management

List user delegates

Retrieve a list of delegates for the specified user. Delegates are users who have been granted specific permissions to act on behalf of the user's account.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have VIEW_USER_DELEGATES permission for the target user, OR
  • Must be an app store user with ROLE_APP_STORE

Permission Filtering: Use the permission query parameter to filter delegates by a specific permission role.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

User ID to get delegates for

query Parameters
permission
string
Example: permission=ROLE_BOOKING_ENGINE

Filter delegates by specific permission role

Responses

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Create a new delegate

Add a new delegate to the specified user account. If a user with the provided email already exists in Xola, that user will be added as the delegate. If no user exists with the email, a new user will be created and a verification email will be sent.

Important: This endpoint creates the delegate but does not grant any permissions. The permissions array in the response will always be empty. Use the individual permission endpoints (PUT /users/{id}/delegates/{delegateId}/permissions/{permission}) to grant specific permissions to the delegate.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have EDIT_USER_DELEGATES permission for the target user

Email Notifications:

  • New users receive account verification emails
  • Existing users receive access granted notifications

Business Rules:

  • Cannot delegate to yourself
  • Cannot delegate to another seller account
  • Cannot delegate to existing affiliates
  • Can delegate to travelers from other seller accounts
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

User ID to create delegate for

Request Body schema: application/json
required
name
string

Full name of the delegate

email
required
string <email>

Email address of the delegate

phone
string

Phone number of the delegate

Responses

Request samples

Content type
application/json
Example
{
  • "name": "John Smith",
  • "email": "john.smith@example.com",
  • "phone": "+1-555-123-4567"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439014",
  • "permissions": [ ],
  • "user": {
    },
  • "name": "Jane Doe",
  • "email": "jane.doe@example.com",
  • "enabled": true
}

Get a specific delegate

Retrieve details for a specific delegate of the user account.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have VIEW_USER_DELEGATES permission for the target user, OR
  • Must be an app store user with ROLE_APP_STORE
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

User ID that owns the delegate

delegateId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the delegate user to retrieve

Responses

Response samples

Content type
application/json
Example
{
  • "id": "507f1f77bcf86cd799439012",
  • "permissions": [
    ],
  • "user": {
    }
}

Create or update delegate permissions

Create a new delegate or update permissions for an existing delegate. This endpoint performs an upsert operation - if the delegate doesn't exist, it will be created.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have EDIT_USER_DELEGATES permission for the target user, OR
  • Must be delegating a distribution channel user (XGEN, Groupon), OR
  • Must be a seller adding a plugin user as delegate

Permission Management:

  • PUT operations replace all existing permissions with the provided permissions
  • To add permissions incrementally, retrieve current permissions first and include them
  • Experience-level granularity is supported for specific permission types

Special Cases:

  • Distribution channel users can be added regardless of access management settings
  • Plugin users can be added by sellers without access management enabled
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

User ID that will own the delegate

delegateId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the user to be added/updated as delegate

Request Body schema: application/json
required
required
Array of objects (PermissionRequest)

List of permissions to grant to the delegate (replaces existing permissions)

Responses

Request samples

Content type
application/json
Example
{
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "permissions": [
    ],
  • "user": {
    }
}

Remove a delegate

Remove a delegate from the user account. This revokes all delegated permissions and access to the account.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have EDIT_USER_DELEGATES permission for the target user, OR
  • Must be removing a distribution channel user (XGEN, Groupon), OR
  • Must be a seller removing a plugin user delegate

Side Effects:

  • Removes delegate from all future events if the delegate is a guide
  • Does not affect past events
  • Triggers audit logging
  • May disable associated plugins or integrations

Special Cases:

  • Distribution channel users can be removed regardless of access management settings
  • Plugin users can be removed by sellers without access management enabled
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439011

User ID that owns the delegate

delegateId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

ID of the delegate user to remove

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Grant or update a specific permission for a delegate

Grant a specific permission to a delegate or update an existing permission. This is the primary way to manage individual permissions for delegates after they have been created.

Authorization Requirements:

  • Must have ROLE_USER or higher
  • Must have EDIT_USER_DELEGATES permission for the target user

Permission Management:

  • This endpoint grants or updates a single permission at a time
  • Use separate API calls to grant multiple permissions
  • Experience-level granularity is supported for applicable permissions

Special Cases:

  • Distribution channel users can be managed regardless of access management settings
  • Plugin users can be managed by sellers without access management enabled
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 65bbde2d1b8c18afc407eee6

User ID that owns the delegate

delegateId
required
string^[0-9a-fA-F]{24}$
Example: 68b86d40fc7a6260d70f44ae

ID of the delegate user to grant permission to

permission
required
string
Example: ROLE_CURATOR

The permission role to grant

Request Body schema: application/json
required
name
required
string

Name of the permission role (see Permission schema for available roles)

object (SelectedExperiencesRequest)

Request payload for specifying experience-level granularity for permissions

Responses

Request samples

Content type
application/json
Example
{
  • "name": "ROLE_CURATOR"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

events

An event represents a collection of bookings for one experience at a scheduled date and time. This object keeps track of the capacity of that particular timeslot for the experience. In Xola's seller interface, events are what are shown on the dashboard.

List events

Fetch all events based on specific filters. An event represents a collection of bookings for one experience that departs at a specific time. Events are automatically created when bookings are made or can be manually created.

Supports roster export format when format=roster parameter is used.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

expand
string
Enum: "experience" "resource" "guide" "schedule"

You can expand multiple objects at the same time by providing a comma-separated list of values

seller
string

Filter events by seller ID

experience
string

Filter events by experience ID

guide
string

Filter events by assigned guide ID

start
integer <int64>
Example: start=1734256800

Start of the date range to filter events by, as a Unix timestamp (integer seconds since the epoch, UTC). Events whose start falls within [start, end] are returned. Defaults to the current time when omitted.

end
integer <int64>
Example: end=1736935200

End of the date range to filter events by, as a Unix timestamp (integer seconds since the epoch, UTC). Defaults to one month after start when omitted.

offset
integer
Example: offset=-19800

Timezone offset, in seconds, applied to the start and end range so it can be expressed in the caller's local time. Negative for zones ahead of UTC (for example IST), positive for zones behind UTC (for example PDT).

format
string
Default: "json"
Enum: "json" "roster"

Response format (use 'roster' for Excel export)

open
integer >= 0

Filter by minimum open capacity

closed
boolean
Default: false

Include closed events

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new event

Create a new event (trip) for an experience. A trip represents a collection of bookings for one experience that departs at the same time. Events are usually created automatically when bookings are made, but this endpoint allows manual creation for assigning guides or modifying capacity.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
object
start
required
string <date-time>

Start date and time for the event

title
string

Optional title override

max
integer >= 0

Maximum capacity override

Array of objects
Array of objects (ResourceUsageInput)

Resources to assign to this event

manual
boolean
Default: false

Flag to create a manual event outside of configured schedules

Responses

Request samples

Content type
application/json
Example
{
  • "experience": {
    },
  • "start": "2024-12-15T10:00:00Z",
  • "max": 12
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "start": "2024-12-15T10:00:00Z",
  • "actualStart": "2024-12-15T10:00:00-05:00",
  • "end": "2024-12-15T12:00:00Z",
  • "title": "Morning Kayak Tour",
  • "experience": {
    },
  • "groupId": null,
  • "max": 12,
  • "open": 12,
  • "private": false,
  • "virtualMeeting": false,
  • "quantity": {
    },
  • "seller": {
    },
  • "orders": [ ],
  • "purchaseItems": [ ],
  • "guides": [ ],
  • "object": "event",
  • "createdAt": "2024-12-14T15:30:00Z",
  • "createdBy": "507f1f77bcf86cd799439018"
}

Get a specific event

Fetch a specific event (trip) by ID. An event represents a collection of bookings for one experience that departs at a specific time.

Supports roster export format when format=roster parameter is used.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

query Parameters
expand
string
Enum: "experience" "resource" "guide" "schedule"

You can expand multiple objects at the same time by providing a comma-separated list of values

format
string
Default: "json"
Enum: "json" "roster"

Response format (use 'roster' for Excel export)

Responses

Response samples

Content type
Example
{
  • "id": "507f1f77bcf86cd799439011",
  • "start": "2024-12-15T10:00:00Z",
  • "actualStart": "2024-12-15T10:00:00-05:00",
  • "end": "2024-12-15T12:00:00Z",
  • "title": "Morning Kayak Tour",
  • "experience": {
    },
  • "groupId": null,
  • "max": 12,
  • "open": 3,
  • "private": false,
  • "virtualMeeting": false,
  • "quantity": {
    },
  • "seller": {
    },
  • "orders": [
    ],
  • "purchaseItems": [
    ],
  • "guides": [
    ],
  • "object": "event"
}

Update an event

Update an event's properties. Currently only supports updating the max capacity. Updating the max capacity allows you to override the maximum trip capacity configured in the experience configuration.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Request Body schema: application/json
required
max
required
integer >= 0

Maximum capacity override

manual
boolean
Default: false

Flag to reopen a closed event as manual

Responses

Request samples

Content type
application/json
Example
{
  • "max": 15
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "actualStart": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "experience": {
    },
  • "groupId": "string",
  • "max": 0,
  • "open": 0,
  • "private": true,
  • "virtualMeeting": true,
  • "quantity": {
    },
  • "seller": {
    },
  • "orders": [
    ],
  • "purchaseItems": [
    ],
  • "guides": [
    ],
  • "object": "event",
  • "manual": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updated": "2019-08-24T14:15:22Z",
  • "notes": [
    ],
  • "aggregation": {
    },
  • "resourceUsages": [
    ],
  • "organizer": { }
}

Partially update an event

Partially update an event's properties. This is an alias for the PUT operation and supports the same functionality.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Request Body schema: application/json
required
max
required
integer >= 0

Maximum capacity override

manual
boolean
Default: false

Flag to reopen a closed event as manual

Responses

Request samples

Content type
application/json
{
  • "max": 0,
  • "manual": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "actualStart": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "experience": {
    },
  • "groupId": "string",
  • "max": 0,
  • "open": 0,
  • "private": true,
  • "virtualMeeting": true,
  • "quantity": {
    },
  • "seller": {
    },
  • "orders": [
    ],
  • "purchaseItems": [
    ],
  • "guides": [
    ],
  • "object": "event",
  • "manual": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updated": "2019-08-24T14:15:22Z",
  • "notes": [
    ],
  • "aggregation": {
    },
  • "resourceUsages": [
    ],
  • "organizer": { }
}

Delete a manual event

Delete a manual type event which has no orders. Only events that were manually created and have no associated bookings can be deleted.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Send event roster via email

Send the trip roster to the seller and any assigned guides through email. This action triggers email delivery of the event participant list.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get event guides

Get all guides currently assigned to an event. Returns basic guide information for each assigned guide.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add guide to event

Add a guide to an event. Only users with guide management permissions can add guides to events. The system will check for guide availability conflicts with other events.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "guide": {
    }
}

Response samples

Content type
application/json
{
  • "status": "confirmed",
  • "guide": {
    },
  • "assignedBy": "507f1f77bcf86cd799439018"
}

Update event guide

Update an event guide assignment. Supports updating the guide's status (e.g., to confirm or decline). The authenticated user must be the guide themselves.

When setting status to declined, the seller's guide notification preference allowDecline must permit it. If decline is not allowed, a 403 Forbidden response is returned.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID

Request Body schema: application/json
required
status
string
Enum: "pending" "confirmed" "declined"

New status for the guide assignment. Setting to declined requires that the seller's allowDecline preference is not false.

Responses

Request samples

Content type
application/json
{
  • "status": "pending"
}

Response samples

Content type
application/json
{
  • "status": "pending",
  • "guide": {
    },
  • "assignedBy": "string"
}

Remove guide from event

Remove a guide from an event. This will unassign the guide from the specified event.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID to remove

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Confirm event guide

Confirm a guide's assignment to an event. This updates the guide's status to confirmed. Typically invoked via a link in the guide's assignment notification email.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID to confirm

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Decline event guide assignment

Decline a guide's assignment to an event. This updates the guide's status to declined and sends a notification email to the user who originally assigned the guide (or the seller as a fallback).

Typically invoked via a link in the guide's assignment notification email.

Triggers a guide_declined_to_seller notification to the assigner.

If the seller's allowDecline guide notification preference is set to false, the decline is not processed and an HTML page with a decline_not_allowed status is returned instead.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID to decline

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create an event note

Add a note to an event. When the event belongs to a group, the note is attached to the primary event of the group.

Requires the EDIT_EVENT_NOTES permission on the event.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Event ID

Request Body schema: application/json
required
text
required
string

Note content

Responses

Request samples

Content type
application/json
{
  • "text": "Guide running 10 minutes late"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Update an event note

Update the text of an existing event note.

Requires the EDIT_EVENT_NOTES permission on the event.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Event ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Request Body schema: application/json
required
text
required
string

Updated note content

system
boolean

Whether the note is a system-generated note.

Responses

Request samples

Content type
application/json
{
  • "text": "Guide arrived - tour started on time"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Delete an event note

Delete an event note.

Requires the EDIT_EVENT_NOTES permission on the event.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Event ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

experiences

Experience and activity management

List experiences

Retrieve a paginated list of experiences. This endpoint supports various filtering and search options.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

expand
string
Enum: "demographic" "partnerSeller" "purchaseRule" "purchaseRuleLink"

You can expand multiple objects at the same time by providing a comma-separated list of values

seller
string
Example: seller=507f1f77bcf86cd799439020

Filter by seller ID

category
string
Example: category=Water Sports

Filter by category name

name
string
Example: name=kayaking

Search experiences by name

geo
string^-?\d+\.?\d*,-?\d+\.?\d*(,-?\d+\.?\d*)?$
Example: geo=36.1069,-112.1129,50

Geographic coordinates for location-based filtering (lat,lng or lat,lng,radius_km)

priceSchemes_price
string^[\d\.]+(-[\d\.]+)?$
Example: priceSchemes_price=50,200

Price filtering - single value (max price) or range (min,max)

agent
boolean
Example: agent=true

Filter experiences available to authenticated agent/delegate

partnerExperiences
boolean

Include experiences from partner sellers

partnerSeller
string
Example: partnerSeller=507f1f77bcf86cd799439090

Filter experiences from specific partner seller

deleted
boolean

Include soft-deleted experiences (admin only)

sort
string^[a-zA-Z_]+(\[(asc|desc)\])?$
Examples:
  • sort=priceSchemes_price[asc] - Sort by price ascending
  • sort=name[desc] - Sort by name descending
  • sort=id - Default sort by ID

Sort field with optional direction. Format: field[asc] or field[desc]

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {}
}

Create experience

Create a new experience for the authenticated seller account.

Required Fields

  • Name, price, duration, and price type are required
  • Experience will be created in draft status initially

Automatic Behavior

  • Sets the seller to the authenticated user's seller account
  • Initializes basic configuration with sensible defaults
  • Creates audit trail entry for the creation
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Experience name or title

desc
string

Full description of the experience

excerpt
string <= 500 characters

Short description or summary of the experience

price
number <float> >= 0

Base price of the experience

currency
string^[A-Z]{3}$

Currency code (ISO 4217)

priceType
string
Default: "person"
Enum: "person" "outing"

Pricing scheme (per person or per outing)

guestType
string
Default: "normal"
Enum: "normal" "passenger"

Type of guests in this experience

required
ObjectReference (object) or string

Seller ID or reference

category
string

Category name for the experience

duration
integer >= 1

Duration to block inventory in minutes

eventDuration
integer >= 1

Publicly visible duration of the experience in minutes

requireAdult
boolean
Default: false

Whether at least one adult is required for booking

object (LocationInput)

Location input for creating/updating geographic locations

pickupAddress
string <= 500 characters

Pickup address for the experience

scheduleType
string
Enum: "open" "day" "time"

Type of scheduling for this experience

cancellationPolicy
string

The cancellation policy for this experience

other
string

Other considerations or notes

sortDemographics
boolean
Default: false

Whether demographics should be sorted by label

isScheduled
boolean
Deprecated

Whether this experience uses scheduling (legacy field)

balanceDueOffset
integer >= 0

Minutes before arrival to send balance due reminder

balanceDueReminder
boolean

Whether to send balance due reminders

autoChargeOnDepositReminder
boolean

When true, automatically charge the outstanding balance on deposit reminder instead of just sending a reminder email

cutoff
integer >= 1

Cutoff time for bookings in minutes

cutoffType
string
Enum: "pre_start" "pre_end" "pre_opening_end"

Type of cutoff:

  • pre_start: Cutoff applies before the experience start time
  • pre_end: Cutoff applies before the experience end time
  • pre_opening_end: Cutoff applies before the opening-hours window closes (requires opening-hours schedules)
alternateCutoff
integer >= 1

Alternate cutoff when bookings exist

arrivalOffset
integer

Meet X minutes before scheduled time

visible
boolean

Whether the experience is publicly visible

complete
boolean

Whether the experience setup is complete

reviewed
boolean

Whether the experience has been reviewed

customerNamePreference
string
Enum: "required" "optional_confirmation" "optional_no_confirmation" "not_collected"

Customer name collection preference

allowedPrivacies
Array of strings
Items Enum: "private" "public"

Allowed privacy levels for bookings

purchaseExpirationOffset
integer >= 0

Minutes from purchase when experience expires (non-scheduled)

firstCheckinExpirationOffset
integer >= 0

Minutes from first check-in when expires

businessHours
string
Deprecated

Business hours for customer communications (deprecated — use the openingHours endpoints instead)

Array of objects (ScheduleInput)

Structured opening-hours schedules. Each entry is a Schedule object with departure: openingHours and per-weekday time windows in openingHoursPerDay. Prefer the dedicated POST/PUT/DELETE /experiences/{id}/openingHours endpoints to manage these; this field in the request body is also accepted for bulk-setting.

paymentMethod
string
Enum: "cc" "later"

Payment method accepted

requireGuestIdentification
boolean
Default: true

Whether purchase item guests require identification data. When set to false, guests do not need any identification information to complete a booking.

requireCCForSources
Array of strings

Sources requiring credit card collection

emailFooter
string

Custom email footer

object (GroupOptionsInput)

Group options input for creating/updating

object (DownDepositInput)

Down deposit input for creating/updating

object (FutureCutoffInput)

Future cutoff input for creating/updating

object (VirtualMeetingPreferenceInput)

Virtual meeting preference input for creating/updating

object (CatalogPreferenceInput)

Catalog preference input

object (UpsellPreferenceInput)

Upsell preference input for creating/updating experiences

Array of objects (ScheduleInput)

Schedule configurations

included
Array of strings

Items included in the experience

notIncluded
Array of strings

Items NOT included in the experience

Array of objects (MediaInput)

Media items to associate with experience

Array of objects (MediaInput)

PDF attachments for the experience

Array of objects (TravelerNotificationPreference)

Experience-level overrides for traveler notification recipients. When provided, replaces the entire set of notification overrides for this experience. If a notification type is not included in this list, the system default recipients are used.

System defaults:

  • order_changed_to_traveler: organizer
  • invoice_changed_traveler: organizer
  • order_canceled_to_traveler: organizer
  • trip_reminder_to_traveler: travelers
  • review_reminder_to_traveler: organizer
  • waiver_reminder_to_traveler: organizer
CheckoutPreference (object) or null

Checkout preferences for this experience. Overrides seller-level checkout preferences when set. Set to null to clear and fall back to seller-level preferences.

Responses

Request samples

Content type
application/json
{
  • "name": "Grand Canyon Kayaking Adventure",
  • "seller": "507f1f77bcf86cd799439020",
  • "desc": "Join us for an unforgettable kayaking adventure through the stunning Grand Canyon rapids. Perfect for beginners and experienced paddlers alike.",
  • "excerpt": "Thrilling kayaking through canyon rapids",
  • "price": 149.99,
  • "currency": "USD",
  • "priceType": "person",
  • "category": "Water Sports",
  • "duration": 180,
  • "eventDuration": 150,
  • "scheduleType": "time",
  • "geo": {
    },
  • "pickupAddress": "Grand Canyon Village, AZ 86023",
  • "requireAdult": false,
  • "cancellationPolicy": "Free cancellation up to 24 hours before the experience",
  • "checkoutPreference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "experience",
  • "name": "Grand Canyon Kayaking Adventure",
  • "desc": "Join us for an unforgettable kayaking adventure through the stunning Grand Canyon rapids.",
  • "price": 149.99,
  • "currency": "USD",
  • "priceType": "person",
  • "category": "Water Sports",
  • "duration": 180,
  • "eventDuration": 150,
  • "complete": false,
  • "visible": false,
  • "reviewed": false,
  • "seller": {
    },
  • "createdAt": "2023-08-15T10:30:00Z",
  • "updatedAt": "2023-08-15T10:30:00Z"
}

Get experience

Retrieve detailed information about a specific experience.

Access Control

  • Public: Can view published, visible experiences
  • Sellers: Can view their own experiences regardless of status
  • Admins: Can view all experiences

Expansion Options

Use the expand parameter to include related data in a single request:

  • schedules: Include schedule configurations
  • seller: Include detailed seller information
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Enum: "demographic" "partnerSeller" "purchaseRule" "purchaseRuleLink"

You can expand multiple objects at the same time by providing a comma-separated list of values

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "experience",
  • "name": "Grand Canyon Kayaking Adventure",
  • "desc": "Join us for an unforgettable kayaking adventure through the stunning Grand Canyon rapids.",
  • "excerpt": "Thrilling kayaking through canyon rapids",
  • "price": 149.99,
  • "currency": "USD",
  • "priceType": "person",
  • "guestType": "normal",
  • "category": "Water Sports",
  • "duration": 180,
  • "eventDuration": 150,
  • "scheduleType": "time",
  • "complete": true,
  • "visible": true,
  • "reviewed": true,
  • "requireAdult": false,
  • "requireGuestIdentification": true,
  • "earlyReturn": false,
  • "isScheduled": true,
  • "balanceDueOffset": 7,
  • "balanceDueReminder": false,
  • "autoChargeOnDepositReminder": false,
  • "geo": {
    },
  • "pickupAddress": "Grand Canyon Village, AZ 86023",
  • "cancellationPolicy": "Free cancellation up to 24 hours before the experience",
  • "sortDemographics": false,
  • "seller": {
    },
  • "photo": null,
  • "schedules": [
    ],
  • "demographics": [ ],
  • "addOns": [ ],
  • "createdAt": "2023-08-15T10:30:00Z",
  • "updatedAt": "2023-08-16T14:20:00Z"
}

Update experience

Update an existing experience. Only the provided fields will be updated; other fields remain unchanged.

Authorization

  • Must be the owner of the experience or have admin privileges
  • Some fields may require specific permissions to modify

Validation

  • All existing validation rules apply to updated fields
  • Cannot change certain fields (like seller) after creation
  • Experience must maintain data integrity across related objects
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Experience name or title

desc
string

Full description of the experience

excerpt
string <= 500 characters

Short description or summary of the experience

price
number <float> >= 0

Base price of the experience

currency
string^[A-Z]{3}$

Currency code (ISO 4217)

priceType
string
Default: "person"
Enum: "person" "outing"

Pricing scheme (per person or per outing)

guestType
string
Default: "normal"
Enum: "normal" "passenger"

Type of guests in this experience

required
ObjectReference (object) or string

Seller ID or reference

category
string

Category name for the experience

duration
integer >= 1

Duration to block inventory in minutes

eventDuration
integer >= 1

Publicly visible duration of the experience in minutes

requireAdult
boolean
Default: false

Whether at least one adult is required for booking

object (LocationInput)

Location input for creating/updating geographic locations

pickupAddress
string <= 500 characters

Pickup address for the experience

scheduleType
string
Enum: "open" "day" "time"

Type of scheduling for this experience

cancellationPolicy
string

The cancellation policy for this experience

other
string

Other considerations or notes

sortDemographics
boolean
Default: false

Whether demographics should be sorted by label

isScheduled
boolean
Deprecated

Whether this experience uses scheduling (legacy field)

balanceDueOffset
integer >= 0

Minutes before arrival to send balance due reminder

balanceDueReminder
boolean

Whether to send balance due reminders

autoChargeOnDepositReminder
boolean

When true, automatically charge the outstanding balance on deposit reminder instead of just sending a reminder email

cutoff
integer >= 1

Cutoff time for bookings in minutes

cutoffType
string
Enum: "pre_start" "pre_end" "pre_opening_end"

Type of cutoff:

  • pre_start: Cutoff applies before the experience start time
  • pre_end: Cutoff applies before the experience end time
  • pre_opening_end: Cutoff applies before the opening-hours window closes (requires opening-hours schedules)
alternateCutoff
integer >= 1

Alternate cutoff when bookings exist

arrivalOffset
integer

Meet X minutes before scheduled time

visible
boolean

Whether the experience is publicly visible

complete
boolean

Whether the experience setup is complete

reviewed
boolean

Whether the experience has been reviewed

customerNamePreference
string
Enum: "required" "optional_confirmation" "optional_no_confirmation" "not_collected"

Customer name collection preference

allowedPrivacies
Array of strings
Items Enum: "private" "public"

Allowed privacy levels for bookings

purchaseExpirationOffset
integer >= 0

Minutes from purchase when experience expires (non-scheduled)

firstCheckinExpirationOffset
integer >= 0

Minutes from first check-in when expires

businessHours
string
Deprecated

Business hours for customer communications (deprecated — use the openingHours endpoints instead)

Array of objects (ScheduleInput)

Structured opening-hours schedules. Each entry is a Schedule object with departure: openingHours and per-weekday time windows in openingHoursPerDay. Prefer the dedicated POST/PUT/DELETE /experiences/{id}/openingHours endpoints to manage these; this field in the request body is also accepted for bulk-setting.

paymentMethod
string
Enum: "cc" "later"

Payment method accepted

requireGuestIdentification
boolean
Default: true

Whether purchase item guests require identification data. When set to false, guests do not need any identification information to complete a booking.

requireCCForSources
Array of strings

Sources requiring credit card collection

emailFooter
string

Custom email footer

object (GroupOptionsInput)

Group options input for creating/updating

object (DownDepositInput)

Down deposit input for creating/updating

object (FutureCutoffInput)

Future cutoff input for creating/updating

object (VirtualMeetingPreferenceInput)

Virtual meeting preference input for creating/updating

object (CatalogPreferenceInput)

Catalog preference input

object (UpsellPreferenceInput)

Upsell preference input for creating/updating experiences

Array of objects (ScheduleInput)

Schedule configurations

included
Array of strings

Items included in the experience

notIncluded
Array of strings

Items NOT included in the experience

Array of objects (MediaInput)

Media items to associate with experience

Array of objects (MediaInput)

PDF attachments for the experience

Array of objects (TravelerNotificationPreference)

Experience-level overrides for traveler notification recipients. When provided, replaces the entire set of notification overrides for this experience. If a notification type is not included in this list, the system default recipients are used.

System defaults:

  • order_changed_to_traveler: organizer
  • invoice_changed_traveler: organizer
  • order_canceled_to_traveler: organizer
  • trip_reminder_to_traveler: travelers
  • review_reminder_to_traveler: organizer
  • waiver_reminder_to_traveler: organizer
CheckoutPreference (object) or null

Checkout preferences for this experience. Overrides seller-level checkout preferences when set. Set to null to clear and fall back to seller-level preferences.

Responses

Request samples

Content type
application/json
{
  • "name": "Grand Canyon Advanced Kayaking Adventure",
  • "seller": "507f1f77bcf86cd799439020",
  • "desc": "Updated description with more advanced techniques and longer duration.",
  • "price": 179.99,
  • "duration": 240,
  • "eventDuration": 210,
  • "requireAdult": true,
  • "cancellationPolicy": "Free cancellation up to 48 hours before the experience",
  • "checkoutPreference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "experience",
  • "name": "Kayaking Adventure in the Grand Canyon",
  • "desc": "Join us for an unforgettable kayaking adventure through the stunning Grand Canyon rapids.",
  • "price": 149.99,
  • "currency": "USD",
  • "seller": {
    },
  • "photo": {
    },
  • "medias": [
    ],
  • "catalog": {
    },
  • "status": "published",
  • "emailFooter": "Thank you for booking with us!",
  • "meta": { },
  • "checkoutPreference": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "reviewPreference": {
    },
  • "excerpt": "Thrilling kayaking adventure through Grand Canyon rapids",
  • "guestType": "normal",
  • "paymentMethod": "cc",
  • "cancellationPolicy": "Free cancellation up to 24 hours before the experience",
  • "other": "Participants should bring sunscreen and water",
  • "addOns": [ ],
  • "downDeposit": {
    },
  • "sortDemographics": false,
  • "cancellation": {
    },
  • "requireGuestIdentification": true,
  • "notifications": [
    ],
  • "group": {
    },
  • "requireCCForSources": [ ],
  • "updated": "2023-08-16T14:20:00Z",
  • "terms": {
    },
  • "category": "Water Sports",
  • "complete": true,
  • "reviewed": true,
  • "requireAdult": false,
  • "earlyReturn": false,
  • "priceSchemes": {
    },
  • "pickupAddress": "123 Adventure St, Grand Canyon, AZ 86023",
  • "isScheduled": true,
  • "geo": {
    },
  • "travelerPreference": {
    },
  • "included": [
    ],
  • "notIncluded": [
    ],
  • "attachments": [
    ],
  • "resources": [
    ],
  • "demographics": [ ],
  • "schedules": [
    ],
  • "waiverPreference": {},
  • "guidePreference": {
    },
  • "virtualMeeting": {
    },
  • "checkInPreference": {
    },
  • "purchaseExpirationOffset": 10080,
  • "firstCheckinExpirationOffset": 1440,
  • "businessHours": "Monday-Friday 9AM-5PM PST",
  • "openingHours": [ ],
  • "customerNamePreference": "required",
  • "checkInValiditySummary": {
    },
  • "balanceDueOffset": 1440,
  • "balanceDueReminder": false,
  • "autoChargeOnDepositReminder": false,
  • "inventory": {
    },
  • "duration": 120,
  • "eventDuration": 90,
  • "allowedPrivacies": [
    ],
  • "cutoff": 60,
  • "cutoffType": "pre_start",
  • "alternateCutoff": 30,
  • "arrivalOffset": 15,
  • "futureCutoff": {
    },
  • "waitlist": {
    },
  • "upsellPreference": {
    },
  • "catalogPreference": {
    },
  • "scheduleType": "time",
  • "qrCodePreference": {
    },
  • "visible": true
}

Delete experience

Delete an experience. This is typically a soft delete operation.

Important Notes

  • Existing bookings are NOT affected by deletion
  • Experience becomes unavailable for new bookings
  • Historical data and reports remain intact
  • Operation cannot be undone through the API

Authorization

  • Must be the owner of the experience or have admin privileges
  • Some experiences may be protected from deletion
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload experience media

Upload photos or videos for an experience. The request body should contain the raw image/video data.

Supported Formats

  • Images: JPG, PNG, WebP (max 10MB)
  • Videos: MP4, MOV (max 100MB)
  • YouTube/Vimeo: Provide URL in request body

Automatic Processing

  • Images are automatically resized and optimized
  • Thumbnails are generated for videos
  • File validation ensures only supported formats
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
qqfile
string
Example: qqfile=canyon-adventure.jpg

Legacy file upload parameter for filename (used by legacy upload clients). When present, indicates file upload via XHR with filename in query parameter.

caption
string
Example: caption=Stunning canyon views during kayaking

Optional caption for the uploaded media

Request Body schema:
required
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{}

Update experience media

Update metadata for an existing media item (such as caption or display order).

Updatable Fields

  • Caption/description text
  • Display order/position
  • Alt text for accessibility
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string
Example: 507f1f77bcf86cd799439030

Media item identifier

Request Body schema: application/json
required
caption
string <= 500 characters

Updated caption for the media

order
integer >= 0

Display order (0 = first)

Responses

Request samples

Content type
application/json
{
  • "caption": "Updated caption - Epic canyon adventures await",
  • "order": 1
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete experience media

Remove a media item from the experience. This permanently deletes the media file.

Important Notes

  • Deletion is permanent and cannot be undone
  • If this is the primary photo, another image may be automatically selected
  • References to this media in other contexts may become broken
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string
Example: 507f1f77bcf86cd799439030

Media item identifier

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get experience fees

Returns the fees that are applicable to this experience, including processing fees, service fees, and any other charges that may apply to bookings.

Fee Types

  • Processing fees: Credit card and payment processing charges
  • Service fees: Platform or booking fees
  • Seller fees: Custom fees defined by the seller

Usage

Used primarily for pricing calculations and displaying total costs to customers.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get upcoming available dates

Get a list of future dates that have availability for the given experience.

Use Cases

  • Calendar display for booking interfaces
  • Quick availability checking
  • Next available date suggestions

Availability Logic

  • Only shows dates within the next 365 days
  • Respects experience scheduling and capacity constraints
  • Considers existing bookings and blocks
  • Applies minimum quantity requirements if specified
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
quantity
integer >= 1
Default: 1
Example: quantity=2

Minimum quantity/seats required for availability

limit
integer [ 1 .. 20 ]
Default: 5
Example: limit=10

Maximum number of dates to return

privacy
string
Enum: "public" "private"
Example: privacy=public

Privacy level for the booking (public/private)

startDate
string <date>
Example: startDate=2023-09-01

Start date for availability search (YYYY-MM-DD)

overrideFutureCutoff
boolean
Default: false

Whether to override future booking cutoff restrictions

package
string
Example: package=507f1f77bcf86cd799439030

Package ID to filter upcoming dates. When provided, only dates available for the specified package are returned.

Responses

Response samples

Content type
application/json
[
  • "2023-09-15",
  • "2023-09-16",
  • "2023-09-18",
  • "2023-09-20",
  • "2023-09-22"
]

Get pickup location map

Returns a static map image showing the pickup location for the experience.

Image Details

  • Format: PNG
  • Size: 600x218 pixels
  • Shows pickup location with marker
  • Cached for performance (1 hour TTL)

Requirements

  • Experience must have geographic coordinates set
  • Google Maps API integration must be configured
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get check-in validity summary

Returns check-in validation rules and requirements for the experience.

Check-In Types

  • Manual: Staff manually marks guests as checked in
  • QR Code: Guests scan QR codes to check in
  • Digital: Mobile app or web-based check-in

Validation Rules

  • Time windows for check-in (before/after start time)
  • Required information from guests
  • Check-in location restrictions
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "type": "qr_code",
  • "timeWindow": {
    },
  • "requirements": [
    ],
  • "location": {
    }
}

Upload experience attachment

Upload PDF attachments for an experience. These attachments are typically sent as part of order confirmation emails when bookings are created.

Supported Formats

  • PDF files only (max 50MB)
  • Attachments are validated for content and size

Use Cases

  • Booking confirmations and vouchers
  • Waiver forms and legal documents
  • Maps, directions, and meeting point information
  • Equipment lists and preparation guides
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
qqfile
string
Example: qqfile=booking-instructions.pdf

Filename when uploading via XHR

Request Body schema:
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 1,
  • "attachment": {
    }
}

Update experience attachment

Update an existing attachment's metadata or replace the file content.

Updatable Fields

  • Caption/description text
  • Replace PDF file content
  • Update title/name

File Replacement

  • Provide new PDF file to replace existing content
  • File validation applies (PDF format, size limits)
  • Original filename and ID are preserved
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

attachmentId
required
string
Example: 507f1f77bcf86cd799439080

Attachment identifier

query Parameters
qqfile
string

Filename when uploading via XHR

Request Body schema:
required
caption
string <= 500 characters

Updated caption for the attachment

title
string <= 255 characters

Updated title for the attachment

Responses

Request samples

Content type
{
  • "caption": "Updated booking instructions with new meeting point",
  • "title": "Booking Instructions v2"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete experience attachment

Delete an attachment and remove it from the experience. This permanently removes the file from storage.

Important Notes

  • Deletion is permanent and cannot be undone
  • File is removed from both database and file system
  • References in email templates may become broken
  • Existing bookings are not affected
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

attachmentId
required
string
Example: 507f1f77bcf86cd799439080

Attachment identifier

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439080",
  • "unlinkResult": true
}

Assign resource to experience

Assigns a pre-existing resource (inventory item) to an experience. Resources are fixed assets that can be utilized across multiple experiences. You must have the Inventory feature enabled for this endpoint to work.

Resource Concepts:

  • Capacity: How many people, seats, or units are in each piece of equipment
  • Count: How many units of equipment you have

Restrictions:

  • Resources can only be assigned to scheduled experiences
  • If multiple equipment feature is not enabled, only one equipment resource is allowed per experience
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the experience

Request Body schema: application/json
required
required
object (ObjectReference)

Reference to the resource to assign

Responses

Request samples

Content type
application/json
{
  • "resource": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "resource": {
    },
  • "priority": 100
}

Unassign resource from experience

Remove the assignment of a resource (inventory item) from an experience. This will also remove the resource from all existing events for this experience.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the experience

resourceId
required
string
Example: 507f1f77bcf86cd799439011

The unique identifier of the resource to unassign

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create or update waitlist preference

Create or update the waitlist preference for an experience. This configures how the waitlist feature behaves for the experience, including where it is enabled (checkout, back office, capped events), the checkout message, the invite delay, notification strategy, and the per-slot limit.

Waitlists are only supported on scheduled experiences; a request against a non-scheduled experience is rejected with a cannot_support_waitlist_feature_for_non_scheduled_experience validation error.

Authorization:

  • Requires EDIT_EXPERIENCE permission on the experience.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Experience ID

Request Body schema: application/json
required
enabled
boolean

Whether waitlist is globally enabled

enabledForCheckout
boolean

Whether waitlist is enabled for the checkout app

enabledForBackOffice
boolean

Whether waitlist is enabled for back office

enabledForCappedEvents
boolean

Whether waitlist is enabled for events whose capacity is capped

checkoutMessage
string <= 600 characters

Message to show on checkout when waitlist is available

inviteDelay
integer >= 0

Delay time in minutes after slots open before sending waitlist invite emails

object (WaitlistNotificationPreferenceInput)

Waitlist notification strategy input

object (WaitlistLimitPreferenceInput)

Waitlist size limitation input

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "enabledForCheckout": true,
  • "enabledForCappedEvents": true,
  • "checkoutMessage": "Join our waitlist to be notified when spots become available",
  • "inviteDelay": 5,
  • "notification": {
    },
  • "limit": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "enabled": true,
  • "enabledForCheckout": true,
  • "enabledForBackOffice": true,
  • "enabledForCappedEvents": true,
  • "checkoutMessage": "Join our waitlist to be notified when spots become available",
  • "inviteDelay": 5,
  • "notification": {
    },
  • "limit": {
    }
}

Create or update waitlist preference

Create or update the waitlist preference for an experience. Behaves identically to the POST method.

Waitlists are only supported on scheduled experiences; a request against a non-scheduled experience is rejected with a cannot_support_waitlist_feature_for_non_scheduled_experience validation error.

Authorization:

  • Requires EDIT_EXPERIENCE permission on the experience.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Experience ID

Request Body schema: application/json
required
enabled
boolean

Whether waitlist is globally enabled

enabledForCheckout
boolean

Whether waitlist is enabled for the checkout app

enabledForBackOffice
boolean

Whether waitlist is enabled for back office

enabledForCappedEvents
boolean

Whether waitlist is enabled for events whose capacity is capped

checkoutMessage
string <= 600 characters

Message to show on checkout when waitlist is available

inviteDelay
integer >= 0

Delay time in minutes after slots open before sending waitlist invite emails

object (WaitlistNotificationPreferenceInput)

Waitlist notification strategy input

object (WaitlistLimitPreferenceInput)

Waitlist size limitation input

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "enabledForCheckout": true,
  • "enabledForBackOffice": true,
  • "enabledForCappedEvents": true,
  • "checkoutMessage": "Join our waitlist to be notified when spots become available",
  • "inviteDelay": 5,
  • "notification": {
    },
  • "limit": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "enabled": true,
  • "enabledForCheckout": true,
  • "enabledForBackOffice": true,
  • "enabledForCappedEvents": true,
  • "checkoutMessage": "Join our waitlist to be notified when spots become available",
  • "inviteDelay": 5,
  • "notification": {
    },
  • "limit": {
    }
}

Create or update reschedule preference

Create or update the reschedule preference for an experience's traveler preference. This configures how self-service rescheduling behaves for travelers, including cutoff timing and price change policies.

Also available via the alias endpoint /experiences/{id}/travelerPreference/arrival.

Price Change Policy:

  • priceIncreasePolicy: Controls whether payment is required before or after modification
  • priceDecreasePolicy: Controls whether to refund the price difference or retain the original price

Authorization:

  • Requires EDIT_EXPERIENCE permission on the experience.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Experience ID

Request Body schema: application/json
required
object

Cutoff timing configuration for rescheduling

object

Policy for handling price changes during self-service modifications

Responses

Request samples

Content type
application/json
Example
{
  • "cutoff": {
    },
  • "priceChangePolicy": {
    }
}

Response samples

Content type
application/json
{
  • "reschedule": {
    },
  • "cancellation": null,
  • "questionnaire": null,
  • "allowPayment": null
}

Create or update reschedule preference

Create or update the reschedule preference for an experience's traveler preference. Behaves identically to the POST method.

Authorization:

  • Requires EDIT_EXPERIENCE permission on the experience.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Experience ID

Request Body schema: application/json
required
object

Cutoff timing configuration for rescheduling

object

Policy for handling price changes during self-service modifications

Responses

Request samples

Content type
application/json
{
  • "cutoff": {
    },
  • "priceChangePolicy": {
    }
}

Response samples

Content type
application/json
{
  • "reschedule": {
    },
  • "cancellation": {
    },
  • "questionnaire": { },
  • "allowPayment": { }
}

Delete reschedule preference

Remove the reschedule preference from an experience's traveler preference.

Authorization:

  • Requires EDIT_EXPERIENCE permission on the experience.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Experience ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get questionnaire for an experience

Retrieve the questionnaire form that applies to a specific experience. The system will first look for an experience-specific form, and if none exists, it will fall back to the seller's global questionnaire.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860eb

The unique identifier of the experience

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

features

User and seller feature flag management

Get all feature flags for a user

Returns all feature flags configured for a specific user account.

Feature flags control access to various features and capabilities within the system. This endpoint requires VIEW_USER_FEATURES permission on the target user.

Authorization:

  • Requires VIEW_USER_FEATURES permission
  • Users can view their own features
  • Admins and authorized sellers can view user features
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "googleAnalytics": true,
  • "advancedReporting": false,
  • "mobileApp": true,
  • "customBranding": true
}

Get the value of a specific feature flag

Returns the value of a specific feature flag for a user.

Public Features: Some features are publicly accessible without authentication:

  • googleAnalytics

Authorization:

  • Public features: No authentication required
  • Private features: Requires VIEW_USER_FEATURES permission
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

feature
required
string
Example: googleAnalytics

The name/key of the feature flag to retrieve

Responses

Response samples

Content type
application/json
Example
true

Activate a feature for a seller

Activates a feature flag for a seller account. This endpoint enables specific features for sellers based on their subscription plan and permissions.

Authorization:

  • Requires EDIT_USER_FEATURES permission on the seller
  • Admin users can enable any feature
  • App Store users can enable subscription features
  • Regular users can only enable features included in their subscription plan

Feature Validation:

  • Non-admin users cannot enable beta features
  • Non-admin users cannot enable features outside their subscription
  • Requests for unavailable features trigger an email notification to Xola

Side Effects:

  • Creates an audit log entry
  • Triggers a SELLER_UPDATE event
  • May send feature request emails to Xola for restricted features
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to activate

Request Body schema: application/json
optional

Feature ID in request body (alternative to path parameter)

id
string

The feature ID to activate

Responses

Request samples

Content type
application/json
{
  • "id": "mobileApp"
}

Response samples

Content type
application/json
{
  • "id": "advancedReporting"
}

Activate a feature for a seller (PUT method)

Alternative PUT method for activating a feature flag for a seller account. Behaves identically to the POST method.

See the POST method documentation for complete details on authorization, validation, and side effects.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to activate

Request Body schema: application/json
optional

Feature ID in request body (alternative to path parameter)

id
string

The feature ID to activate

Responses

Request samples

Content type
application/json
{
  • "id": "mobileApp"
}

Response samples

Content type
application/json
{
  • "id": "advancedReporting"
}

Deactivate a feature for a seller

Deactivates a feature flag for a seller account. This removes access to the specified feature for the seller.

Authorization:

  • Requires EDIT_USER_FEATURES permission on the seller
  • Sellers can deactivate their own features
  • Admins can deactivate any seller's features

Side Effects:

  • Creates an audit log entry
  • Triggers a SELLER_UPDATE event
  • Non-admin deactivations send a notification email to Xola
  • May trigger subscription package changes

Important: Deactivating a feature may affect the seller's subscription package eligibility and will notify Xola staff for review.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to deactivate

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

forms

Forms (also called "questionnaires") are collections of questions that you can ask travelers during or after the order creation flow.

In the Xola Seller App, this corresponds to the Global or Product-specific Questionnaire. These questions may be presented to a purchaser during or immediately after the checkout process.

Forms may be required or optional, and may be requested for each member of a booking party, or only the party organizer.

List forms

Retrieve a paginated list of forms.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

seller
string

Filter forms by seller ID

productType
string
Enum: "experience" "package" "membership"

Filter forms by product type

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": null
}

Create a new form

Create a new questionnaire form. Forms can be either:

  • Global (seller-level): Applied to all experiences for a seller when no product-specific form exists
  • Product-specific: Applied only to a specific experience, package, or membership

Only one form can exist per product. If a product-specific form already exists, a conflict error will be returned.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
object (ObjectReference)

Reference to the seller who will own this form

ObjectReference (object) or null

Reference to specific product. Omit for global forms.

productType
string
Default: "experience"
Enum: "experience" "package" "membership"

Type of product this form is designed for

required
Array of objects (FormFieldBase)

List of form fields to create

optionalSourcesList
Array of strings
Default: []

List of booking sources for which questionnaire completion is optional

Responses

Request samples

Content type
application/json
Example
{
  • "seller": {
    },
  • "productType": "experience",
  • "optionalSourcesList": [ ],
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Retrieve a specific form

Get detailed information about a specific form by its ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

The unique identifier of the form

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": false,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ]
}

Update a form

Update an existing form. This endpoint allows updating:

  • Form field configurations (labels, descriptions, URLs, etc.)
  • Optional sources list

Field types cannot be changed through this endpoint. If a field type needs to be changed, the field must be removed and recreated.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

The unique identifier of the form

Request Body schema: application/json
required
Array of objects (FormFieldUpdate)

List of fields to update. Include 'id' for existing fields to update them, or omit 'id' to create new fields. Fields not included will be removed.

optionalSourcesList
Array of strings

Updated list of optional booking sources

Responses

Request samples

Content type
application/json
{
  • "fields": [
    ],
  • "optionalSourcesList": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Delete a form

Soft delete a form. The form will be marked as deleted but not physically removed from the database. Once deleted, the form will no longer appear in API responses and cannot be used for new bookings.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

The unique identifier of the form

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get questionnaire for an experience

Retrieve the questionnaire form that applies to a specific experience. The system will first look for an experience-specific form, and if none exists, it will fall back to the seller's global questionnaire.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860eb

The unique identifier of the experience

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Get global questionnaire for a seller

Retrieve the global questionnaire form for a seller. This form applies to all experiences when no experience-specific form exists.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the seller

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Get questions for a specific purchase item

Retrieve the questionnaire that applies to a specific item within a purchase. This is useful for purchases with multiple items that may have different questionnaires.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

itemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Upload photos for purchase item form response fields

Upload one or more photos for photo-type fields in a purchase item's form response. Photos are uploaded via multipart form data with a photos key containing an associative array where each key is the field label and the value is the photo file.

Supported image types: JPEG, PNG, GIF, WebP (max 5MB per file).

If a photo field response already exists for the given label, the photo will be replaced. Label matching is case-insensitive.

Permission: Requires EDIT_PURCHASE_FORM_RESPONSE permission.

Validation Errors:

  • missing_photos: No photos were provided in the request
  • no_form_for_product: No questionnaire is configured for this purchase item's product
  • unknown_label: The provided label does not match any photo field in the form
  • file_too_large: Photo file exceeds maximum size of 5MB
  • invalid_file_extension: Only JPEG, PNG, GIF, and WebP files are allowed
  • invalid_image_type: Only JPEG, PNG, GIF, and WebP images are allowed
  • mime_type_mismatch: File extension does not match the image type
  • upload_failed: File storage upload failed
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

purchaseItemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

Request Body schema: multipart/form-data
required
required
object

An associative array of photo files keyed by field label. Each key should match the label of a photo-type field in the form.

Responses

Request samples

Content type
multipart/form-data
Example
{
  "photos": {
    "ID Photo": "(binary file data)"
  }
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ee",
  • "name": "John Doe",
  • "fields": [
    ]
}

Get an uploaded photo for a form response field

Retrieve an uploaded photo for a specific photo-type field in a purchase item's form response. Returns the image binary with appropriate Content-Type and Content-Disposition headers.

Label matching is case-insensitive.

Permission: Requires EDIT_PURCHASE_FORM_RESPONSE permission.

Returns 404 if the purchase item, form response, or photo file is not found. Returns a validation error with reason invalid_type if the field exists but is not a photo field.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

purchaseItemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

fieldLabel
required
string
Example: ID Photo

The label of the photo field to retrieve (case-insensitive)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Gift Offers

Gift certificates allow customers to purchase a specific activity, or a redeemable dollar amount, for their friends or family. Whenever a Gift is purchased it generates a special code, and this code can be used to pay for any new or existing booking.

List all gift offers

Retrieve all gift offers with optional filtering and pagination

Authorizations:
apiKeybasicAuth
query Parameters
expand
string
Enum: "experience" "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

skip
integer >= 0
Default: 0

Number of items to skip

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

seller
string

Filter by seller ID

system
boolean

Filter by system generated gift offers. This typically includes one gift offer per experience.

baseGiftProduct
boolean

Filter for "Choose an amount" type gift offers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new gift offer

Create a new gift offer for a seller

Authorizations:
apiKeybasicAuth
query Parameters
expand
string
Enum: "experience" "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

Request Body schema: application/json
required
name
required
string
desc
string

Description of the gift offer

required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

price
number <float>

Price of the gift offer

minimumPrice
number <float>

Minimum price for variable gift offers

currency
string

Currency code (e.g., USD)

type
string
Enum: "fixed" "variable"

Type of gift offer

status
string
system
boolean

Whether this is a system gift offer

baseGiftProduct
boolean

Whether this is a base gift product

emailReminder
boolean

Whether to send email reminders

emailReminderDays
integer

Days before expiry to send reminder

experience
string

Experience ID to associate with this gift offer

photo
string

Media ID for the gift offer photo

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "desc": "string",
  • "seller": {
    },
  • "price": 0.1,
  • "minimumPrice": 0.1,
  • "currency": "string",
  • "type": "fixed",
  • "status": "string",
  • "system": true,
  • "baseGiftProduct": true,
  • "emailReminder": true,
  • "emailReminderDays": 0,
  • "experience": "string",
  • "photo": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "desc": "string",
  • "seller": {
    },
  • "price": 0.1,
  • "minimumPrice": 0.1,
  • "currency": "string",
  • "type": "fixed",
  • "status": "string",
  • "system": true,
  • "baseGiftProduct": true,
  • "emailReminder": true,
  • "emailReminderDays": 0,
  • "id": "string",
  • "photo": {
    },
  • "medias": [
    ],
  • "experience": {
    },
  • "purchaseRule": {
    },
  • "redemptionPurchaseRule": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": {
    },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    }
}

Get a specific gift offer

Retrieve a gift offer by its ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Enum: "experience" "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "desc": "string",
  • "seller": {
    },
  • "price": 0.1,
  • "minimumPrice": 0.1,
  • "currency": "string",
  • "type": "fixed",
  • "status": "string",
  • "system": true,
  • "baseGiftProduct": true,
  • "emailReminder": true,
  • "emailReminderDays": 0,
  • "id": "string",
  • "photo": {
    },
  • "medias": [
    ],
  • "experience": {
    },
  • "purchaseRule": {
    },
  • "redemptionPurchaseRule": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": {
    },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    }
}

Update a gift offer

Update an existing gift offer

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Enum: "experience" "purchaseRule"

You can expand multiple objects at the same time by providing a comma-separated list of values

Request Body schema: application/json
required
name
required
string
desc
string

Description of the gift offer

required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

price
number <float>

Price of the gift offer

minimumPrice
number <float>

Minimum price for variable gift offers

currency
string

Currency code (e.g., USD)

type
string
Enum: "fixed" "variable"

Type of gift offer

status
string
system
boolean

Whether this is a system gift offer

baseGiftProduct
boolean

Whether this is a base gift product

emailReminder
boolean

Whether to send email reminders

emailReminderDays
integer

Days before expiry to send reminder

experience
string

Experience ID to associate with this gift offer

photo
string

Media ID for the gift offer photo

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "desc": "string",
  • "seller": {
    },
  • "price": 0.1,
  • "minimumPrice": 0.1,
  • "currency": "string",
  • "type": "fixed",
  • "status": "string",
  • "system": true,
  • "baseGiftProduct": true,
  • "emailReminder": true,
  • "emailReminderDays": 0,
  • "experience": "string",
  • "photo": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "desc": "string",
  • "seller": {
    },
  • "price": 0.1,
  • "minimumPrice": 0.1,
  • "currency": "string",
  • "type": "fixed",
  • "status": "string",
  • "system": true,
  • "baseGiftProduct": true,
  • "emailReminder": true,
  • "emailReminderDays": 0,
  • "id": "string",
  • "photo": {
    },
  • "medias": [
    ],
  • "experience": {
    },
  • "purchaseRule": {
    },
  • "redemptionPurchaseRule": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": {
    },
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    }
}

Delete a gift offer

Soft delete a gift offer (sets deletedAt timestamp)

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{ }

Upload media for a gift offer

Upload a photo/media file for a gift offer.

Supported Formats

  • Images: JPEG, PNG, GIF only (max 5MB)

Upload Methods

XHR Upload: Send raw binary data in request body with Content-Type header set to the image MIME type. Use the qqfile query parameter to specify the filename.

Form Upload: Send as multipart/form-data with the file in the qqfile field.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
qqfile
string
Example: qqfile=gift-image.jpg

Legacy file upload parameter for filename (used by legacy upload clients). Optional for form uploads; for XHR uploads, use this parameter to provide the original file name and preserve it on the server.

Request Body schema:
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 1,
  • "media": {
    },
  • "photo": {
    }
}

Get media file

Retrieve a media file for a gift offer with optional resizing

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string

Media ID or "default" for the default image

query Parameters
size
string

Image size filter (bg for background, or other size options)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update media caption

Update the caption for a specific media item

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string

The media ID to update

Request Body schema: application/json
required
caption
string

New caption for the media

Responses

Request samples

Content type
application/json
{
  • "caption": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete a media item

Remove a media item from a gift offer

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

mediaId
required
string

The media ID to delete

Responses

Response samples

Content type
application/json
{
  • "id": "string"
}

gratuities

Gratuities record tips left for experience bookings. A gratuity captures the tip amount, an optional comment, the payment used to collect it, and references back to the booking it relates to - the experience purchase item, the guide, and the event.

Gratuities are created against an experience purchase item; experience products are the only products that support gratuities.

Who can create and view gratuities

Creating a gratuity is a traveler-facing action: it can be performed by the purchase organizer or by any traveler on the booking. When a non-traveler user creates a gratuity, they must attribute it to a traveler that belongs to the purchase.

Listing and retrieving gratuities is scoped to the requesting account: a seller sees their own gratuities, delegates see gratuities for the seller accounts they manage (guide-only delegates see only gratuities that reference them as a guide), and administrators see all.

Reconciliation status

A gratuity starts in the pending status. Once it has been reconciled into a payout it moves to reconciled. The status field reflects this lifecycle, and the list endpoint can be filtered by it.

Exporting gratuities

The list endpoint can produce an asynchronous export instead of an inline list by setting the format query parameter. An export requires a seller and returns a 202 Accepted with an export job; poll the jobs endpoint with the returned job ID to track progress and retrieve the generated file.

Create a gratuity on a purchase item

Create a gratuity for an experience purchase item. Gratuities are only supported on experience products.

This endpoint may be used by the purchase organizer or any traveler on the booking. When called by a non-traveler user, a traveler reference is required and must belong to the purchase.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

ID of the experience purchase item to tip.

Request Body schema: application/json
required

Gratuity to create

amount
required
number <float> > 0

The gratuity amount. Must be greater than zero.

comment
required
string

A comment describing the gratuity.

required
object (GratuityPaymentRequest)

The payment used to collect the gratuity. The required fields depend on the method. When method is intent, a paymentIntent reference is required (either nested here or as a top-level paymentIntent on the request).

object

Reference to the Stripe payment intent. Required when the payment method is intent and not nested inside payment.

object

The traveler the gratuity is attributed to. Required when the request is made by a non-traveler user; the traveler must belong to the purchase.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 20,
  • "comment": "Thanks for a great tour!",
  • "payment": {
    }
}

Response samples

Content type
application/json
{
  • "object": "gratuity",
  • "id": "507f1f77bcf86cd799439099",
  • "amount": 20,
  • "comment": "Thanks for a great tour!",
  • "status": "pending",
  • "seller": {
    },
  • "createdAt": "2026-06-29T10:30:00+00:00",
  • "createdBy": {
    },
  • "payment": {
    },
  • "references": [
    ]
}

List gratuities

Retrieve a paginated list of gratuities. Results are automatically scoped to the gratuities the authenticated user is allowed to see: a seller sees their own gratuities; delegates see gratuities for the seller accounts they manage (guide-only delegates see only gratuities that reference them as a guide); administrators see all.

Set the format query parameter to request an asynchronous export instead of an inline list. When exporting, the seller parameter is required and the response is a 202 Accepted with an export job to poll.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=507f1f77bcf86cd799439010

Filter by seller ID. Required when format is set (export).

references
string
Example: references=507f1f77bcf86cd799439011

Filter by a referenced object ID (for example a purchase item, event, or guide). Supports in for matching multiple IDs.

references_object
string
Enum: "scheduled_experience_purchase_item" "user_profile" "event"
Example: references_object=scheduled_experience_purchase_item

Filter by referenced object type. Supports in and nin to include or exclude specific object types.

status
string
Enum: "pending" "reconciled"
Example: status=pending

Filter by reconciliation status.

createdAt
string
Example: createdAt=2026-01-01,2026-12-31

Filter by creation time. Supports comparison operators (gt, gte, lt, lte), range, period, in, nin, and exists. Accepts Unix timestamps or ISO 8601 date-times.

sort
string
Example: sort=-createdAt

Comma-separated list of fields to sort by, each optionally prefixed with - for descending order. Defaults to -id.

expand
string
Example: expand=transaction,references.scheduled_experience_purchase_item

Comma-separated list of related objects to expand inline rather than returning ID references. Use references.<object> to expand a reference (for example references.scheduled_experience_purchase_item).

format
string
Value: "csv"
Example: format=csv

When set, an asynchronous export job is created instead of returning an inline list. Requires seller.

skip
integer >= 0
Default: 0

Number of items to skip

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Get a gratuity

Retrieve a single gratuity by its ID. Access is limited to the gratuity's seller, seller delegates, and administrators.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Example: expand=transaction

Comma-separated list of related objects to expand inline. Use transaction and references.<object> (for example references.scheduled_experience_purchase_item).

Responses

Response samples

Content type
application/json
{
  • "object": "gratuity",
  • "id": "507f1f77bcf86cd799439099",
  • "amount": 20,
  • "comment": "Thanks for a great tour!",
  • "status": "pending",
  • "seller": {
    },
  • "createdAt": "2026-06-29T10:30:00+00:00",
  • "createdBy": {
    },
  • "payment": {
    },
  • "references": [
    ]
}

guides

Guide management and scheduling

List guides for a seller

Retrieve a paginated list of guides belonging to a specific seller. Supports filtering by availability for events.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

query Parameters
name
string
Example: name=Sarah

Filter guides by name (partial match)

events
string

Event ID to check guide availability against

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new guide

Create a new guide for a seller. Can create a guide for an existing user or create a new user account.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

Request Body schema: application/json
required
name
required
string

Full name of the guide

bio
string or null

Biography or description of the guide

phone
string or null

Phone number of the guide

Media (object) or null

Profile picture of the guide

Array of objects (BaseSchedule)

Guide availability schedules

GuidePermissionPreference (object) or null

Permissions related to guide schedule modifications

OverlappingEventsPreference (object) or null

Preferences for handling overlapping event assignments

required
object

User account information for the guide

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Sarah Johnson",
  • "bio": "Experienced outdoor guide with 10 years in adventure tourism",
  • "phone": "+1-617-555-1234",
  • "user": {
    },
  • "guidePermission": {
    },
  • "overlappingEvents": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "user_profile",
  • "name": "Sarah Johnson",
  • "bio": "Experienced outdoor guide with 10 years in adventure tourism",
  • "phone": "+1-617-555-1234",
  • "picture": null,
  • "user": {
    },
  • "seller": {
    },
  • "schedules": [ ],
  • "createdBy": {
    },
  • "updatedAt": "2024-01-15T10:30:00Z",
  • "deletedAt": null,
  • "deletedBy": null,
  • "guidePermission": {
    },
  • "overlappingEvents": {
    }
}

Retrieve a guide

Get detailed information about a specific guide.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "user_profile",
  • "name": "Sarah Johnson",
  • "bio": "Experienced outdoor guide with 10 years in adventure tourism",
  • "phone": "+1-617-555-1234",
  • "picture": null,
  • "user": {
    },
  • "seller": {
    },
  • "schedules": [ ],
  • "createdBy": {
    },
  • "updatedAt": "2024-01-15T10:30:00Z",
  • "deletedAt": null,
  • "deletedBy": null,
  • "guidePermission": {
    },
  • "overlappingEvents": {
    }
}

Update a guide

Update information for an existing guide.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

Request Body schema: application/json
required
name
string

Updated full name of the guide

bio
string or null

Updated biography or description of the guide

phone
string or null

Updated phone number of the guide

Media (object) or null

Updated profile picture of the guide

Array of objects (BaseSchedule)

Updated guide availability schedules

GuidePermissionPreference (object) or null

Updated permissions related to guide schedule modifications

OverlappingEventsPreference (object) or null

Updated preferences for handling overlapping event assignments

Responses

Request samples

Content type
application/json
Example
{
  • "bio": "Senior outdoor guide with 15 years in adventure tourism"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "user_profile",
  • "name": "Sarah Johnson",
  • "bio": "Senior outdoor guide with 15 years in adventure tourism",
  • "phone": "+1-617-555-1234",
  • "picture": null,
  • "user": {
    },
  • "seller": {
    },
  • "schedules": [ ],
  • "createdBy": {
    },
  • "updatedAt": "2024-01-16T14:20:00Z",
  • "deletedAt": null,
  • "deletedBy": null,
  • "guidePermission": {
    },
  • "overlappingEvents": {
    }
}

Delete a guide

Delete a guide. The guide cannot be deleted if they are assigned to future events.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload guide media

Upload a profile picture or other media for a guide.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

Request Body schema: multipart/form-data
required
picture
required
string <binary>

Profile picture file to upload

Responses

Response samples

Content type
application/json
{}

Delete guide media

Delete a specific media item (profile picture) from a guide.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

mediaId
required
string

Media ID to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get guide picture

Redirects to the guide's profile picture URL.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Seller ID

guideId
required
string

Guide ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

jobs

Asynchronous job tracking (exports, imports, dispute evidence)

Get job by ID

Retrieve the status and details of an asynchronous job. Jobs are created by async operations such as CSV purchase imports and dispute evidence exports.

Job Types:

  • CSV import jobs - created by POST /purchases with CSV file upload
  • exportDisputeEvidence - created by GET /purchases/{id}/disputeEvidence. Includes additional fields: url (S3 download URL), filename (zip file name), purchase (purchase ID).

Poll this endpoint to track job progress. Terminal statuses:

  • completed - job finished successfully
  • error - job failed (see error details in response)
  • stale - job timed out or became stale
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "status": "completed",
  • "progress": 100,
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedAt": "2024-01-15T10:31:00Z"
}

lineItemTemplates

A LineItemTemplate is the blueprint for a line item. It stores the initial schema for the different types of line items (demographics, add-ons, taxes, fees, coupon discounts) that can be added to a purchase. Every line item uses a template to set initial values for fields like type, destination, visibility, and name; purchase rules then operate on the resulting line items to modify certain fields.

When creating a purchase, the traveler (or whoever is placing the purchase) begins by selecting a set of line item templates (typically demographics and add-ons) and adding line items for these into their purchase. Purchase rules can then operate on the purchase to update price, amount, and other fields, and to add any other line items if required. In general, there is a line item template for each demographic, add-on, tax/fee, or coupon a seller has configured. A LineItemTemplate shares most of its fields with the LineItems created from it.

List line item templates

Retrieve a paginated list of line item templates for the authenticated seller.

Supports filtering and pagination. Returns both LineItemTemplate and UnitLineItemTemplate objects depending on the template type.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create line item template

Create a new line item template. The template type determines whether a basic LineItemTemplate or UnitLineItemTemplate is created.

For unit-based templates, include the object field set to "unit_line_item_template" and provide a unit reference.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
One of
type
required
string
Enum: "tax" "fee" "discount" "coupon_discount" "partner_fee" "processing_fee" "sub_total" "package_discount" "affiliate_discount" "affiliate_commission" "affiliate_deposit" "feeable_taxable_adjustment"

Type of the line item template

destination
required
string
Enum: "seller" "xola"

Where the line item is directed

visible
required
boolean

Whether the line item is visible to customers

includeInAmount
required
boolean

Whether to include this line item in the total amount calculation

required
object (ObjectReference)

Reference to the seller who owns this template

source
string
Enum: "seller" "traveler"

Source of the line item template (for partner fee items)

visibility
string
Enum: "all" "none" "xola" "seller" "traveler" "affiliate" "guide"

Visibility setting for the line item

lineItemObject
string
Default: "line_item"

The object type for line items created from this template

name
string

Human-readable name of the line item template

code
string

Unique code identifier for the template

refundToTraveler
boolean

Whether the partner fee can be refunded to traveler (valid only if paid by traveler)

refundToSeller
boolean

Whether the partner fee can be refunded to seller

excludeFromUnitPrice
boolean

Whether to exclude from tax calculation for prices shown during checkout

Responses

Request samples

Content type
application/json
Example
{
  • "type": "fee",
  • "destination": "seller",
  • "visible": true,
  • "includeInAmount": false,
  • "seller": {
    },
  • "name": "Service Fee"
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "unit_line_item_template",
  • "type": "fee",
  • "name": "Adult",
  • "destination": "seller",
  • "visible": true,
  • "system": false,
  • "includeInAmount": true,
  • "unit": {
    },
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T10:30:00Z"
}

Get line item template by ID

Retrieve a specific line item template by its unique identifier.

Returns either a LineItemTemplate or UnitLineItemTemplate object depending on the template type.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier of the line item template

Responses

Response samples

Content type
application/json
Example
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "unit_line_item_template",
  • "type": "fee",
  • "name": "Adult",
  • "code": "ADULT_001",
  • "destination": "seller",
  • "visibility": "all",
  • "visible": true,
  • "system": false,
  • "includeInAmount": true,
  • "lineItemObject": "line_item",
  • "unit": {
    },
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z"
}

Update line item template

Update an existing line item template with new data.

Only provided fields will be updated. Immutable fields like object and id cannot be changed.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier of the line item template

Request Body schema: application/json
required
One of
type
required
string
Enum: "tax" "fee" "discount" "coupon_discount" "partner_fee" "processing_fee" "sub_total" "package_discount" "affiliate_discount" "affiliate_commission" "affiliate_deposit" "feeable_taxable_adjustment"

Type of the line item template

destination
required
string
Enum: "seller" "xola"

Where the line item is directed

visible
required
boolean

Whether the line item is visible to customers

includeInAmount
required
boolean

Whether to include this line item in the total amount calculation

required
object (ObjectReference)

Reference to the seller who owns this template

source
string
Enum: "seller" "traveler"

Source of the line item template (for partner fee items)

visibility
string
Enum: "all" "none" "xola" "seller" "traveler" "affiliate" "guide"

Visibility setting for the line item

lineItemObject
string
Default: "line_item"

The object type for line items created from this template

name
string

Human-readable name of the line item template

code
string

Unique code identifier for the template

refundToTraveler
boolean

Whether the partner fee can be refunded to traveler (valid only if paid by traveler)

refundToSeller
boolean

Whether the partner fee can be refunded to seller

excludeFromUnitPrice
boolean

Whether to exclude from tax calculation for prices shown during checkout

Responses

Request samples

Content type
application/json
Example
{
  • "type": "fee",
  • "destination": "xola",
  • "visible": false,
  • "includeInAmount": true,
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "unit_line_item_template",
  • "type": "fee",
  • "name": "Adult",
  • "destination": "seller",
  • "visible": true,
  • "system": false,
  • "includeInAmount": false,
  • "unit": {
    },
  • "seller": {
    },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T15:45:00Z"
}

Delete line item template

Soft delete a line item template. The template will be marked as deleted but preserved in the database for audit purposes.

Deleted templates will not appear in list responses unless specifically requested.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Unique identifier of the line item template

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

messages

Messages and message templates

List message templates

Retrieves a list of message templates for the authenticated user's accessible sellers.

Results can be filtered by seller and the existence of specific message channels (email or SMS). Supports pagination and sorting.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=60f7d1234567890abcdef123

Filter templates by seller ID

exists
string
Examples:
  • exists=email - Templates with email content
  • exists=sms - Templates with SMS content
  • exists=email,sms - Templates with both channels

Comma-separated list of fields that must exist. Common values: email, sms

object (DateTimeFilterSchema)
Examples: deletedAt[summary]=Find records where field exists (not null)&deletedAt[value]=[object Object] deletedAt[summary]=Find records where field is null/missing&deletedAt[value]=[object Object] deletedAt[summary]=Date range filtering&deletedAt[value]=[object Object] deletedAt[summary]=Range using comma-separated string&deletedAt[value]=[object Object] deletedAt[summary]=Using period for today&deletedAt[value]=[object Object] deletedAt[summary]=Using period for last week&deletedAt[value]=[object Object] deletedAt[summary]=Exact date-time match&deletedAt[value]=[object Object] deletedAt[summary]=After specific date&deletedAt[value]=[object Object]

Filter by deletion timestamp. Supports date-time filtering operations.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": "",
  • "_es": false
}

Create message template

Creates a new message template for the specified seller.

A message template must include at least one message channel (email and/or SMS). You can specify channels using either the email/sms properties or the channels array.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string

Seller ID (can be provided as query parameter or in request body)

Request Body schema: application/json
required
name
required
string <= 255 characters

Descriptive name for the message template

object (MessageContentRequest)

Email content configuration for this template

object (MessageContentRequest)

SMS content configuration for this template

Array of objects (ChannelRequest)

Alternative way to specify multiple message channels (email and/or SMS)

locale
string <locale>

The locale/language for this message template

object (ObjectReference)

Reference to the seller that will own this message template (required for POST requests)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Booking Confirmation",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en",
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "Booking Confirmation",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en",
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2024-01-15T10:30:00Z"
}

Get message template

Retrieves a specific message template by ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Message template ID

Responses

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "Booking Confirmation",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en",
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedBy": {
    },
  • "updatedAt": "2024-01-15T14:20:00Z"
}

Update message template

Updates an existing message template.

All updatable fields should be provided in the request body. The template cannot be updated if it has been soft-deleted.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Message template ID

Request Body schema: application/json
required
name
required
string <= 255 characters

Descriptive name for the message template

object (MessageContentRequest)

Email content configuration for this template

object (MessageContentRequest)

SMS content configuration for this template

Array of objects (ChannelRequest)

Alternative way to specify multiple message channels (email and/or SMS)

locale
string <locale>

The locale/language for this message template

object (ObjectReference)

Reference to the seller that will own this message template (required for POST requests)

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Booking Confirmation",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "Updated Booking Confirmation",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en",
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedBy": {
    },
  • "updatedAt": "2024-01-15T16:45:00Z"
}

Delete message template

Soft-deletes a message template by setting the deletedAt timestamp.

The template will no longer appear in regular API responses but can still be retrieved using the deletedAt[exists]=true filter parameter.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Message template ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Send messages to customers

Sends messages (email and/or SMS) to customers using a message template.

This endpoint can:

  • Use an existing message template by ID
  • Use inline message content in the request
  • Filter customers by order, event, date, or purchase criteria (for bulk messaging)
  • Preview messages without sending (dry run mode)

The messages will be sent to customers associated with the filtered orders/purchases.

Template Variables: Message content supports Twig template variables like:

  • {{purchase.customerName}} - Customer's full name
  • {{purchase.customerName|first_name}} - Customer's first name
  • {{purchase.productName}} - Product/experience name(s)
  • {{purchase.arrivalDate}} - Arrival date
  • {{purchase.quantity}} - Number of guests
  • {{seller.name}} - Seller name
  • {{seller.phone}} - Seller phone
  • {{seller.email}} - Seller email
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
required
MessageTemplateReference (object) or InlineMessageTemplate (object)

Either a reference to an existing template or inline template content

required
object (MessageFilters)

Criteria to select which customers receive the message

from
string <email>

Sender email address (for email messages)

Array of objects (MessageRecipient)

Specific recipients (optional - usually determined by filters)

dryRun
boolean
Default: false

When true, returns a preview without actually sending messages

Responses

Request samples

Content type
application/json
Example
{
  • "messageTemplate": {
    },
  • "filters": {
    },
  • "from": "bookings@example.com",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "Trip Reminder Template",
  • "email": {
    },
  • "sms": {
    },
  • "locale": "en",
  • "seller": {
    },
  • "createdBy": {
    },
  • "createdAt": "2024-01-15T10:30:00Z"
}

Preview message content

Generates a preview of rendered message content using template variables and customer data.

This endpoint renders the specified email template with actual or dummy data to show how the final message will appear. Returns HTML content suitable for preview display.

The template field in the request body determines which email layout to render. Depending on the template type, different fields are required or optional:

  • purchase.confirmation: Requires experience to look up a purchase for that experience.
  • purchase.gift.certificate: Requires giftOffer to look up a gift purchase.
  • purchase.reminder.review: The experience field is optional. If provided, the preview uses purchase data for that experience. If omitted, the endpoint falls back to the authenticated seller's context (using the seller's review preferences and a recent purchase from the seller's catalog). A ValidationException is returned if neither an experience nor a resolvable seller is available. Optionally accepts customHTML to render a custom review reminder template body.
  • communication.email / communication.sms: Requires messageTemplate with a reference to an existing template.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
template
required
string
Enum: "purchase.confirmation" "purchase.gift.certificate" "purchase.reminder.review" "communication.email" "communication.sms"

The template type identifier that determines which email layout to render. Supported values:

  • purchase.confirmation — Purchase confirmation email
  • purchase.gift.certificate — Gift certificate email
  • purchase.reminder.review — Review reminder email
  • communication.email — Custom communication email
  • communication.sms — Custom communication SMS
experience
string^[0-9a-fA-F]{24}$

Experience (product) ID used to generate preview data. Required for purchase.confirmation. Optional for purchase.reminder.review — if omitted, the seller's context is used as a fallback.

giftOffer
string^[0-9a-fA-F]{24}$

Gift offer ID used to generate preview data. Required for purchase.gift.certificate.

MessageTemplateReference (object) or InlineMessageTemplate (object)

Message template reference or inline content. Required for communication.email and communication.sms.

customHTML
string

Custom HTML content to render in place of the default review template body. Only applicable to purchase.reminder.review. When provided, the custom HTML is rendered with the template variables (purchase, seller, etc.) and displayed in the review reminder layout. Can be used alongside either an experience or seller-context fallback.

Responses

Request samples

Content type
application/json
Example
{
  • "template": "purchase.confirmation",
  • "experience": "60f7d1234567890abcdef123"
}

Response samples

Content type
text/html
<h1>How was your Adventure Tour?</h1>
<p>Hi John, we hope you enjoyed your experience!</p>
<p>We'd love to hear your feedback.</p>

Send message in conversation

Creates a new message within an existing conversation.

Supports three types of messages:

  • User messages (legacy): Regular messages with body and from fields
  • Multi-channel messages: Explicit formats, channels, and from fields. Required when targeting plugin channels. Both formats and channels must be non-empty.
  • System messages: Template-based messages with meta.template field

For v2 sellers, messages are handled differently than v1 sellers.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Conversation ID

Request Body schema: application/json
required
One of
body
required
string <= 10000 characters

Message content

from
required
string <email>

Sender email address

Responses

Request samples

Content type
application/json
Example
{
  • "body": "Thank you for your inquiry. We'll get back to you shortly.",
  • "from": "507f191e810c19729de860ea"
}

Response samples

Content type
application/json
{
  • "object": "message",
  • "id": "60f7d1234567890abcdef456",
  • "from": "507f191e810c19729de860ea",
  • "type": "email",
  • "system": false,
  • "channels": [
    ],
  • "formats": [
    ],
  • "to": [ ],
  • "createdAt": "2024-01-15T10:30:00Z"
}

Update message

Partially updates a message within a conversation.

Currently supports updating the body of a text-type format for messages sent via plugin channels only (not email or sms).

The request body must include a formats array with text-type format objects.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Conversation ID

messageId
required
string
Example: 60f7d1234567890abcdef456

Message ID

Request Body schema: application/json
required
required
Array of objects non-empty

Array of format objects to update. Only text format body updates are supported.

Responses

Request samples

Content type
application/json
{
  • "formats": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef456"
}

Delete message

Soft-deletes a message within a conversation.

The message is not permanently removed - deletedAt and deletedBy fields are set on the message document. The message will still appear in conversation responses but will have the deletedAt timestamp set.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Conversation ID

messageId
required
string
Example: 60f7d1234567890abcdef456

Message ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update message delivery status

Updates delivery status and error information for a message. Used by external systems to report delivery status.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Conversation ID

messageId
required
string
Example: 60f7d1234567890abcdef456

Message ID

Request Body schema: application/json
required
status
required
string
Enum: "pending" "sent" "delivered" "failed" "read"

Delivery status

error
string

Error description if delivery failed

Responses

Request samples

Content type
application/json
Example
{
  • "status": "delivered"
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef456"
}

packages

Packages bundle multiple experiences so they can be sold together as a single offering, optionally at a discount. A package is a kind of product, so it shares many fields with experiences - name, description, pricing, media, and cancellation policy - while adding the experiences it bundles and how they are grouped.

The seller account must have packages enabled. Listing and retrieving packages is available to any authenticated user, while creating, updating, and deleting a package requires access to the seller account (ownership, or a curator or seller-admin delegation on it).

Bundled experiences

A package defines the experiences it bundles through selectedProducts - an ordered list where each entry references an experience and carries a sequence position that controls its display order within the package.

Demographics

The type field controls how guest demographics are handled across the bundled experiences:

  • demographics_shared: the package uses one shared set of demographics that applies to every bundled experience.
  • demographics_varies: each bundled experience keeps its own demographics.

Availability

A package can define its own schedules to control when it is available for booking, independently of the schedules of the experiences it bundles.

Media

Each package can have a primary photo and additional images. Images are uploaded as raw binary data (or as multipart/form-data) and can be resized on the server when retrieved. The primary photo cannot be deleted.

List packages

Retrieve a paginated list of packages for a seller. The seller query parameter is required.

Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string
Example: seller=507f1f77bcf86cd799439011

ID of the seller whose packages to list.

id
string
Example: id=507f1f77bcf86cd799439012

Filter packages by ID. Supports an exact match (id=<packageId>) as well as the standard comparison operators (e.g. id[in]=<id1>,<id2>).

expand
string
Enum: "selectedProducts" "experiences" "seller" "seller.name" "form"
Example: expand=selectedProducts

Comma-separated list of related objects to expand inline rather than returning ID references.

skip
integer >= 0
Default: 0

Number of items to skip

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a package

Create a new package for a seller. The request must include a seller reference, and the authenticated user must be allowed to create packages for that seller (owner, or a curator / seller-admin delegate, with the packages feature enabled).

The experiences included in the package are configured through selectedProducts.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required

Package to create

name
required
string

Package name.

excerpt
required
string

Short summary of the package.

desc
required
string

Full package description.

price
number <float> >= 0

Package price.

currency
string

ISO currency code.

priceType
string
Default: "person"
Enum: "person" "outing"

Whether the price is charged per person or per outing.

guestType
string
Default: "normal"
Enum: "normal" "passenger"

How guests are counted for this package.

type
string
Default: "demographics_shared"
Enum: "demographics_shared" "demographics_varies"

Whether demographics are shared across the bundled experiences or vary per experience.

minimumTransitDuration
integer

Suggested minimum time, in minutes, between the bundled experiences.

paymentMethod
string
Enum: "later" "cc"

Accepted payment method for the package.

cancellationPolicy
string

Cancellation policy text.

other
string

Additional information shown to travelers.

allowedCouponTypes
Array of strings
Items Enum: "discount" "unlock"

Coupon types that may be applied to this package.

object

The seller that owns the package. Required when creating a package; ignored on update (the existing seller is retained).

Array of objects (SelectedProductRequest)

Experiences included in the package, in display order.

object

Reference to an existing media item to use as the primary photo.

Responses

Request samples

Content type
application/json
{
  • "name": "Adventure Weekend Bundle",
  • "excerpt": "Two thrilling experiences for one great price.",
  • "desc": "Combine our zip-line tour and white-water rafting trip.",
  • "price": 199,
  • "currency": "USD",
  • "priceType": "person",
  • "type": "demographics_shared",
  • "seller": {
    },
  • "selectedProducts": [
    ]
}

Response samples

Content type
application/json
{
  • "object": "package",
  • "id": "507f1f77bcf86cd799439011",
  • "name": "Adventure Weekend Bundle",
  • "excerpt": "Two thrilling experiences for one great price.",
  • "desc": "Combine our zip-line tour and white-water rafting trip.",
  • "price": 199,
  • "currency": "USD",
  • "priceType": "person",
  • "type": "demographics_shared",
  • "status": "draft",
  • "seller": {
    },
  • "selectedProducts": [
    ]
}

Get a package

Retrieve a single package by its ID.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string
Enum: "selectedProducts" "experiences" "seller" "seller.name" "form"
Example: expand=selectedProducts,form

Comma-separated list of related objects to expand inline rather than returning ID references.

Responses

Response samples

Content type
application/json
{
  • "object": "package",
  • "id": "507f1f77bcf86cd799439011",
  • "name": "Adventure Weekend Bundle",
  • "excerpt": "Two thrilling experiences for one great price.",
  • "desc": "Combine our zip-line tour and white-water rafting trip.",
  • "price": 199,
  • "currency": "USD",
  • "priceType": "person",
  • "type": "demographics_shared",
  • "status": "published",
  • "seller": {
    },
  • "selectedProducts": [
    ]
}

Update a package

Update an existing package. The authenticated user must be allowed to edit the package (owner, or a curator / seller-admin delegate, with the packages feature enabled).

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Package fields to update

name
required
string

Package name.

excerpt
required
string

Short summary of the package.

desc
required
string

Full package description.

price
number <float> >= 0

Package price.

currency
string

ISO currency code.

priceType
string
Default: "person"
Enum: "person" "outing"

Whether the price is charged per person or per outing.

guestType
string
Default: "normal"
Enum: "normal" "passenger"

How guests are counted for this package.

type
string
Default: "demographics_shared"
Enum: "demographics_shared" "demographics_varies"

Whether demographics are shared across the bundled experiences or vary per experience.

minimumTransitDuration
integer

Suggested minimum time, in minutes, between the bundled experiences.

paymentMethod
string
Enum: "later" "cc"

Accepted payment method for the package.

cancellationPolicy
string

Cancellation policy text.

other
string

Additional information shown to travelers.

allowedCouponTypes
Array of strings
Items Enum: "discount" "unlock"

Coupon types that may be applied to this package.

object

The seller that owns the package. Required when creating a package; ignored on update (the existing seller is retained).

Array of objects (SelectedProductRequest)

Experiences included in the package, in display order.

object

Reference to an existing media item to use as the primary photo.

Responses

Request samples

Content type
application/json
{
  • "name": "Adventure Weekend Bundle (Updated)",
  • "excerpt": "Now with an extra activity.",
  • "desc": "Three experiences, one price.",
  • "selectedProducts": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "Adventure Weekend Bundle",
  • "excerpt": "Two thrilling experiences for one great price.",
  • "desc": "Combine our zip-line tour and white-water rafting trip.",
  • "price": 199,
  • "currency": "USD",
  • "priceType": "person",
  • "guestType": "normal",
  • "type": "demographics_shared",
  • "minimumTransitDuration": 30,
  • "paymentMethod": "later",
  • "cancellationPolicy": "string",
  • "other": "string",
  • "allowedCouponTypes": [
    ],
  • "object": "package",
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "status": "draft",
  • "selectedProducts": [
    ],
  • "photo": {
    },
  • "medias": [
    ],
  • "catalog": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    }
}

Delete a package

Soft-delete a package (sets a deletedAt timestamp and removes its seller associations). The authenticated user must be allowed to delete the package.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload package media

Upload a photo for a package. The body of the request should contain the raw image data.

Supported Formats

  • Images: JPEG, PNG, GIF

Upload Methods

XHR Upload: Send raw binary data in the request body with the Content-Type header set to the image MIME type. Use the qqfile query parameter to specify the filename.

Form Upload: Send as multipart/form-data with the file in the qqfile field.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
qqfile
string
Example: qqfile=package-image.jpg

Original file name, used to preserve the filename on the server (used by legacy upload clients).

Request Body schema:
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "success": 1,
  • "media": {
    },
  • "photo": {
    }
}

Get package media

Retrieve a package image. Filters allow the image to be resized on the server; if no filters are specified, the original image is returned. The bg size returns a large, blurred image suitable for use as a page background.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string
Example: 507f1f77bcf86cd799439041

Media ID, or default for the default image for the package.

query Parameters
size
string
Example: size=bg

Image size filter (e.g. bg for a blurred background image).

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update package media caption

Update the caption for a media item on a package.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string
Example: 507f1f77bcf86cd799439041

ID of the media item to update.

Request Body schema: application/json
required
caption
string

New caption for the media item.

Responses

Request samples

Content type
application/json
{
  • "caption": "Sunset over the canyon"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete package media

Remove a media item from a package. The package's primary photo cannot be deleted.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string
Example: 507f1f77bcf86cd799439041

ID of the media item to delete.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

purchases

A Purchase represents a booking made on a seller's account. A Purchase is associated with two related resources: PurchaseItems (the individual reservations within the booking) and LineItems (the financial entries that make up its payment summary). All pricing-related components of a booking are consolidated into line items, which makes pricing calculations on a purchase straightforward.

Payment-related line items (payments, refunds, gift coupons, vouchers, partner fees, processing fees) are added at the Purchase level, while reservation-related line items (demographics, add-ons, taxes, discounts) are added at the PurchaseItem level.

List purchases

Retrieve a paginated list of purchases. Supports filtering, searching, and various query parameters.

Supports two modes:

  • Database query mode (default): Direct database queries with full filtering support
  • Elasticsearch mode: Used when search, kiosk, or dashboard parameters are provided along with seller

For export functionality, include a format parameter to receive a job ID for asynchronous processing.

Affiliate Access: Affiliates with product-level permissions (selectedExperiences) can access purchases containing items for their assigned experiences. If an affiliate has access to all experiences for a seller, they can view all of that seller's purchases. Otherwise, only purchases with items matching their permitted experience IDs are returned.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=60f7b3c4e4b0a1234567890a

Filter purchases by seller ID

organizer
string
Example: organizer=60f7b3c4e4b0a1234567890b

Filter purchases by organizer/customer ID

status
Array of strings
Items Enum: "draft" "waitlist" "abandon" "hold" "committed"
Example: status=committed,hold

Filter by purchase status(es)

search
string
Example: search=john@example.com

Search query for customer names, emails, or purchase details

kiosk
boolean

Enable kiosk mode for simplified UI (triggers Elasticsearch)

dashboard
boolean

Enable dashboard mode (triggers Elasticsearch)

object (DateTimeFilterSchema)
Examples: createdAt[summary]=Find records where field exists (not null)&createdAt[value]=[object Object] createdAt[summary]=Find records where field is null/missing&createdAt[value]=[object Object] createdAt[summary]=Date range filtering&createdAt[value]=[object Object] createdAt[summary]=Range using comma-separated string&createdAt[value]=[object Object] createdAt[summary]=Using period for today&createdAt[value]=[object Object] createdAt[summary]=Using period for last week&createdAt[value]=[object Object] createdAt[summary]=Exact date-time match&createdAt[value]=[object Object] createdAt[summary]=After specific date&createdAt[value]=[object Object]

Filter by creation timestamp. Supports date-time filtering operations.

object (DateTimeFilterSchema)
Examples: updatedAt[summary]=Find records where field exists (not null)&updatedAt[value]=[object Object] updatedAt[summary]=Find records where field is null/missing&updatedAt[value]=[object Object] updatedAt[summary]=Date range filtering&updatedAt[value]=[object Object] updatedAt[summary]=Range using comma-separated string&updatedAt[value]=[object Object] updatedAt[summary]=Using period for today&updatedAt[value]=[object Object] updatedAt[summary]=Using period for last week&updatedAt[value]=[object Object] updatedAt[summary]=Exact date-time match&updatedAt[value]=[object Object] updatedAt[summary]=After specific date&updatedAt[value]=[object Object]

Filter by last update timestamp. Supports date-time filtering operations.

object
Example: id[gt]=60f7b3c4e4b0a1234567890a

Filter by purchase ID using MongoDB query operators

sort
string
Example: sort=createdAt,-updatedAt

Sort field(s). Multiple fields can be comma-separated. Prefix with - for descending order.

limit
integer [ 1 .. 100 ]
Example: limit=25

Number of results per page

offset
integer >= 0

Number of results to skip

expand
Array of strings
Items Enum: "items" "seller" "organizer" "travelers" "conversation" "breakdown"
Example: expand=items,seller

Additional resources to include in response:

  • items: Include purchase items
  • seller: Expand seller details
  • organizer: Expand organizer/customer details
  • travelers: Expand traveler details
  • conversation: Include conversation thread
  • breakdown: Include payment breakdown (requires authentication)
include
Array of strings

Additional fields to include in response

format
string
Enum: "csv" "xlsx"
Example: format=csv

Export format - returns job ID for async processing instead of data

string or object
Example: items_product=60f7b3c4e4b0a1234567890a

Filter purchases by product (experience) ID. Filters based on the products associated with purchase items. Supports the following operators:

  • Direct value: Exact match (items_product=<objectId>)
  • ne: Not equal (items_product[ne]=<objectId>)
  • in: Match any (items_product[in]=<id1>,<id2>)
  • nin: Exclude matches (items_product[nin]=<id1>,<id2>)
  • exists: Check existence (items_product[exists]=true)

Values must be valid 24-character hex MongoDB ObjectIds.

etl
boolean

Enable ETL mode for data extraction (admin only)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create purchase

Create a new purchase. Supports both regular purchases and partner purchases.

The system automatically detects partner purchases based on payload content. Use the dryRun parameter to validate purchase data without persisting.

The validationLevel parameter controls validation strictness:

  • error: Full validation
  • info: Basic validation only
  • warning: Skip validation
  • ignore: No validation
Authorizations:
apiKeybasicAuth
query Parameters
dryRun
boolean
Default: false

Validate purchase without persisting (returns 200 instead of 201)

validationLevel
string
Default: "ignore"
Enum: "error" "info" "warning" "ignore"

Level of validation to apply

expand
Array of strings
Items Enum: "items" "seller" "organizer" "travelers" "breakdown"
Example: expand=items,seller

Additional resources to include in response

Request Body schema: application/json
required
id
string or null

Purchase ID (null for new purchases)

status
string
Enum: "draft" "waitlist" "abandon" "hold" "committed"

Purchase status

customerName
required
string

Name of the customer

customerEmail
required
string <email>

Email address of the customer

customerLocale
string

Customer's preferred locale

customerTimezoneName
string

Customer's timezone

phone
string

Customer's phone number

currency
string

Currency code (ISO 4217)

payNow
number or null <float>

Deposit amount to pay now

referenceId
string

External booking reference

source
string

Source where purchase originated

required
object (ObjectReference)

Seller ID reference

object (ObjectReference)

Customer/organizer ID reference

required
Array of objects (PurchaseItemRequest)

Purchase items to include

Array of any (PurchaseLineItemRequest)

Top-level line items for the purchase (payment and refund line items)

object (purchases_SplitPaymentPreferenceRequest)

Split payment configuration

Array of objects (PaymentReminder)

Payment reminder configuration

releaseHoldAt
string <date-time>

When to release hold (for draft purchases)

object

Additional metadata

Responses

Request samples

Content type
application/json
Example

Creates a purchase for a day-scheduled experience with adult demographics

{
  • "lineItems": [ ],
  • "items": [
    ],
  • "seller": {
    },
  • "splitPayment": {
    },
  • "currency": "USD",
  • "status": "draft",
  • "id": null,
  • "payNow": null,
  • "customerName": "John Doe",
  • "customerEmail": "customer@example.com",
  • "phone": ""
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "committed",
  • "internalStatus": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerLocale": "en-US",
  • "customerTimezoneName": "America/New_York",
  • "phone": "+1234567890",
  • "phoneCanonical": "1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "amounts": {
    },
  • "balances": {
    },
  • "balance": 0,
  • "payNow": 50,
  • "dueNow": 50,
  • "minimumDue": 25,
  • "affiliatePayment": 15,
  • "referenceId": "EXT-BOOKING-123",
  • "source": "website",
  • "seller": {
    },
  • "organizer": {
    },
  • "partnerSeller": {
    },
  • "partner": {
    },
  • "affiliate": {
    },
  • "conversation": {
    },
  • "waitlist": {
    },
  • "travelers": [
    ],
  • "items": [
    ],
  • "lineItems": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "reminders": [
    ],
  • "paymentReminders": [
    ],
  • "splitPayment": {
    },
  • "trackingData": {
    },
  • "telemetry": {
    },
  • "meta": { },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "requiresCaptcha": false,
  • "termsAgreedAt": "2023-12-07T10:25:00Z",
  • "releaseHoldAt": "2023-12-07T12:00:00Z",
  • "notifyAt": "2023-12-07T09:00:00Z",
  • "migratedAt": "2023-12-07T08:00:00Z",
  • "commissionRefundProcessedAt": "2023-12-07T16:00:00Z"
}

Get purchase by ID

Retrieve a specific purchase by its ID.

Special handling for ticket exports: When context=tickets and format is specified, returns a job ID for asynchronous ticket generation instead of purchase data.

Response context varies based on user type:

  • Sellers see full purchase details
  • Travelers (or requests authenticated via client secret token) see customer-appropriate information

Conditional Fields:

  • minimumDue: Included in the response when the purchase is in draft status and has a traveler source.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

query Parameters
expand
Array of strings
Items Enum: "items" "seller" "organizer" "travelers" "conversation" "breakdown"
Example: expand=items,seller

Additional resources to include in response

include
Array of strings

Additional fields to include in response

context
string
Value: "tickets"

Special context for different response formats

format
string
Enum: "pdf" "csv"

Export format for tickets (requires context=tickets)

Responses

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "phone": "+1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "balance": 0,
  • "payNow": 50,
  • "seller": {
    },
  • "organizer": {
    },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "items": [
    ],
  • "lineItems": [
    ]
}

Update purchase

Update an existing purchase using partial data (PATCH semantics).

Supports two update modes:

  1. Standard PATCH with 'items' property: Update purchase properties and items directly (customerName, status, guests, etc.)

    • Use when updating purchase metadata, guest information, or item details
    • Include 'items' array with item IDs to update specific purchase items
    • Package Split: Set parentProduct: null on an item to split it out of its parent package. The Package tag is removed and Package → Split / Multi-item tags are added. Use _retainDiscount: true at the top level to keep the package discount.
    • Self-service cancellation: To cancel a purchase item as a traveler/organizer, set items[].status: canceled. If the experience cancellation policy has multiple refund methods configured (paymentMethods), also set items[].refundMethod to either cc (credit card refund) or store_credit. This field is conditionally required when multiple refund methods are available.

  2. Operations-based PATCH with 'ops' property: Use the ops array to perform specific operations

    • Use when adding/removing line items, applying discount codes, or managing ware fulfillment units
    • Line item operations: addLineItem, addLineItemWithPayment, addCode, removeLineItem
    • Ware fulfillment operations: addFulfillmentUnit, fulfillFulfillmentUnit, removeFulfillmentUnit, returnFulfillmentUnit

Line item operations:

  • addLineItem: Add a line item to a purchase or specific purchase item
  • addLineItemWithPayment: Add a line item with associated payment processing
  • addCode: Apply discount codes, coupons, or other promotional codes
  • removeLineItem: Remove existing line items (limited to specific types)

Ware fulfillment unit operations (path: /items/{itemId}/fulfillmentUnits):

  • addFulfillmentUnit: Add fulfillment units to a ware purchase item. Requires unit.id (must be a ware-type unit whose template is purchasable for the ware) and quantity.
  • fulfillFulfillmentUnit: Mark pending fulfillment units as fulfilled. Requires unit.id and quantity.
  • removeFulfillmentUnit: Remove pending (unfulfilled) fulfillment units. Requires unit.id and quantity.
  • returnFulfillmentUnit: Return or damage fulfilled units. Requires unit.id and quantity. Use _damaged: true to mark as damaged.

Important: Ware line items (type ware) cannot be created, updated, or modified via the standard lineItems property or addLineItem/removeLineItem ops. All modifications to ware quantities must be performed via the fulfillmentUnits ops path.

Path format for operations:

  • /lineItems for purchase-level operations
  • /items/{itemId}/lineItems for item-specific line item operations
  • /items/{itemId}/fulfillmentUnits for ware fulfillment unit operations

Error strategy: Set errorStrategy to continue_on_failure to process remaining operations even when one fails.

Automatically acquires a lock on the purchase during update to prevent concurrent modifications. Use dryRun parameter to validate changes without persisting them.

The validationLevel parameter controls validation strictness during updates.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

query Parameters
dryRun
boolean
Default: false

Validate update without persisting changes

validationLevel
string
Default: "ignore"
Enum: "error" "info" "warning" "ignore"

Level of validation to apply

expand
Array of strings
Items Enum: "items" "seller" "organizer" "travelers" "breakdown"

Additional resources to include in response

Request Body schema: application/json
required
customerName
string
customerEmail
string <email>
phone
string
status
string
Enum: "draft" "waitlist" "abandon" "hold" "committed"
payNow
number <float>
Array of objects

Purchase items to update

Array of objects

Line items to update

_retainDiscount
boolean
Default: false

When performing a package split operation (setting parentProduct to null on an item), set this to true to retain the existing package discount line item. By default (false), the package discount is voided when splitting.

_partialRefund
number <float>

Partial refund amount for guest change operations

_partialRefundLabel
string

Custom label for the adjustment line item created during partial refund operations. Defaults to "Change guests" if not provided. The label appears in the line item name as "{label} (partial refund)" or "{label} (no refund)".

object

Additional metadata to update

Array of any (PatchOperation) non-empty

Array of operations to perform on the purchase. Use this when adding/removing line items, applying codes, or managing fulfillment units for ware purchases.

errorStrategy
string
Default: "stop_on_failure"
Enum: "stop_on_failure" "continue_on_failure"

Controls how errors are handled when processing multiple operations:

  • stop_on_failure: Stop processing at the first failed operation (default)
  • continue_on_failure: Continue processing remaining operations even if one fails

Responses

Request samples

Content type
application/json
Example

Updates purchase items with new guest information and ticket codes

{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "committed",
  • "customerName": "John Updated Doe",
  • "customerEmail": "john.updated@example.com",
  • "phone": "+1987654321",
  • "currency": "USD",
  • "items": [ ],
  • "amount": 155,
  • "balance": 0,
  • "updatedAt": "2023-12-07T12:00:00Z"
}

Upsert draft purchase

Create or completely replace a draft purchase (PUT semantics).

This endpoint is specifically for draft purchases only. For updating other purchase statuses, use PATCH /api/purchases/{id} instead.

If the purchase doesn't exist, creates a new one. If it exists and is in draft status, replaces it entirely with the provided data.

Automatically acquires a lock during operation to prevent concurrent modifications.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

query Parameters
validationLevel
string
Default: "ignore"
Enum: "error" "info" "warning" "ignore"

Level of validation to apply

expand
Array of strings
Items Enum: "items" "seller" "organizer" "travelers" "breakdown"

Additional resources to include in response

Request Body schema: application/json
required
id
string or null

Purchase ID (null for new purchases)

status
string
Enum: "draft" "waitlist" "abandon" "hold" "committed"

Purchase status

customerName
required
string

Name of the customer

customerEmail
required
string <email>

Email address of the customer

customerLocale
string

Customer's preferred locale

customerTimezoneName
string

Customer's timezone

phone
string

Customer's phone number

currency
string

Currency code (ISO 4217)

payNow
number or null <float>

Deposit amount to pay now

referenceId
string

External booking reference

source
string

Source where purchase originated

required
object (ObjectReference)

Seller ID reference

object (ObjectReference)

Customer/organizer ID reference

required
Array of objects (PurchaseItemRequest)

Purchase items to include

Array of any (PurchaseLineItemRequest)

Top-level line items for the purchase (payment and refund line items)

object (purchases_SplitPaymentPreferenceRequest)

Split payment configuration

Array of objects (PaymentReminder)

Payment reminder configuration

releaseHoldAt
string <date-time>

When to release hold (for draft purchases)

object

Additional metadata

Responses

Request samples

Content type
application/json

Replace draft purchase with complete experience booking including multiple guests

{
  • "lineItems": [ ],
  • "items": [
    ],
  • "seller": {
    },
  • "splitPayment": {
    },
  • "paymentReminders": [ ],
  • "currency": "USD",
  • "status": "draft",
  • "id": "68b5b603da7ed5c60b0d0daa",
  • "payNow": null,
  • "customerEmail": "sachin@xola.com",
  • "customerName": "sachin",
  • "phone": ""
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "purchase",
  • "status": "draft",
  • "customerName": "Jane Smith",
  • "customerEmail": "jane.smith@example.com",
  • "currency": "USD",
  • "amount": 100,
  • "payNow": 100,
  • "items": [ ],
  • "seller": {
    },
  • "organizer": {
    },
  • "updatedAt": "2023-12-07T12:30:00Z"
}

Release/rollback purchase hold

Release or rollback a purchase that is in HOLD status.

This operation is only allowed for purchases with STATUS_HOLD. It effectively cancels the purchase and releases any inventory holds or temporary reservations.

Automatically acquires a lock during operation to prevent concurrent modifications.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Create payment or refund line item

Create a payment or refund line item on a purchase. This endpoint is used for post-booking payment collection and refund processing.

Supports two line item types based on the object field:

  • payment_line_item: Record a payment (amount should be negative, representing money collected)
  • refund_line_item: Record a refund

Use dryRun=true to preview changes without persisting them.

Use force=true to bypass balance validation checks. When force is not set or false:

  • Payment amount cannot exceed the traveler's outstanding balance
  • Cannot collect payment if there is no pending balance on the purchase

Authorization:

  • Requires CREATE_PURCHASE_LINE_ITEM permission on the purchase.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

query Parameters
dryRun
boolean
Default: false

Preview changes without persisting (returns 200 instead of 201)

force
boolean
Default: false

Bypass balance validation checks. When true:

  • Allows payment amount to exceed the traveler's outstanding balance
  • Allows collecting payment even if there is no pending balance on the purchase
Request Body schema: application/json
required
id
string

Line item ID (for updates)

object
required
string

Payment line item object type

Value: "payment_line_item"
type
required
string

Payment line item type

Value: "payment"
code
string

Coupon, gift, store credit, affiliate, or voucher code to apply as the payment. Required when payment.method is voucher (or another code-backed method); ignored otherwise.

required
object

Payment method information

status
string
Default: "pending"
Enum: "pending" "complete" "failed" "canceled"

Payment status

amount
required
number <float>

Payment amount (negative for payments made)

includeInAmount
boolean
Default: true

Whether to include this line item in the total amount

Responses

Request samples

Content type
application/json
Example
{
  • "object": "payment_line_item",
  • "type": "payment",
  • "amount": -50,
  • "payment": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "60f7b3c4e4b0a1234567890c",
  • "object": "line_item",
  • "type": "fee",
  • "name": "Service Fee",
  • "code": "SERVICE_FEE_001",
  • "price": 25,
  • "amount": 50,
  • "quantity": 2,
  • "destination": "seller",
  • "visibility": "all",
  • "visible": true,
  • "system": false,
  • "includeInAmount": true,
  • "unit": {
    },
  • "template": {
    },
  • "meta": { }
}

Update payment line item

Update an existing payment line item on a purchase. Only payment line items can be updated via this endpoint.

Use dryRun=true to preview changes without persisting them.

Authorization:

  • Requires EDIT_PURCHASE_LINE_ITEM permission on the purchase.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

lineItemId
required
string
Example: 60f7b3c4e4b0a123456789a1

Line item ID

query Parameters
dryRun
boolean
Default: false

Preview changes without persisting

Request Body schema: application/json
required
id
string

Line item ID (for updates)

object
required
string

Payment line item object type

Value: "payment_line_item"
type
required
string

Payment line item type

Value: "payment"
code
string

Coupon, gift, store credit, affiliate, or voucher code to apply as the payment. Required when payment.method is voucher (or another code-backed method); ignored otherwise.

required
object

Payment method information

status
string
Default: "pending"
Enum: "pending" "complete" "failed" "canceled"

Payment status

amount
required
number <float>

Payment amount (negative for payments made)

includeInAmount
boolean
Default: true

Whether to include this line item in the total amount

Responses

Request samples

Content type
application/json
{
  • "id": "68b81b65f672ff33c205606d",
  • "object": "payment_line_item",
  • "type": "payment",
  • "code": "DISCOUNT20",
  • "payment": {
    },
  • "status": "complete",
  • "amount": -262.71,
  • "includeInAmount": true
}

Response samples

Content type
application/json
Example
{
  • "id": "60f7b3c4e4b0a1234567890c",
  • "object": "line_item",
  • "type": "fee",
  • "name": "Service Fee",
  • "code": "SERVICE_FEE_001",
  • "price": 25,
  • "amount": 50,
  • "quantity": 2,
  • "destination": "seller",
  • "visibility": "all",
  • "visible": true,
  • "system": false,
  • "includeInAmount": true,
  • "unit": {
    },
  • "template": {
    },
  • "meta": { }
}

Delete payment or refund line item

Delete a payment or refund line item from a purchase.

Use dryRun=true to preview changes without persisting them.

Authorization:

  • Requires DELETE_PURCHASE_LINE_ITEM permission on the purchase.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

lineItemId
required
string
Example: 60f7b3c4e4b0a123456789a1

Line item ID

query Parameters
dryRun
boolean
Default: false

Preview changes without persisting

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get purchase remote cards

Retrieve remote card summaries associated with a purchase.

Remote cards are external payment methods or cards associated with the purchase, typically from third-party payment processors or gift card systems.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get dispute evidence for a purchase

Creates an asynchronous job to collect dispute evidence for a purchase.

This endpoint initiates the collection of all relevant evidence (communications, emails, waivers, etc.) for disputes associated with the purchase. The evidence is compiled into a zip file and uploaded to S3.

Returns a 202 Accepted response with the job object. Poll the job endpoint (GET /jobs/{id}) to track progress. When the job completes, the response will include the url to download the evidence zip file.

Authorization:

  • Requires VIEW_PURCHASE_DISPUTE_EVIDENCE permission on the purchase.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "type": "exportDisputeEvidence",
  • "status": "pending",
  • "progress": 0,
  • "url": null,
  • "filename": null,
  • "purchase": "60f7b3c4e4b0a1234567890a",
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedAt": "2024-01-15T10:30:00Z"
}

Pay invoice redirect

Redirects to the appropriate checkout URL for paying an invoice.

This endpoint determines whether to use v1 or x2 checkout based on the seller's configuration settings and returns a 302 redirect response to the correct checkout page.

Use Cases

  • Invoice payment links in emails
  • Balance due payment redirection
  • Customer self-service invoice payment

Redirect Behavior

The response is a 302 redirect to the checkout URL where the customer can complete the invoice payment. The specific checkout version (v1 or x2) is determined automatically based on the seller's settings.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create a purchase note

Add a note to a purchase (order).

Requires the CREATE_PURCHASE_NOTES permission on the purchase.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Purchase ID

Request Body schema: application/json
required
text
required
string

Note content

Responses

Request samples

Content type
application/json
{
  • "text": "Customer paid remaining balance in cash"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Update a purchase note

Update the text of an existing purchase note.

Requires the EDIT_PURCHASE_NOTES permission on the purchase.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Purchase ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Request Body schema: application/json
required
text
required
string

Updated note content

system
boolean

Whether the note is a system-generated note.

Responses

Request samples

Content type
application/json
{
  • "text": "Customer paid remaining balance in cash (receipt #4821)"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Delete a purchase note

Delete a purchase note.

Requires the DELETE_PURCHASE_NOTES permission on the purchase.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Purchase ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create a review for a purchase item

Submit a review for a specific item within a purchase. The seller and experience are resolved from the purchase item; when the request is made by an authenticated traveler, that traveler is recorded as the reviewer.

Rating fields (responsible, safe, unique, value, rating) are optional and are typically supplied only for traveler reviews. redirectedTo is set when smart review redirection applies.

Permission required: CREATE_PURCHASE_REVIEW

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 64f7b3c4e4b0a1234567890c

Purchase ID

itemId
required
string
Example: 64f7b3c4e4b0a1234567890a

Purchase item ID within the purchase

Request Body schema: application/json
required
name
required
string

Name of the reviewer. Required.

email
string <email>

Email of the reviewer

review
string

Free-text review comment on the experience

responsible
integer

Traveler rating for how responsible the operator was

safe
integer

Traveler rating for how safe the experience felt

unique
integer

Traveler rating for how unique the experience was

value
integer

Traveler rating for value for money

rating
number <float>

Overall rating given by the traveler

redirectedTo
string
Enum: "tripAdvisor" "yelp" "googlePlus"

External platform the traveler was redirected to when smart review is enabled

feedback
string

Additional free-text feedback on the experience

Responses

Request samples

Content type
application/json
{
  • "name": "John Doe",
  • "email": "johndoe@example.com",
  • "review": "Fantastic tour, would book again!",
  • "responsible": 5,
  • "safe": 5,
  • "unique": 4,
  • "value": 4,
  • "rating": 4.5
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "John Doe",
  • "email": "johndoe@example.com",
  • "review": "Fantastic tour, would book again!",
  • "responsible": 5,
  • "safe": 5,
  • "unique": 4,
  • "value": 4,
  • "rating": 4.5,
  • "redirectedTo": "tripAdvisor",
  • "feedback": "The guide was very knowledgeable.",
  • "experience": {
    },
  • "traveler": {
    },
  • "seller": {
    }
}

Create a review

Submit a review by referencing the purchase and experience directly. The matching purchase item is resolved from the purchase and experience, then the review is created the same way as POST /purchases/{id}/items/{itemId}/review.

Permission required: ROLE_USER

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
name
required
string

Name of the reviewer. Required.

email
string <email>

Email of the reviewer

review
string

Free-text review comment on the experience

responsible
integer

Traveler rating for how responsible the operator was

safe
integer

Traveler rating for how safe the experience felt

unique
integer

Traveler rating for how unique the experience was

value
integer

Traveler rating for value for money

rating
number <float>

Overall rating given by the traveler

redirectedTo
string
Enum: "tripAdvisor" "yelp" "googlePlus"

External platform the traveler was redirected to when smart review is enabled

feedback
string

Additional free-text feedback on the experience

required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

required
object (ObjectReference)

A reference to another object containing only its ID. Use the expand request parameter to include the full object data instead of just the reference. For example, use expand=seller to expand a seller reference into the complete seller object.

Responses

Request samples

Content type
application/json
{
  • "purchase": {
    },
  • "experience": {
    },
  • "name": "John Doe",
  • "review": "Fantastic tour, would book again!",
  • "rating": 4.5
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef123",
  • "name": "John Doe",
  • "email": "johndoe@example.com",
  • "review": "Fantastic tour, would book again!",
  • "responsible": 5,
  • "safe": 5,
  • "unique": 4,
  • "value": 4,
  • "rating": 4.5,
  • "redirectedTo": "tripAdvisor",
  • "feedback": "The guide was very knowledgeable.",
  • "experience": {
    },
  • "traveler": {
    },
  • "seller": {
    }
}

Get questions for a specific purchase item

Retrieve the questionnaire that applies to a specific item within a purchase. This is useful for purchases with multiple items that may have different questionnaires.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

itemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Upload photos for purchase item form response fields

Upload one or more photos for photo-type fields in a purchase item's form response. Photos are uploaded via multipart form data with a photos key containing an associative array where each key is the field label and the value is the photo file.

Supported image types: JPEG, PNG, GIF, WebP (max 5MB per file).

If a photo field response already exists for the given label, the photo will be replaced. Label matching is case-insensitive.

Permission: Requires EDIT_PURCHASE_FORM_RESPONSE permission.

Validation Errors:

  • missing_photos: No photos were provided in the request
  • no_form_for_product: No questionnaire is configured for this purchase item's product
  • unknown_label: The provided label does not match any photo field in the form
  • file_too_large: Photo file exceeds maximum size of 5MB
  • invalid_file_extension: Only JPEG, PNG, GIF, and WebP files are allowed
  • invalid_image_type: Only JPEG, PNG, GIF, and WebP images are allowed
  • mime_type_mismatch: File extension does not match the image type
  • upload_failed: File storage upload failed
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

purchaseItemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

Request Body schema: multipart/form-data
required
required
object

An associative array of photo files keyed by field label. Each key should match the label of a photo-type field in the form.

Responses

Request samples

Content type
multipart/form-data
Example
{
  "photos": {
    "ID Photo": "(binary file data)"
  }
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ee",
  • "name": "John Doe",
  • "fields": [
    ]
}

Get an uploaded photo for a form response field

Retrieve an uploaded photo for a specific photo-type field in a purchase item's form response. Returns the image binary with appropriate Content-Type and Content-Disposition headers.

Label matching is case-insensitive.

Permission: Requires EDIT_PURCHASE_FORM_RESPONSE permission.

Returns 404 if the purchase item, form response, or photo file is not found. Returns a validation error with reason invalid_type if the field exists but is not a photo field.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ec

The unique identifier of the purchase

purchaseItemId
required
string
Example: 507f191e810c19729de860ed

The unique identifier of the purchase item

fieldLabel
required
string
Example: ID Photo

The label of the photo field to retrieve (case-insensitive)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

purchaseItems

A PurchaseItem represents an individual reservation within a booking (a Purchase). A single Purchase can contain multiple PurchaseItems. Each PurchaseItem carries its own reservation-related line items (demographics, add-ons, taxes, discounts), so pricing can be calculated per reservation and then rolled up to the purchase total.

List purchase items

Retrieve a paginated list of purchase items. Supports filtering by various criteria and export functionality.

Supports export functionality - include a format parameter to receive a job ID for asynchronous processing.

Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string
Example: seller=60f7b3c4e4b0a1234567890a

Filter purchase items by seller ID (required for exports)

product
string
Example: product=64f7b3c4e4b0a1234567890b

Filter purchase items by product ID

arrivalDate
string <date>
Example: arrivalDate=2024-07-01

Filter purchase items by arrival date (YYYY-MM-DD)

event
string
Example: event=64f7b3c4e4b0a1234567890c

Filter purchase items by event ID

format
string
Enum: "csv" "xlsx"
Example: format=csv

Export format - when provided, returns a job ID for async processing

limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=20

Maximum number of items to return per page

offset
integer >= 0
Default: 0

Number of items to skip for pagination

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Get purchase item by ID

Retrieve a specific purchase item by its ID. Supports expanding related objects.

Access control:

  • Sellers can view purchase items for their products
  • Travelers can view their own purchase items
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 64f7b3c4e4b0a1234567890a

Purchase item ID

query Parameters
expand
Array of strings
Items Enum: "purchase" "product" "traveler" "schedule"
Example: expand=purchase,product

Comma-separated list of related objects to expand

Responses

Response samples

Content type
application/json
{
  • "id": "64f7b3c4e4b0a1234567890a",
  • "object": "experience_purchase_item",
  • "status": "confirmed",
  • "amount": 150,
  • "currency": "USD",
  • "quantity": 2,
  • "product": {
    },
  • "purchase": {
    },
  • "lineItems": [
    ],
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedAt": "2024-01-15T10:30:00Z"
}

Create line item for purchase item

Add a line item (e.g., discount, fee, adjustment) to a specific purchase item within a purchase.

Common line item types:

  • adjustment: Manual price adjustment
  • discount: Discount application
  • fee: Additional fee
  • tax: Tax calculation

Important: Line items of type ware are not supported via this endpoint. Ware quantities are managed exclusively through the PATCH /purchases/{id} endpoint using the ops fulfillmentUnits path with operations such as addFulfillmentUnit and removeFulfillmentUnit.

Use dryRun=true to preview changes without persisting them.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 64f7b3c4e4b0a1234567890c

Purchase ID

itemId
required
string
Example: 64f7b3c4e4b0a1234567890a

Purchase item ID within the purchase

query Parameters
dryRun
boolean
Default: false

Preview changes without persisting (returns 200 instead of 201)

Request Body schema: application/json
required
object
required
string

Standard line item object type

Value: "line_item"
type
required
string
Enum: "tax" "fee" "discount" "demographic" "merchandise" "equipment" "service" "gift" "pickup" "membership" "adjustment" "feeable_taxable_adjustment"

Type of line item

required
object

Line item template reference

quantity
integer or null

Quantity (null for non-unit-based items like fees/taxes)

price
number or null <float>

Price per unit (null for fixed amount items), use this only for taxed_adjustment and adjustment type lineItems

amount
required
number <float>

Total amount for this line item, use this only for gift type lineItems

includeInAmount
boolean
Default: true

Whether to include this line item in the total amount, use this only for tax and fee type lineItems

code
string

Line item code

destination
string
Enum: "seller" "xola" "affiliate" "xola_partner"

Where the line item amount is allocated

Responses

Request samples

Content type
application/json
Example
{
  • "object": "line_item",
  • "type": "fee",
  • "amount": 30,
  • "quantity": 1,
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "id": "64f7b3c4e4b0a1234567890e",
  • "object": "line_item",
  • "type": "fee",
  • "amount": 30,
  • "name": "Additional Fee",
  • "quantity": 1
}

Delete/void line item from purchase item

Remove or void a specific line item from a purchase item. This creates a voiding line item rather than physically deleting the record for audit trail purposes.

Use dryRun=true to preview changes without persisting them.

Note: Line items that are already voided cannot be voided again.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 64f7b3c4e4b0a1234567890c

Purchase ID

itemId
required
string
Example: 64f7b3c4e4b0a1234567890a

Purchase item ID within the purchase

lineItemId
required
string
Example: 64f7b3c4e4b0a1234567890e

Line item ID to delete/void

query Parameters
dryRun
boolean
Default: false

Preview changes without persisting

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Pay gratuity redirect

Redirects to the appropriate checkout URL for paying a gratuity on a purchase item.

This endpoint determines whether to use v1 or x2 checkout based on the seller's configuration settings and returns a 302 redirect response to the correct checkout page where the customer can complete the gratuity payment.

Use Cases

  • Gratuity payment links in reminder emails
  • Post-event tip collection
  • Customer self-service gratuity payment
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Purchase ID

itemId
required
string
Example: 60f7b3c4e4b0a1234567890b

Purchase item ID within the purchase

query Parameters
algorithm
string
Example: algorithm=percent

Gratuity calculation algorithm (e.g., "percent", "fixed")

amount
string
Example: amount=18

Gratuity amount (interpretation depends on algorithm)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

purchaseRules

Purchase rules are the driving mechanism for performing all pricing-based calculations on a purchase. A purchase rule is, simply put, a bundling of a filter and a set of actions. If the filter conditions pass for the resource the rule is acting on, the rule performs its list of actions on that same resource. The only actions a purchase rule can perform are to insert, update, or remove line items.

Most rules a seller defines operate on a PurchaseItem (experience pricing, taxes, discounts). A few Xola-defined rules operate at the Purchase level (partner fees, processing fees). These are represented by two kinds of rule: one operates on a purchase, and one operates on an item — otherwise they look exactly the same.

  • Filter: Defines the conditions that must match for a purchase rule to operate on a purchase or purchase item. An absence of a filter means the rule always evaluates to true and always performs its actions. A single rule filter specifies one condition (a field and an expected operand); a multiple rule filter combines several conditions with the logical operators AND and OR.
  • Actions: An action's scope is limited to the lineItems field — it can only add or modify line items, and within a line item it can only modify one of price, quantity, amount, or multiplier. The main action types are insert, update, upsert, and copy. Each action uses a modifier (which field to change, how, and by what value) and an aggregator (which computes that value from the purchase) to determine the change.

List purchase rules

Retrieve a paginated list of purchase rules

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

active
boolean

Filter by active status

required
boolean

Filter by required status

system
boolean

Filter by system status

object
string
Enum: "purchase_rule" "purchase_item_rule"

Filter by rule type

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new purchase rule

Create a new purchase rule with filters and actions

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
One of
name
required
string

Name of the purchase rule

required
object (ObjectReference)

Seller this rule belongs to

system
boolean

Whether this is a system purchase rule

required
boolean

If set to true, this rule has to pass for the purchase to be created

sequence
integer

The sequence in which this rule should apply

processActionsForIgnoredValidations
boolean

Indicates if the action can still be processed if this rule validation fails

shouldCheckFieldValueForIgnoredValidations
boolean

Indicates if a more granular error compare should be performed for ignored errors

Array of objects

Tags associated with this rule

object

Additional metadata for the rule

object
required
string

Must be purchase_item_rule for demographic pricing

Value: "purchase_item_rule"
required
Array of objects (DemographicPricingAction)

List of demographic pricing actions for different templates

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "seller": {
    },
  • "system": true,
  • "required": true,
  • "sequence": 0,
  • "processActionsForIgnoredValidations": true,
  • "shouldCheckFieldValueForIgnoredValidations": true,
  • "tags": [
    ],
  • "meta": { },
  • "object": "purchase_item_rule",
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "seller": {
    },
  • "system": true,
  • "required": true,
  • "sequence": 0,
  • "processActionsForIgnoredValidations": true,
  • "shouldCheckFieldValueForIgnoredValidations": true,
  • "tags": [
    ],
  • "meta": { },
  • "id": "string",
  • "object": "purchase_rule",
  • "createdBy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    },
  • "filter": {
    },
  • "actions": [
    ]
}

Get purchase rule by ID

Retrieve a specific purchase rule by its ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "seller": {
    },
  • "system": true,
  • "required": true,
  • "sequence": 0,
  • "processActionsForIgnoredValidations": true,
  • "shouldCheckFieldValueForIgnoredValidations": true,
  • "tags": [
    ],
  • "meta": { },
  • "id": "string",
  • "object": "purchase_rule",
  • "createdBy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    },
  • "filter": {
    },
  • "actions": [
    ]
}

Update purchase rule

Update an existing purchase rule

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
One of
name
required
string

Name of the purchase rule

required
object (ObjectReference)

Seller this rule belongs to

system
boolean

Whether this is a system purchase rule

required
boolean

If set to true, this rule has to pass for the purchase to be created

sequence
integer

The sequence in which this rule should apply

processActionsForIgnoredValidations
boolean

Indicates if the action can still be processed if this rule validation fails

shouldCheckFieldValueForIgnoredValidations
boolean

Indicates if a more granular error compare should be performed for ignored errors

Array of objects

Tags associated with this rule

object

Additional metadata for the rule

object
required
string

Must be purchase_item_rule for demographic pricing

Value: "purchase_item_rule"
required
Array of objects (DemographicPricingAction)

List of demographic pricing actions for different templates

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "seller": {
    },
  • "system": true,
  • "required": true,
  • "sequence": 0,
  • "processActionsForIgnoredValidations": true,
  • "shouldCheckFieldValueForIgnoredValidations": true,
  • "tags": [
    ],
  • "meta": { },
  • "object": "purchase_item_rule",
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "seller": {
    },
  • "system": true,
  • "required": true,
  • "sequence": 0,
  • "processActionsForIgnoredValidations": true,
  • "shouldCheckFieldValueForIgnoredValidations": true,
  • "tags": [
    ],
  • "meta": { },
  • "id": "string",
  • "object": "purchase_rule",
  • "createdBy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedBy": {
    },
  • "filter": {
    },
  • "actions": [
    ]
}

Delete purchase rule

Delete a purchase rule by marking it as deleted

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

resources

Equipment and guide resource management

List resources

Retrieve a paginated list of resources.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

event
string

Get resources for a specific event ID with availability information

product
string

Get resources for a specific product/experience ID with availability information

start
string <date-time>
Example: start=2024-01-15T09:00:00

Start time for product resource availability (valid only when 'product' is specified)

seller
string

Filter resources by seller ID (required if neither event nor product are specified)

name
string
Example: name=kayak

Filter resources by name (partial match)

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a new resource

Create a new resource (equipment or guide). The resource will be automatically associated with the authenticated user's seller account unless a different seller is specified.

For equipment resources with custom allocation strategy, the resource will be automatically added to the prioritized resource list.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
type
required
string
Enum: "equipment" "guide"

Type of resource to create

name
required
string

Name of the resource

seller
string

Seller ID (will default to authenticated user if not provided)

capacity
integer >= 1

Capacity per unit (equipment only)

count
integer >= 1

Number of units available (equipment only)

Responses

Request samples

Content type
application/json
Example
{
  • "type": "equipment",
  • "name": "Double Kayak",
  • "capacity": 2,
  • "count": 3
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "type": "equipment",
  • "name": "Double Kayak",
  • "seller": {
    },
  • "capacity": 2,
  • "count": 3,
  • "schedules": [ ],
  • "createdAt": "2024-01-15T10:30:00Z"
}

Get resource by ID

Retrieve detailed information about a specific resource

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "type": "equipment",
  • "name": "Raft",
  • "seller": {
    },
  • "capacity": 10,
  • "count": 5,
  • "schedules": [ ],
  • "createdAt": "2024-01-01T10:00:00Z"
}

Update a resource

Update an existing resource. Only provided fields will be updated. This endpoint triggers resource update events for equipment resources.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
string

Updated name of the resource

capacity
integer >= 1

Updated capacity per unit (equipment only)

count
integer >= 1

Updated number of units available (equipment only)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Premium Kayak"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "type": "equipment",
  • "name": "Premium Kayak",
  • "seller": {
    },
  • "capacity": 3,
  • "count": 2,
  • "schedules": [ ],
  • "createdAt": "2024-01-01T10:00:00Z"
}

Delete a resource

Soft delete a resource by setting the deletedAt timestamp. Resources that are associated with experiences cannot be deleted and will return a conflict error.

For equipment resources with custom allocation strategy, the resource will be automatically removed from the prioritized resource list.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Assign resource to experience

Assigns a pre-existing resource (inventory item) to an experience. Resources are fixed assets that can be utilized across multiple experiences. You must have the Inventory feature enabled for this endpoint to work.

Resource Concepts:

  • Capacity: How many people, seats, or units are in each piece of equipment
  • Count: How many units of equipment you have

Restrictions:

  • Resources can only be assigned to scheduled experiences
  • If multiple equipment feature is not enabled, only one equipment resource is allowed per experience
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the experience

Request Body schema: application/json
required
required
object (ObjectReference)

Reference to the resource to assign

Responses

Request samples

Content type
application/json
{
  • "resource": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "resource": {
    },
  • "priority": 100
}

Unassign resource from experience

Remove the assignment of a resource (inventory item) from an experience. This will also remove the resource from all existing events for this experience.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the experience

resourceId
required
string
Example: 507f1f77bcf86cd799439011

The unique identifier of the resource to unassign

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

schedules

Schedule management for experiences, guides, and resources

Create experience schedule

Create schedules for an Experience. This allows you to build activity schedules that define when your trip departs. Combining schedules also allows for dynamic pricing that adjusts based on time or day. You can create as many schedules as you would like.

Sample Request:

// Every weekday 8AM, 12PM, 6PM
{
  "name": "Weekdays",
  "repeat": "weekly", 
  "days": [1,2,3,4,5],
  "departure": "fixed",
  "times": [800, 1200, 1800],
  "type": "available",
  "priceDelta": 0
}
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Schedule configuration data

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string
Default: "available"
Enum: "available" "blackout"

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

departure
string
Enum: "fixed" "varies" "openingHours"

Whether departure time is fixed, varies, or driven by opening-hours windows.

  • fixed: Departure at specific times listed in times
  • varies: Departure time varies (no fixed times)
  • openingHours: Departure windows are defined by openingHoursPerDay entries
times
Array of integers[ items [ 0 .. 2359 ] ]

Start times in HHMM format (e.g., 900 = 9:00 AM, 1800 = 6:00 PM)

priceDelta
number <float>
Default: 0

Price adjustment for this schedule

priceOverride
boolean

Whether this schedule overrides base pricing

allowedPrivacies
Array of strings
Items Enum: "private" "public"

Allowed privacy levels

Array of objects (OpeningHoursPerDay)

Per-weekday opening hour windows. Required when departure is openingHours. Each entry defines the open/close time window for a specific day of the week. Duplicate entries for the same day are ignored (first occurrence wins).

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Weekday Tours",
  • "repeat": "weekly",
  • "days": [
    ],
  • "departure": "fixed",
  • "times": [
    ],
  • "type": "available",
  • "priceDelta": 0
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439014",
  • "name": "Weekday Tours",
  • "repeat": "weekly",
  • "days": [
    ],
  • "departure": "fixed",
  • "times": [
    ],
  • "type": "available",
  • "priceDelta": 0,
  • "priceOverride": false,
  • "allowedPrivacies": [
    ],
  • "start": "2024-01-01",
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedAt": "2024-01-15T10:30:00Z"
}

Update experience schedule

Update an existing schedule for an experience. All schedule properties can be modified.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439014

Schedule ID to update

Request Body schema: application/json
required

Updated schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string
Default: "available"
Enum: "available" "blackout"

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

departure
string
Enum: "fixed" "varies" "openingHours"

Whether departure time is fixed, varies, or driven by opening-hours windows.

  • fixed: Departure at specific times listed in times
  • varies: Departure time varies (no fixed times)
  • openingHours: Departure windows are defined by openingHoursPerDay entries
times
Array of integers[ items [ 0 .. 2359 ] ]

Start times in HHMM format (e.g., 900 = 9:00 AM, 1800 = 6:00 PM)

priceDelta
number <float>
Default: 0

Price adjustment for this schedule

priceOverride
boolean

Whether this schedule overrides base pricing

allowedPrivacies
Array of strings
Items Enum: "private" "public"

Allowed privacy levels

Array of objects (OpeningHoursPerDay)

Per-weekday opening hour windows. Required when departure is openingHours. Each entry defines the open/close time window for a specific day of the week. Duplicate entries for the same day are ignored (first occurrence wins).

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Weekday Tours",
  • "repeat": "weekly",
  • "days": [
    ],
  • "departure": "fixed",
  • "times": [
    ],
  • "type": "available",
  • "priceDelta": 5
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z",
  • "departure": "fixed",
  • "times": [
    ],
  • "priceDelta": 0,
  • "priceOverride": false,
  • "allowedPrivacies": [
    ],
  • "timeRanges": [
    ],
  • "openingHoursPerDay": [
    ]
}

Delete experience schedule

Delete a schedule from an experience. This will remove all future occurrences of the schedule.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439014

Schedule ID to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create experience opening hours

Add a new opening-hours schedule to an experience. Opening-hours schedules define the days and time windows during which an experience is open for walk-in or pre_opening_end cutoff enforcement.

Permission required: EDIT_EXPERIENCE_OPENING_SCHEDULES

Validation rules:

  • The new schedule's date range must not overlap with any existing opening-hours schedule on the same experience.
  • Each openingHoursPerDay entry must have an endTime greater than its startTime.
  • Duplicate entries for the same weekday are ignored (first occurrence wins).

Sample Request:

{
  "name": "Summer Hours",
  "repeat": "weekly",
  "departure": "openingHours",
  "start": "2024-06-01",
  "end": "2024-08-31",
  "openingHoursPerDay": [
    {"day": 1, "timeRange": {"startTime": 900, "endTime": 1700}},
    {"day": 2, "timeRange": {"startTime": 900, "endTime": 1700}},
    {"day": 3, "timeRange": {"startTime": 900, "endTime": 1700}},
    {"day": 4, "timeRange": {"startTime": 900, "endTime": 1700}},
    {"day": 5, "timeRange": {"startTime": 900, "endTime": 1700}}
  ]
}
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required

Opening-hours schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
required
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

departure
string
Value: "openingHours"

Always set to openingHours by the server for opening-hours schedules

required
Array of objects (OpeningHoursPerDay) non-empty

Per-weekday time windows for this schedule. At least one entry is required. Duplicate entries for the same day are ignored (first occurrence wins).

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Weekday Hours",
  • "type": "available",
  • "repeat": "weekly",
  • "departure": "openingHours",
  • "start": "2024-06-01",
  • "openingHoursPerDay": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439030",
  • "name": "Weekday Hours",
  • "type": "available",
  • "repeat": "weekly",
  • "departure": "openingHours",
  • "openingHoursPerDay": [
    ],
  • "createdAt": "2024-01-15T10:30:00Z",
  • "updatedAt": "2024-01-15T10:30:00Z"
}

Update experience opening hours

Update an existing opening-hours schedule on an experience.

Permission required: EDIT_EXPERIENCE_OPENING_SCHEDULES

Validation rules:

  • The updated schedule's date range must not overlap with any other opening-hours schedule on the same experience.
  • Each openingHoursPerDay entry must have an endTime greater than its startTime.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

openingHourId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439030

Opening-hours schedule ID to update

Request Body schema: application/json
required

Updated opening-hours schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
required
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

departure
string
Value: "openingHours"

Always set to openingHours by the server for opening-hours schedules

required
Array of objects (OpeningHoursPerDay) non-empty

Per-weekday time windows for this schedule. At least one entry is required. Duplicate entries for the same day are ignored (first occurrence wins).

Responses

Request samples

Content type
application/json
{
  • "name": "Extended Weekday Hours",
  • "type": "available",
  • "repeat": "weekly",
  • "departure": "openingHours",
  • "start": "2024-06-01",
  • "openingHoursPerDay": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z",
  • "departure": "fixed",
  • "times": [
    ],
  • "priceDelta": 0,
  • "priceOverride": false,
  • "allowedPrivacies": [
    ],
  • "timeRanges": [
    ],
  • "openingHoursPerDay": [
    ]
}

Delete experience opening hours

Remove an opening-hours schedule from an experience.

Permission required: EDIT_EXPERIENCE_OPENING_SCHEDULES

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

openingHourId
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439030

Opening-hours schedule ID to delete

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create guide schedule

Add a new availability schedule to a guide. Guide schedules define when guides are available for assignments.

Required fields: type, days, start

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

guideId
required
string
Example: 507f1f77bcf86cd799439012

Guide ID

Request Body schema: application/json
required

Guide schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

Array of objects (baseSchedule_TimeRange)

Time ranges when the guide is available

Responses

Request samples

Content type
application/json
Example
{
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "start": "2024-01-01",
  • "timeRanges": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z"
}

Update guide schedule

Update an existing schedule for a guide.

Required fields: type, days

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

guideId
required
string
Example: 507f1f77bcf86cd799439012

Guide ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439015

Schedule ID to update

Request Body schema: application/json
required

Updated guide schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

Array of objects (baseSchedule_TimeRange)

Updated time ranges when the guide is available

Responses

Request samples

Content type
application/json
{
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "timeRanges": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z"
}

Delete guide schedule

Delete a schedule from a guide. Use the force query parameter to force deletion even if there are conflicts.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

guideId
required
string
Example: 507f1f77bcf86cd799439012

Guide ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439015

Schedule ID to delete

query Parameters
force
boolean
Default: false
Example: force=true

Force deletion even if there are conflicts

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create resource schedule

Add a new schedule to a resource. Resource schedules define when equipment or resources are available for use. Use the force query parameter to force creation even if there are conflicts.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
force
boolean
Default: false

Force creation even if there are conflicts

Request Body schema: application/json
required

Resource schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Summer Kayak Availability",
  • "type": "available",
  • "repeat": "weekly",
  • "start": "2024-06-01",
  • "end": "2024-08-31"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z"
}

Update resource schedule

Update an existing schedule for a resource. Use the force query parameter to force update even if there are conflicts.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439016

Schedule ID to update

query Parameters
force
boolean
Default: false

Force update even if there are conflicts

Request Body schema: application/json
required

Updated resource schedule configuration

id
string

Schedule identifier (for updates)

name
string

Name for this schedule

type
required
string

Type of schedule

repeat
string
Enum: "weekly" "custom"

How the schedule repeats

days
Array of integers[ items [ 0 .. 6 ] ]

Days of week (0=Sunday, 1=Monday, etc.) for weekly repeats

dates
Array of strings <date> [ items <date > ]

Specific dates when this schedule applies

start
string <date>

Start date for recurring schedules

end
string <date>

End date for recurring schedules

source
string

Source of the schedule

Responses

Request samples

Content type
application/json
{
  • "name": "Extended Summer Availability",
  • "type": "available",
  • "repeat": "weekly",
  • "start": "2024-05-01",
  • "end": "2024-09-30"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439012",
  • "name": "Morning Tours",
  • "type": "available",
  • "repeat": "weekly",
  • "days": [
    ],
  • "dates": [
    ],
  • "start": "2023-08-01",
  • "end": "2023-12-31",
  • "source": "manual",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "expiresAt": "2024-01-01T00:00:00Z"
}

Delete resource schedule

Delete a schedule from a resource. Use the force query parameter to force deletion even if there are conflicts.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

scheduleId
required
string
Example: 507f1f77bcf86cd799439016

Schedule ID to delete

query Parameters
force
boolean
Default: false

Force deletion even if there are conflicts

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

sellers

Seller account management

Create a new seller account

Creates a new seller account. For internal use or admin creation. Public requests require reCAPTCHA validation. Admin-created accounts require a password.

Authorizations:
apiKeybasicAuth
header Parameters
X-RECAPTCHA-RESPONSE
string

reCAPTCHA response token (required for public requests)

Request Body schema: application/json
required
bankAccount
string^[a-zA-Z0-9]+$

Bank account number for payouts

bankAccountType
string
Enum: "checking" "savings"

Type of bank account

bankRouting
string

Bank routing number for payouts

businessType
string
Enum: "business" "individual"

Type of business entity

city
string

City

company
string

Legal company name

communicationEmail
string <email>

Email address for customer communications

country
string

Country name

countryCode
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code

currency
string^[A-Z]{3}$

ISO 4217 currency code

email
string <email>

Primary email address

emailFooter
string

Custom footer text for outgoing emails

object (Location)

Geographic location with coordinates and optional address

geoNameId
integer

GeoNames database ID for location

name
string

Company or business name

personName
string

Name of the person who created the account (populated during self-registration)

phone
string

Contact phone number

registrationPath
string
Enum: "xola_admin" "self_registration"

How the seller account was created

state
string

State or province

statementDescriptor
string <= 22 characters ^[^><'"]*$

Text that appears on customer credit card statements

streetAddress
string

Street address

timezone
number <float>
Deprecated

Timezone offset as a float

timezoneName
string

Timezone identifier

website
string <uri>

Company website URL

zip
string <= 10 characters

ZIP or postal code

taxId
string

EIN (business) or SSN (individual) of the bank account holder (only last 4 digits are stored)

password
string >= 6 characters

Password for new seller account (required for admin-created accounts)

createStripeAccount
boolean
Default: true

Whether to create a Stripe managed account

Responses

Request samples

Content type
application/json
Example
{
  • "email": "newbusiness@example.com",
  • "name": "Mystic Mountain Tours",
  • "company": "Mystic Mountain Tours",
  • "businessType": "business",
  • "phone": "+1-555-123-4567",
  • "country": "United States",
  • "countryCode": "US"
}

Response samples

Content type
application/json
{
  • "bankAccount": "1234567890",
  • "bankAccountType": "checking",
  • "bankRouting": "123456789",
  • "businessType": "business",
  • "city": "Boulder",
  • "company": "Mystic Mountain Tours LLC",
  • "communicationEmail": "bookings@mystic-mountain-tours.com",
  • "country": "United States",
  • "countryCode": "US",
  • "currency": "USD",
  • "email": "info@mystic-mountain-tours.com",
  • "emailFooter": "Thank you for choosing Mystic Mountain Tours!",
  • "geo": {
    },
  • "geoNameId": 5294810,
  • "name": "Mystic Mountain Tours",
  • "personName": "John Smith",
  • "phone": "+1-555-123-4567",
  • "registrationPath": "self_registration",
  • "state": "Colorado",
  • "statementDescriptor": "MYSTIC MOUNTAIN TOURS",
  • "streetAddress": "456 Mountain View Road",
  • "timezone": -7,
  • "timezoneName": "America/Denver",
  • "website": "https://mystic-mountain-tours.com",
  • "zip": "80301",
  • "id": "507f1f77bcf86cd799439011",
  • "version": 2,
  • "enabled": true,
  • "balance": 1250.5,
  • "disputedBalance": 0,
  • "unrecoveredBalance": 0,
  • "locale": "en_US",
  • "picture": {
    },
  • "medias": [
    ],
  • "acceptedCards": [
    ],
  • "allowedGateways": [
    ],
  • "defaultGateway": "stripe",
  • "fees": [
    ],
  • "pluginFees": {
    },
  • "processingFeeFormulas": [
    ],
  • "partnerFeeFormulas": [
    ],
  • "paymentMethods": [
    ],
  • "remoteCards": [
    ],
  • "remoteGateways": [
    ],
  • "plans": [
    ],
  • "subscriptionPlan": {
    },
  • "stripeAccount": {
    },
  • "topUpSource": {
    },
  • "autoAccept": {
    },
  • "blackoutSchedules": [
    ],
  • "terms": {
    },
  • "preferences": {
    },
  • "roles": [
    ],
  • "delegates": [
    ],
  • "meta": {
    },
  • "customerNotes": {
    },
  • "bankAccountLast4": "7890",
  • "bankRoutingLast4": "6789",
  • "taxIdLast4": "1234",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Search and list sellers

Searches and retrieves a list of sellers based on various filters. Supports different contexts like agent view, Google Reserve, and partner search.

Results are paginated and can be filtered by various criteria.

Authorizations:
apiKeybasicAuth
query Parameters
agent
boolean
Default: false

Return sellers for agent context

filter
string
Value: "googleReserve"
Example: filter=googleReserve

Special filter type

context
string
Default: "public"
Enum: "public" "admin" "xolaPartner"
Example: context=admin

Response context for data formatting

seller
string
Example: seller=507f1f77bcf86cd799439011

Seller ID for context-based filtering

etl
boolean
Default: false

ETL mode for higher limits (admin only)

limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=50

Number of results per page

offset
integer >= 0
Default: 0

Number of results to skip

q
string
Example: q=mystic mountain tours

Search query for seller names

country
string
Example: country=United States

Filter by country

enabled
boolean
Example: enabled=true

Filter by enabled status

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": "/api/sellers?offset=50&limit=50",
  • "_es": true
}

Update seller information

Updates an existing seller's information. Supports both full replacement (PUT) and partial updates (PATCH semantics). Some fields like email changes may require multi-factor authentication.

Version migration from V1 to V2 requires special permissions.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
bankAccount
string^[a-zA-Z0-9]+$

Bank account number for payouts

bankAccountType
string
Enum: "checking" "savings"

Type of bank account

bankRouting
string

Bank routing number for payouts

businessType
string
Enum: "business" "individual"

Type of business entity

city
string

City

company
string

Legal company name

communicationEmail
string <email>

Email address for customer communications

country
string

Country name

countryCode
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code

currency
string^[A-Z]{3}$

ISO 4217 currency code

email
string <email>

Primary email address

emailFooter
string

Custom footer text for outgoing emails

object (Location)

Geographic location with coordinates and optional address

geoNameId
integer

GeoNames database ID for location

name
string

Company or business name

personName
string

Name of the person who created the account (populated during self-registration)

phone
string

Contact phone number

registrationPath
string
Enum: "xola_admin" "self_registration"

How the seller account was created

state
string

State or province

statementDescriptor
string <= 22 characters ^[^><'"]*$

Text that appears on customer credit card statements

streetAddress
string

Street address

timezone
number <float>
Deprecated

Timezone offset as a float

timezoneName
string

Timezone identifier

website
string <uri>

Company website URL

zip
string <= 10 characters

ZIP or postal code

taxId
string

EIN (business) or SSN (individual) of the bank account holder (only last 4 digits are stored)

password
string >= 6 characters

Password for new seller account (required for admin-created accounts)

createStripeAccount
boolean
Default: true

Whether to create a Stripe managed account

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "bankAccount": "1234567890",
  • "bankAccountType": "checking",
  • "bankRouting": "123456789",
  • "businessType": "business",
  • "city": "Boulder",
  • "company": "Mystic Mountain Tours LLC",
  • "communicationEmail": "bookings@mystic-mountain-tours.com",
  • "country": "United States",
  • "countryCode": "US",
  • "currency": "USD",
  • "email": "info@mystic-mountain-tours.com",
  • "emailFooter": "Thank you for choosing Mystic Mountain Tours!",
  • "geo": {
    },
  • "geoNameId": 5294810,
  • "name": "Mystic Mountain Tours",
  • "personName": "John Smith",
  • "phone": "+1-555-123-4567",
  • "registrationPath": "self_registration",
  • "state": "Colorado",
  • "statementDescriptor": "MYSTIC MOUNTAIN TOURS",
  • "streetAddress": "456 Mountain View Road",
  • "timezone": -7,
  • "timezoneName": "America/Denver",
  • "website": "https://mystic-mountain-tours.com",
  • "zip": "80301",
  • "id": "507f1f77bcf86cd799439011",
  • "version": 2,
  • "enabled": true,
  • "balance": 1250.5,
  • "disputedBalance": 0,
  • "unrecoveredBalance": 0,
  • "locale": "en_US",
  • "picture": {
    },
  • "medias": [
    ],
  • "acceptedCards": [
    ],
  • "allowedGateways": [
    ],
  • "defaultGateway": "stripe",
  • "fees": [
    ],
  • "pluginFees": {
    },
  • "processingFeeFormulas": [
    ],
  • "partnerFeeFormulas": [
    ],
  • "paymentMethods": [
    ],
  • "remoteCards": [
    ],
  • "remoteGateways": [
    ],
  • "plans": [
    ],
  • "subscriptionPlan": {
    },
  • "stripeAccount": {
    },
  • "topUpSource": {
    },
  • "autoAccept": {
    },
  • "blackoutSchedules": [
    ],
  • "terms": {
    },
  • "preferences": {
    },
  • "roles": [
    ],
  • "delegates": [
    ],
  • "meta": {
    },
  • "customerNotes": {
    },
  • "bankAccountLast4": "7890",
  • "bankRoutingLast4": "6789",
  • "taxIdLast4": "1234",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Partially update seller information

Partially updates a seller's information. Only provided fields are updated, other fields remain unchanged. Alias for PUT with same behavior.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
bankAccount
string^[a-zA-Z0-9]+$

Bank account number for payouts

bankAccountType
string
Enum: "checking" "savings"

Type of bank account

bankRouting
string

Bank routing number for payouts

businessType
string
Enum: "business" "individual"

Type of business entity

city
string

City

company
string

Legal company name

communicationEmail
string <email>

Email address for customer communications

country
string

Country name

countryCode
string^[A-Z]{2}$

ISO 3166-1 alpha-2 country code

currency
string^[A-Z]{3}$

ISO 4217 currency code

email
string <email>

Primary email address

emailFooter
string

Custom footer text for outgoing emails

object (Location)

Geographic location with coordinates and optional address

geoNameId
integer

GeoNames database ID for location

name
string

Company or business name

personName
string

Name of the person who created the account (populated during self-registration)

phone
string

Contact phone number

registrationPath
string
Enum: "xola_admin" "self_registration"

How the seller account was created

state
string

State or province

statementDescriptor
string <= 22 characters ^[^><'"]*$

Text that appears on customer credit card statements

streetAddress
string

Street address

timezone
number <float>
Deprecated

Timezone offset as a float

timezoneName
string

Timezone identifier

website
string <uri>

Company website URL

zip
string <= 10 characters

ZIP or postal code

taxId
string

EIN (business) or SSN (individual) of the bank account holder (only last 4 digits are stored)

password
string >= 6 characters

Password for new seller account (required for admin-created accounts)

createStripeAccount
boolean
Default: true

Whether to create a Stripe managed account

Responses

Request samples

Content type
application/json
{
  • "bankAccount": "1234567890",
  • "bankAccountType": "checking",
  • "bankRouting": "123456789",
  • "businessType": "business",
  • "city": "Boulder",
  • "company": "Mystic Mountain Tours LLC",
  • "communicationEmail": "bookings@mystic-mountain-tours.com",
  • "country": "United States",
  • "countryCode": "US",
  • "currency": "USD",
  • "email": "info@mystic-mountain-tours.com",
  • "emailFooter": "Thank you for choosing Mystic Mountain Tours!",
  • "geo": {
    },
  • "geoNameId": 5294810,
  • "name": "Mystic Mountain Tours",
  • "personName": "John Smith",
  • "phone": "+1-555-123-4567",
  • "registrationPath": "self_registration",
  • "state": "Colorado",
  • "statementDescriptor": "MYSTIC MOUNTAIN TOURS",
  • "streetAddress": "456 Mountain View Road",
  • "timezone": -7,
  • "timezoneName": "America/Denver",
  • "website": "https://mystic-mountain-tours.com",
  • "zip": "80301",
  • "taxId": "12-3456789",
  • "password": "securePassword123",
  • "createStripeAccount": true
}

Response samples

Content type
application/json
{
  • "bankAccount": "1234567890",
  • "bankAccountType": "checking",
  • "bankRouting": "123456789",
  • "businessType": "business",
  • "city": "Boulder",
  • "company": "Mystic Mountain Tours LLC",
  • "communicationEmail": "bookings@mystic-mountain-tours.com",
  • "country": "United States",
  • "countryCode": "US",
  • "currency": "USD",
  • "email": "info@mystic-mountain-tours.com",
  • "emailFooter": "Thank you for choosing Mystic Mountain Tours!",
  • "geo": {
    },
  • "geoNameId": 5294810,
  • "name": "Mystic Mountain Tours",
  • "personName": "John Smith",
  • "phone": "+1-555-123-4567",
  • "registrationPath": "self_registration",
  • "state": "Colorado",
  • "statementDescriptor": "MYSTIC MOUNTAIN TOURS",
  • "streetAddress": "456 Mountain View Road",
  • "timezone": -7,
  • "timezoneName": "America/Denver",
  • "website": "https://mystic-mountain-tours.com",
  • "zip": "80301",
  • "id": "507f1f77bcf86cd799439011",
  • "version": 2,
  • "enabled": true,
  • "balance": 1250.5,
  • "disputedBalance": 0,
  • "unrecoveredBalance": 0,
  • "locale": "en_US",
  • "picture": {
    },
  • "medias": [
    ],
  • "acceptedCards": [
    ],
  • "allowedGateways": [
    ],
  • "defaultGateway": "stripe",
  • "fees": [
    ],
  • "pluginFees": {
    },
  • "processingFeeFormulas": [
    ],
  • "partnerFeeFormulas": [
    ],
  • "paymentMethods": [
    ],
  • "remoteCards": [
    ],
  • "remoteGateways": [
    ],
  • "plans": [
    ],
  • "subscriptionPlan": {
    },
  • "stripeAccount": {
    },
  • "topUpSource": {
    },
  • "autoAccept": {
    },
  • "blackoutSchedules": [
    ],
  • "terms": {
    },
  • "preferences": {
    },
  • "roles": [
    ],
  • "delegates": [
    ],
  • "meta": {
    },
  • "customerNotes": {
    },
  • "bankAccountLast4": "7890",
  • "bankRoutingLast4": "6789",
  • "taxIdLast4": "1234",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get seller information

Retrieves detailed information about a specific seller. Response content varies based on admin access and expand parameters.

Permission-based response fields:

  • When the authenticated user has the ROLE_BOOKING_ENGINE delegate permission for the seller, the response includes additional fields under preferences:
    • preferences.communicationChannels — the seller's enabled communication channels.
    • preferences.notifications — the seller's notification preferences configuration.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

query Parameters
admin
boolean
Default: false
Example: admin=true

Include admin-only fields (requires admin role)

expand
string
Example: expand=defaultGateway,subscriptionPlan

Comma-separated list of related objects to expand

exclude
string
Example: exclude=preferences,meta

Comma-separated list of fields to exclude from response

Responses

Response samples

Content type
application/json
{
  • "bankAccount": "1234567890",
  • "bankAccountType": "checking",
  • "bankRouting": "123456789",
  • "businessType": "business",
  • "city": "Boulder",
  • "company": "Mystic Mountain Tours LLC",
  • "communicationEmail": "bookings@mystic-mountain-tours.com",
  • "country": "United States",
  • "countryCode": "US",
  • "currency": "USD",
  • "email": "info@mystic-mountain-tours.com",
  • "emailFooter": "Thank you for choosing Mystic Mountain Tours!",
  • "geo": {
    },
  • "geoNameId": 5294810,
  • "name": "Mystic Mountain Tours",
  • "personName": "John Smith",
  • "phone": "+1-555-123-4567",
  • "registrationPath": "self_registration",
  • "state": "Colorado",
  • "statementDescriptor": "MYSTIC MOUNTAIN TOURS",
  • "streetAddress": "456 Mountain View Road",
  • "timezone": -7,
  • "timezoneName": "America/Denver",
  • "website": "https://mystic-mountain-tours.com",
  • "zip": "80301",
  • "id": "507f1f77bcf86cd799439011",
  • "version": 2,
  • "enabled": true,
  • "balance": 1250.5,
  • "disputedBalance": 0,
  • "unrecoveredBalance": 0,
  • "locale": "en_US",
  • "picture": {
    },
  • "medias": [
    ],
  • "acceptedCards": [
    ],
  • "allowedGateways": [
    ],
  • "defaultGateway": "stripe",
  • "fees": [
    ],
  • "pluginFees": {
    },
  • "processingFeeFormulas": [
    ],
  • "partnerFeeFormulas": [
    ],
  • "paymentMethods": [
    ],
  • "remoteCards": [
    ],
  • "remoteGateways": [
    ],
  • "plans": [
    ],
  • "subscriptionPlan": {
    },
  • "stripeAccount": {
    },
  • "topUpSource": {
    },
  • "autoAccept": {
    },
  • "blackoutSchedules": [
    ],
  • "terms": {
    },
  • "preferences": {
    },
  • "roles": [
    ],
  • "delegates": [
    ],
  • "meta": {
    },
  • "customerNotes": {
    },
  • "bankAccountLast4": "7890",
  • "bankRoutingLast4": "6789",
  • "taxIdLast4": "1234",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Enable a seller account

Enables a seller account by setting enabled status to true. Also reactivates associated subscription plans if applicable.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Disable a seller account

Disables a seller account by setting enabled status to false. Also deactivates the account and associated subscription plans.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update allowed payment gateways

Updates the list of payment gateways allowed for a seller. Admin-only endpoint. Automatically creates Stripe managed accounts if Xola Stripe platform gateway is enabled and seller doesn't have one.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
allowedGateways
required
Array of strings
Items Enum: "stripe_xola" "stripe_xola_canada" "stripe_oauth" "stripe_api_key" "authorize_net_aim" "authorize_net_cim" "cybersource"

List of allowed payment gateway types. Available options:

  • stripe_xola - Xola's managed Stripe account (USA)
  • stripe_xola_canada - Xola's managed Stripe account (Canada)
  • stripe_oauth - Seller's own Stripe account via OAuth
  • stripe_api_key - Seller's own Stripe account via API key
  • authorize_net_aim - Authorize.Net AIM gateway
  • authorize_net_cim - Authorize.Net CIM gateway
  • cybersource - CyberSource payment gateway

Responses

Request samples

Content type
application/json
{
  • "allowedGateways": [
    ]
}

Response samples

Content type
application/json
[
  • "stripe_xola",
  • "stripe_oauth"
]

Update seller KYC information

Updates Know Your Customer (KYC) information for a seller. This information is used for payment processing compliance.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
accountHolderName
required
string

Legal name of the account holder

dateOfBirth
required
string <date>

Date of birth of the account holder

Responses

Request samples

Content type
application/json
{
  • "accountHolderName": "John Smith",
  • "dateOfBirth": "1985-03-15"
}

Response samples

Content type
application/json
[
  • null
]

Update seller KYC information (alias)

Alias for POST /sellers/{id}/kycInfo

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
accountHolderName
required
string

Legal name of the account holder

dateOfBirth
required
string <date>

Date of birth of the account holder

Responses

Request samples

Content type
application/json
{
  • "accountHolderName": "John Smith",
  • "dateOfBirth": "1985-03-15"
}

Response samples

Content type
application/json
[
  • null
]

Create a Stripe Account Session

Creates a Stripe Account Session for rendering embedded Stripe Connect components.

This endpoint generates a clientSecret that can be used to initialize Stripe embedded components such as payment_method_settings, disputes_list, and payment_disputes on the seller's dashboard.

Requirements:

  • The seller must have a Stripe account configured and be on a Stripe gateway.
  • Requires VIEW_SELLER_SEMI_PRIVATE_DATA permission at the route level.

Supported Components and Permissions:

  • payment_method_settings: Allows sellers to manage their payment method settings. This component is in preview and requires a Stripe beta header. Requires EDIT_USER_STRIPE_ACCOUNT permission.
  • disputes_list: Displays a list of disputes for the seller's Stripe account. Automatically enables destination_on_behalf_of_charge_management and dispute_management features, while disabling capture_payments and refund_management. Requires VIEW_SELLER_STRIPE_DISPUTES permission.
  • payment_disputes: Displays and manages payment disputes. Enables destination_on_behalf_of_charge_management and dispute_management features, while disabling refund_management. Requires EDIT_SELLER_STRIPE_DISPUTES permission.
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
required
object non-empty

A map of Stripe embedded component names to their configuration. Each key is a component name, and the value is the component-specific configuration object.

Responses

Request samples

Content type
application/json
Example
{
  • "components": {
    }
}

Response samples

Content type
application/json
{
  • "clientSecret": "acss_secret_abc123..."
}

Create a customer note

Add a note to a customer (traveler) on the given seller account.

Requires the EDIT_USER_CUSTOMERS permission on the seller.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

travelerId
required
string
Example: 507f1f77bcf86cd799439012

Traveler (customer) ID

Request Body schema: application/json
required
text
required
string

Note content

Responses

Request samples

Content type
application/json
{
  • "text": "VIP customer - offer complimentary upgrade"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Update a customer note

Update the text of an existing customer note. System-generated notes cannot be edited and return a 403 response.

Requires the EDIT_USER_CUSTOMERS permission on the seller.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

travelerId
required
string
Example: 507f1f77bcf86cd799439012

Traveler (customer) ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Request Body schema: application/json
required
text
required
string

Updated note content

system
boolean

Whether the note is a system-generated note.

Responses

Request samples

Content type
application/json
{
  • "text": "VIP customer - complimentary upgrade already applied"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Delete a customer note

Delete a customer note. System-generated notes cannot be removed and return a 403 response.

Requires the EDIT_USER_CUSTOMERS permission on the seller.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

travelerId
required
string
Example: 507f1f77bcf86cd799439012

Traveler (customer) ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload seller primary picture (logo)

Uploads the primary picture/logo for a seller account. This sets the main profile image displayed for the seller.

Supports both xhr upload (with qqfile parameter) and form upload.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

query Parameters
qqfile
string
Example: qqfile=logo.jpg

Filename for xhr upload

Request Body schema:
qqfile
string <binary>

Image file to upload

target
string

Target usage for the media

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "target": "string"
}

Upload additional seller media

Uploads additional media files for a seller account (beyond the primary logo). These can include promotional images, videos, or documents.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

query Parameters
qqfile
string
Example: qqfile=promo-image.jpg

Filename for xhr upload

Request Body schema:
qqfile
string <binary>

Media file to upload

target
string

Target usage for the media

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "string",
  • "caption": "string",
  • "type": "image",
  • "size": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "target": "string"
}

Get seller media files

Retrieves all media files associated with a seller account. Results can be filtered by target usage and media type.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

query Parameters
target
string
Example: target=checkout_banner

Filter by target usage

type
string
Enum: "photo" "video" "document"
Example: type=photo

Filter by media type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get specific seller media file

Retrieves a specific media file for a seller, with optional resizing. Returns a redirect to the actual media file URL.

Parameter Precedence: If both width AND height are specified, they take precedence over the size preset. If only width OR only height is provided (not both), the size preset will be used instead. If neither width/height nor size is provided, the original image is returned.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

mediaId
required
string
Example: 507f1f77bcf86cd799439012

Media file ID

query Parameters
width
integer [ 1 .. 2000 ]
Example: width=300

Desired image width in pixels

height
integer [ 1 .. 2000 ]
Example: height=200

Desired image height in pixels

size
string
Enum: "small" "medium" "large" "thumbnail"
Example: size=medium

Predefined size preset with specific dimensions:

  • thumbnail = 150x150px (square thumbnail)
  • small = 300x200px (3:2 aspect ratio)
  • medium = 600x400px (3:2 aspect ratio)
  • large = 1200x800px (3:2 aspect ratio)

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Activate a feature for a seller

Activates a feature flag for a seller account. This endpoint enables specific features for sellers based on their subscription plan and permissions.

Authorization:

  • Requires EDIT_USER_FEATURES permission on the seller
  • Admin users can enable any feature
  • App Store users can enable subscription features
  • Regular users can only enable features included in their subscription plan

Feature Validation:

  • Non-admin users cannot enable beta features
  • Non-admin users cannot enable features outside their subscription
  • Requests for unavailable features trigger an email notification to Xola

Side Effects:

  • Creates an audit log entry
  • Triggers a SELLER_UPDATE event
  • May send feature request emails to Xola for restricted features
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to activate

Request Body schema: application/json
optional

Feature ID in request body (alternative to path parameter)

id
string

The feature ID to activate

Responses

Request samples

Content type
application/json
{
  • "id": "mobileApp"
}

Response samples

Content type
application/json
{
  • "id": "advancedReporting"
}

Activate a feature for a seller (PUT method)

Alternative PUT method for activating a feature flag for a seller account. Behaves identically to the POST method.

See the POST method documentation for complete details on authorization, validation, and side effects.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to activate

Request Body schema: application/json
optional

Feature ID in request body (alternative to path parameter)

id
string

The feature ID to activate

Responses

Request samples

Content type
application/json
{
  • "id": "mobileApp"
}

Response samples

Content type
application/json
{
  • "id": "advancedReporting"
}

Deactivate a feature for a seller

Deactivates a feature flag for a seller account. This removes access to the specified feature for the seller.

Authorization:

  • Requires EDIT_USER_FEATURES permission on the seller
  • Sellers can deactivate their own features
  • Admins can deactivate any seller's features

Side Effects:

  • Creates an audit log entry
  • Triggers a SELLER_UPDATE event
  • Non-admin deactivations send a notification email to Xola
  • May trigger subscription package changes

Important: Deactivating a feature may affect the seller's subscription package eligibility and will notify Xola staff for review.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string (id) ^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439012

The seller ID

featureId
required
string
Example: advancedReporting

The feature ID to deactivate

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Create check-in rule

Create a new check-in rule for ticket validation during guest check-in process. Rules can be mandatory or optional and can display validation results on tickets.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
name
required
string

Name of the check-in rule

required
boolean

Whether this rule must be validated during guest check-in

showOnTicket
boolean

Whether validation result appears on the ticket

passText
string

Text to show on ticket if the rule passes validation

failText
string

Text to show on ticket if the rule fails validation

Responses

Request samples

Content type
application/json
{
  • "name": "Age Verification",
  • "required": true,
  • "showOnTicket": true,
  • "passText": "Age verified ✓",
  • "failText": "Age verification required"
}

Response samples

Content type
application/json
{
  • "name": "Age Verification",
  • "required": true,
  • "showOnTicket": true,
  • "passText": "Age verified ✓",
  • "failText": "Age verification required",
  • "id": "507f1f77bcf86cd799439011"
}

Update check-in rule

Update an existing check-in rule by ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

ruleId
required
string
Example: 507f1f77bcf86cd799439012

Check-in rule ID

Request Body schema: application/json
required
name
required
string

Name of the check-in rule

required
boolean

Whether this rule must be validated during guest check-in

showOnTicket
boolean

Whether validation result appears on the ticket

passText
string

Text to show on ticket if the rule passes validation

failText
string

Text to show on ticket if the rule fails validation

Responses

Request samples

Content type
application/json
{
  • "name": "Age Verification",
  • "required": true,
  • "showOnTicket": true,
  • "passText": "Age verified ✓",
  • "failText": "Age verification required"
}

Response samples

Content type
application/json
{
  • "name": "Age Verification",
  • "required": true,
  • "showOnTicket": true,
  • "passText": "Age verified ✓",
  • "failText": "Age verification required",
  • "id": "507f1f77bcf86cd799439011"
}

Delete check-in rule

Remove a check-in rule by ID

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

ruleId
required
string
Example: 507f1f77bcf86cd799439012

Check-in rule ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update custom style preferences

Configure custom styling preferences for user interface customization. Requires admin role permissions.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
seller
string or null <uri>

URL pointing to a remote CSS file for seller interface customization

checkout
string or null <uri>

URL pointing to a remote CSS file for checkout page customization

checkoutV2
string or null <uri>

URL pointing to a remote CSS file for the V2 checkout page customization

traveler
string or null <uri>

URL pointing to a remote CSS file for traveler interface customization

ticket
string or null <uri>

URL pointing to a remote CSS file for order ticket page customization

Responses

Request samples

Update custom style preferences

Configure custom styling preferences for user interface customization. Requires admin role permissions.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
seller
string or null <uri>

URL pointing to a remote CSS file for seller interface customization

checkout
string or null <uri>

URL pointing to a remote CSS file for checkout page customization

checkoutV2
string or null <uri>

URL pointing to a remote CSS file for the V2 checkout page customization

traveler
string or null <uri>

URL pointing to a remote CSS file for traveler interface customization

ticket
string or null <uri>

URL pointing to a remote CSS file for order ticket page customization

Responses

Update booking preferences

Configure booking behavior preferences including post-booking actions, order limitations, and itemization settings.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
postBookingAction
string or null

Action to be performed post booking

allowMultiItemOrders
boolean or null

Whether to allow multiple items in a single order (deprecated)

allowMultiplePrivateEvents
boolean or null

Whether multiple private events can be created for the same timeslot

allowPastDates
boolean or null

Whether past dates are available when making a booking or switching arrival/experience

allowBookingEngineOrderModification
boolean or null

Whether booking engine orders can be modified by the seller

timeslotReservationLimit
integer or null >= 1

Maximum number of reserved reservations allowed for any given time slot, across all experiences

reservationLimit
integer or null >= 1

Maximum number of experience items an order should be limited to in case of MIST booking

object or null

Order itemization settings

defaultPriceStrategyForPurchaseEdit
string or null

Default strategy for the retain price toggle in all purchase modification screens

Responses

Request samples

Content type
application/json
{
  • "postBookingAction": "goToDashboard",
  • "allowMultiItemOrders": true,
  • "allowMultiplePrivateEvents": false,
  • "allowPastDates": false,
  • "allowBookingEngineOrderModification": false,
  • "timeslotReservationLimit": 10,
  • "reservationLimit": 5,
  • "orderItemization": {
    },
  • "defaultPriceStrategyForPurchaseEdit": "retain"
}

Response samples

Content type
application/json
{
  • "postBookingAction": "goToDashboard",
  • "allowMultiItemOrders": true,
  • "allowMultiplePrivateEvents": false,
  • "allowPastDates": false,
  • "allowBookingEngineOrderModification": false,
  • "timeslotReservationLimit": 10,
  • "reservationLimit": 5,
  • "orderItemization": {
    },
  • "defaultPriceStrategyForPurchaseEdit": "retain"
}

Update payment preferences

Configure payment processing preferences including billing requirements, 3D Secure settings, tax calculation, and fraud prevention.

Note: V2 sellers cannot disable 3D Secure - contact support for assistance.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
requireAdditionalBillingInfo
boolean

Whether to require additional billing information during card payment

threeDSecureEnabled
boolean

Whether 3D Secure transactions are enabled

taxAssessedOn
string
Enum: "promotional_value" "purchase_value"

How tax is calculated when voucher is applied

refundProcessingFee
boolean

Whether CC processing fee is returned upon full order refund

enforcePostalCode
boolean

Whether postal code is required during billing

object

Fraud prevention settings

Responses

Request samples

Content type
application/json
{
  • "requireAdditionalBillingInfo": true,
  • "threeDSecureEnabled": true,
  • "taxAssessedOn": "purchase_value",
  • "refundProcessingFee": false,
  • "fraud": {
    }
}

Response samples

Content type
application/json
{
  • "requireAdditionalBillingInfo": true,
  • "threeDSecureEnabled": true,
  • "taxAssessedOn": "purchase_value",
  • "refundProcessingFee": false,
  • "enforcePostalCode": true,
  • "fraud": {
    }
}

Update branding preferences

Configure custom branding preferences including SMTP settings for branded emails. All SMTP fields are required when configuring custom email branding.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
emailFooter
string or null

Custom footer text for email templates

receiptFooter
string or null

Custom footer text for receipt emails

object or null

Custom SMTP configuration for branded emails (all fields required when configuring)

Responses

Request samples

Content type
application/json
{
  • "customSmtp": {
    }
}

Response samples

Content type
application/json
{
  • "emailFooter": "Thank you for choosing our service!",
  • "receiptFooter": "Visit our website for more information",
  • "customSmtp": {
    }
}

Update branding preferences

Configure custom branding preferences including SMTP settings for branded emails. All SMTP fields are required when configuring custom email branding.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
emailFooter
string or null

Custom footer text for email templates

receiptFooter
string or null

Custom footer text for receipt emails

object or null

Custom SMTP configuration for branded emails (all fields required when configuring)

Responses

Request samples

Content type
application/json
{
  • "emailFooter": "Thank you for choosing our service!",
  • "receiptFooter": "Visit our website for more information",
  • "customSmtp": {
    }
}

Response samples

Content type
application/json
{
  • "emailFooter": "Thank you for choosing our service!",
  • "receiptFooter": "Visit our website for more information",
  • "customSmtp": {
    }
}

Update checkout preferences

Configure checkout process preferences including price display options and themes.

Price display options:

  • hide: Don't show pricing until the last checkout page
  • range: Show price range (min - max)
  • lowest: Show the lowest possible price (default)
  • base: Show the configured experience price

Some options require specific permissions (X2 checkout).

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
priceDisplay
string
Enum: "hide" "range" "lowest" "base"

How pricing information is displayed during checkout:

  • hide: Do not show pricing until the last page
  • range: Show price range (min - max)
  • lowest: Show the lowest possible price (default)
  • base: Show the configured experience price
includeFees
boolean

Include taxes and fees in the final price displayed on checkout

displayEventDuration
boolean

Display duration of event on checkout

showTaxesAndFeesBreakdown
boolean

Show a taxes and fees breakdown in the checkout app

showExcerptInTile
boolean

Show the product excerpt in the multi-item checkout tile

object or null

Checkout theme configuration

x2Probability
number [ 0 .. 1 ]

X2 checkout probability (requires X2 checkout permission)

object or null

Checkout flow weights configuration

Array of objects

Footer links configuration

Responses

Request samples

Content type
application/json
{
  • "priceDisplay": "range"
}

Response samples

Content type
application/json
{
  • "priceDisplay": "range",
  • "includeFees": false,
  • "displayEventDuration": true,
  • "showTaxesAndFeesBreakdown": true,
  • "showExcerptInTile": false,
  • "theme": {
    },
  • "x2Probability": 1,
  • "flowWeights": {
    },
  • "footerLinks": []
}

Update checkout preferences

Configure checkout process preferences including price display options and themes.

Price display options:

  • hide: Don't show pricing until the last checkout page
  • range: Show price range (min - max)
  • lowest: Show the lowest possible price (default)
  • base: Show the configured experience price
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
priceDisplay
string
Enum: "hide" "range" "lowest" "base"

How pricing information is displayed during checkout:

  • hide: Do not show pricing until the last page
  • range: Show price range (min - max)
  • lowest: Show the lowest possible price (default)
  • base: Show the configured experience price
includeFees
boolean

Include taxes and fees in the final price displayed on checkout

displayEventDuration
boolean

Display duration of event on checkout

showTaxesAndFeesBreakdown
boolean

Show a taxes and fees breakdown in the checkout app

showExcerptInTile
boolean

Show the product excerpt in the multi-item checkout tile

object or null

Checkout theme configuration

x2Probability
number [ 0 .. 1 ]

X2 checkout probability (requires X2 checkout permission)

object or null

Checkout flow weights configuration

Array of objects

Footer links configuration

Responses

Request samples

Content type
application/json
{
  • "priceDisplay": "range",
  • "includeFees": false,
  • "displayEventDuration": true,
  • "showTaxesAndFeesBreakdown": true,
  • "showExcerptInTile": false,
  • "theme": {
    },
  • "x2Probability": 1,
  • "flowWeights": {
    },
  • "footerLinks": []
}

Response samples

Content type
application/json
{
  • "priceDisplay": "range",
  • "includeFees": false,
  • "displayEventDuration": true,
  • "showTaxesAndFeesBreakdown": true,
  • "showExcerptInTile": false,
  • "theme": {
    },
  • "x2Probability": 1,
  • "flowWeights": {
    },
  • "footerLinks": []
}

Update date picker preferences

Configure date picker widget preferences including theme, format, and locale settings

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
displayType
string
Enum: "none" "price" "count"

Type of information to display on date picker:

  • none: No additional information
  • price: Show pricing information
  • count: Show availability count
priceDisplay
string
Enum: "lowest" "highest"

Which price to display when displayType is 'price':

  • lowest: Show the lowest price
  • highest: Show the highest price
unavailableMessage
string or null <= 15 characters

Custom message to show when a date is unavailable (max 15 characters)

unavailableScheduleMessage
string or null

Custom message to show when a schedule is not available for the date

showUnavailableTimes
boolean or null

Whether to show unavailable time slots in front-office datepicker

displayCountMax
integer or null >= 0

Show availability count only if below this value

showNextDayTimeslotsTill
integer or null [ 0 .. 2359 ]

Time in military format - show next day timeslots until this time

showCurrentDayTimeslotsAfter
integer or null [ 0 .. 2359 ]

Time in military format - hide current day timeslots before this time

Responses

Request samples

Content type
application/json
{
  • "displayType": "price",
  • "priceDisplay": "highest",
  • "unavailableMessage": "Sold Out",
  • "unavailableScheduleMessage": "No times available",
  • "showUnavailableTimes": false,
  • "displayCountMax": 10,
  • "showNextDayTimeslotsTill": 200,
  • "showCurrentDayTimeslotsAfter": 600
}

Response samples

Content type
application/json
{
  • "displayType": "price",
  • "priceDisplay": "highest",
  • "unavailableMessage": "Sold Out",
  • "unavailableScheduleMessage": "No times available",
  • "showUnavailableTimes": false,
  • "displayCountMax": 10,
  • "showNextDayTimeslotsTill": 200,
  • "showCurrentDayTimeslotsAfter": 600
}

Update gift certificate preferences

Configure gift certificate preferences including email templates and additional experience visibility

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
enabled
boolean or null

Whether gift feature is enabled

showAdditionalExperiences
boolean or null

Whether additional bookable experiences are included in gift emails

customerPhoneRequired
boolean or null

Whether customer phone number is mandatory upon purchase

captchaEnabled
boolean or null

Whether captcha is enabled for gift purchases

allowMultiItemGifts
boolean or null

Whether to allow multiple items in gift purchases (deprecated)

showDemographics
boolean or null

Whether to show demographics in gift purchase flow (deprecated)

Responses

Request samples

Content type
application/json
{
  • "showAdditionalExperiences": true
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "showAdditionalExperiences": true,
  • "customerPhoneRequired": true,
  • "captchaEnabled": true,
  • "allowMultiItemGifts": true,
  • "showDemographics": true
}

Update all notification preferences

Configure notification preferences for all notification types. Updates the complete notification preferences configuration.

Abandoned Recovery Preferences: The abandoned_recovery_to_traveler type supports configurable multi-email recovery sequences. Each email channel can have a different offset, and a send window (sendStartTime/sendEndTime) can restrict when emails are sent. If a computed send time falls outside the window, it is delayed to the next window start.

Validation: For abandoned_recovery_to_traveler, all enabled email channel offsets must be at least 240 minutes (4 hours) apart. If violated, a 400 error is returned with:

{
  "channels": {
    "reason": "invalid_offset_gaps",
    "message": "Reminder offsets must be at least 4 hours apart."
  }
}
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
Array of objects (NotificationPreferenceRequest)

Array of notification preferences

Responses

Request samples

Content type
application/json
Example
{
  • "preferences": [
    ]
}

Response samples

Content type
application/json
{
  • "preferences": [
    ]
}

Update all notification preferences

Configure notification preferences for all notification types. Updates the complete notification preferences configuration.

See POST endpoint for details on abandoned_recovery_to_traveler type, send window configuration, and offset gap validation.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
Array of objects (NotificationPreferenceRequest)

Array of notification preferences

Responses

Request samples

Content type
application/json
{
  • "preferences": [
    ]
}

Response samples

Content type
application/json
{
  • "preferences": [
    ]
}

Update single notification preference

Update a specific notification preference by notification type. The notification type in the URL must match the type field in the request body.

For abandoned_recovery_to_traveler type, optional sendStartTime and sendEndTime fields can be included to configure a send window (military time format). All enabled email channel offsets must be at least 240 minutes (4 hours) apart, or a 400 error with reason invalid_offset_gaps is returned.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

notificationType
required
string
Example: abandoned_recovery_to_traveler

Notification type to update

Request Body schema: application/json
required
type
required
string

Type of notification. Common values include booking_confirmation, booking_reminder, and the newer abandoned_recovery_to_traveler for configurable abandoned cart recovery emails sent to travelers.

required
Array of objects

Notification channels and their settings. For abandoned_recovery_to_traveler, multiple email channels can be configured with different offsets to send a series of recovery emails. Each enabled email channel offset must be at least 4 hours apart.

sendStartTime
integer [ 0 .. 2359 ]

Start of the send window in military HHMM format, where the hour portion is 0–23 and the minute portion (last two digits) must be 00–59. Examples: 900 = 9:00 AM, 1730 = 5:30 PM. Only applicable for abandoned_recovery_to_traveler notification type. If omitted, defaults to 0 (midnight). Supports wrap-around windows (e.g., 2200 to 0600).

sendEndTime
integer [ 0 .. 2359 ]

End of the send window in military HHMM format, where the hour portion is 0–23 and the minute portion (last two digits) must be 00–59. Examples: 900 = 9:00 AM, 2100 = 9:00 PM. Only applicable for abandoned_recovery_to_traveler notification type. If omitted, defaults to 2359 (11:59 PM). Supports wrap-around windows (e.g., 2200 to 0600).

Responses

Request samples

Content type
application/json
Example
{
  • "type": "booking_confirmation",
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "preferences": [
    ]
}

Update Google integration preferences

Configure Google Analytics, Tag Manager, and advertising integration preferences

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
gtmId
string or null

Google Tag Manager ID specified for this user

Array of objects

Array of Google Places associated with the user

Responses

Request samples

Content type
application/json
{
  • "gtmId": "GTM-XXXXXXX",
  • "places": [
    ]
}

Response samples

Content type
application/json
{
  • "gtmId": "GTM-XXXXXXX",
  • "places": [
    ]
}

Create conversion tracking preference

Create a new conversion tracking configuration for marketing platforms

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
enabled
boolean or null

Whether this conversion tracking is enabled

label
string or null

Label/name for this tracking configuration

code
string or null

Code template with variables for conversion tracking. Available variables: order.amount, order.purchaseAmount, order.currency, order.id, order.productId, order.productName, order.productType, order.quantity, order.arrival, order.couponCode, session, order.seller.id, order.seller.name, order.seller.city, order.seller.state, order.seller.country, order.seller.countryCode

Responses

Request samples

Content type
application/json
{
  • "enabled": false,
  • "label": "Facebook Conversion Tracking",
  • "code": "fbq('track', 'Purchase');"
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "label": "Facebook Conversion Tracking",
  • "code": "gtag('event', 'purchase', { value: {{order.amount}}, currency: '{{order.currency}}' });",
  • "id": "507f1f77bcf86cd799439011"
}

Update conversion tracking preference

Update an existing conversion tracking configuration

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

trackingId
required
string
Example: 507f1f77bcf86cd799439012

Conversion tracking ID

Request Body schema: application/json
required
enabled
boolean or null

Whether this conversion tracking is enabled

label
string or null

Label/name for this tracking configuration

code
string or null

Code template with variables for conversion tracking. Available variables: order.amount, order.purchaseAmount, order.currency, order.id, order.productId, order.productName, order.productType, order.quantity, order.arrival, order.couponCode, session, order.seller.id, order.seller.name, order.seller.city, order.seller.state, order.seller.country, order.seller.countryCode

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "label": "Facebook Conversion Tracking",
  • "code": "gtag('event', 'purchase', { value: {{order.amount}}, currency: '{{order.currency}}' });"
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "label": "Facebook Conversion Tracking",
  • "code": "gtag('event', 'purchase', { value: {{order.amount}}, currency: '{{order.currency}}' });",
  • "id": "507f1f77bcf86cd799439011"
}

Update Facebook Pixel tracking preferences

Configure Facebook Pixel tracking for conversion monitoring and remarketing

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
enabled
boolean

Whether Facebook Pixel tracking is enabled

facebookPixelId
string

Facebook Pixel ID

allowAdvancedConversionTracking
boolean

Whether to allow advanced conversion tracking

accessToken
string

Facebook access token for advanced features

Responses

Request samples

Content type
application/json
{
  • "enabled": false,
  • "facebookPixelId": "123456789012345",
  • "allowAdvancedConversionTracking": false,
  • "accessToken": "EAABwzLixnjYBAJWY5OlkUF3..."
}

Response samples

Content type
application/json
{
  • "enabled": false,
  • "facebookPixelId": "123456789012345",
  • "allowAdvancedConversionTracking": false,
  • "accessToken": "EAABwzLixnjYBAJWY5OlkUF3..."
}

Update affiliate program preferences

Configure affiliate program settings including commission rates and cookie duration

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
allowLogin
boolean

Whether affiliates should be allowed to login into Xola

object

Affiliate credit line configuration

Responses

Request samples

Content type
application/json
{
  • "allowLogin": false,
  • "affiliateCreditLine": {
    }
}

Response samples

Content type
application/json
{
  • "allowLogin": false,
  • "affiliateCreditLine": {
    }
}

Update inventory management preferences

Configure inventory and booking automation preferences

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
allocationStrategy
string
Enum: "smallest_first" "largest_first" "custom_assignment"

Strategy to be used while assigning resources to events:

  • smallest_first: Assign smallest available resources first
  • largest_first: Assign largest available resources first
  • custom_assignment: Use custom prioritized resource assignment
Array of objects

Sorted list of resources (only for custom_assignment strategy)

Responses

Request samples

Content type
application/json
{
  • "allocationStrategy": "largest_first",
  • "prioritizedResources": [ ]
}

Response samples

Content type
application/json
{
  • "allocationStrategy": "largest_first",
  • "prioritizedResources": [
    ]
}

Create review preferences

Configure customer review and rating collection preferences

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
destination
string
Enum: "off" "xola" "googlePlus" "tripAdvisor" "yelp" "custom"

Review destination platform

reviewTemplate
string or null

Custom review template (required when destination is 'custom')

reviewLink
string or null <uri>

Custom review link URL (required when destination is 'googlePlus')

sendReviewEmailToAllTravelers
boolean

Whether to send review email to all travelers in the booking. Note: For experience-level review preference endpoints (POST/PUT /api/experiences/{id}/preferences/review), this field is ignored. Use the notifications array on the experience to control review reminder recipients (set review_reminder_to_traveler recipients to travelers or organizer).

enableSmartReview
boolean

Whether to enable smart review redirection. When enabled, travelers who leave a rating greater than or equal to smartReviewThreshold will be redirected to the external review platform specified in destination. Only valid when destination is googlePlus, tripAdvisor, or yelp.

smartReviewThreshold
integer [ 2 .. 5 ]

Minimum rating required to redirect a traveler to the external review platform when smart review is enabled. Must be between 2 and 5 (inclusive). Defaults to 4.

Responses

Request samples

Content type
application/json
{
  • "destination": "xola",
  • "reviewTemplate": null,
  • "reviewLink": null,
  • "sendReviewEmailToAllTravelers": false
}

Response samples

Content type
application/json
{
  • "destination": "xola",
  • "reviewTemplate": "Please leave us a review at our custom platform",
  • "reviewLink": "https://maps.google.com/place?cid=123456789",
  • "sendReviewEmailToAllTravelers": false,
  • "enableSmartReview": false,
  • "smartReviewThreshold": 4
}

Update review preferences

Update customer review and rating collection preferences

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
destination
string
Enum: "off" "xola" "googlePlus" "tripAdvisor" "yelp" "custom"

Review destination platform

reviewTemplate
string or null

Custom review template (required when destination is 'custom')

reviewLink
string or null <uri>

Custom review link URL (required when destination is 'googlePlus')

sendReviewEmailToAllTravelers
boolean

Whether to send review email to all travelers in the booking. Note: For experience-level review preference endpoints (POST/PUT /api/experiences/{id}/preferences/review), this field is ignored. Use the notifications array on the experience to control review reminder recipients (set review_reminder_to_traveler recipients to travelers or organizer).

enableSmartReview
boolean

Whether to enable smart review redirection. When enabled, travelers who leave a rating greater than or equal to smartReviewThreshold will be redirected to the external review platform specified in destination. Only valid when destination is googlePlus, tripAdvisor, or yelp.

smartReviewThreshold
integer [ 2 .. 5 ]

Minimum rating required to redirect a traveler to the external review platform when smart review is enabled. Must be between 2 and 5 (inclusive). Defaults to 4.

Responses

Request samples

Content type
application/json
{
  • "destination": "xola",
  • "reviewTemplate": "Please leave us a review at our custom platform",
  • "reviewLink": "https://maps.google.com/place?cid=123456789",
  • "sendReviewEmailToAllTravelers": false,
  • "enableSmartReview": false,
  • "smartReviewThreshold": 4
}

Response samples

Content type
application/json
{
  • "destination": "xola",
  • "reviewTemplate": "Please leave us a review at our custom platform",
  • "reviewLink": "https://maps.google.com/place?cid=123456789",
  • "sendReviewEmailToAllTravelers": false,
  • "enableSmartReview": false,
  • "smartReviewThreshold": 4
}

Delete review preferences

Remove review and rating collection preferences

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update user split payment preferences

Configure split payment preferences for a specific user. Split payment allows customers to pay in multiple installments with configurable deadlines.

Key Features:

  • Enable/disable split payment for the user
  • Set payment deadline in minutes after booking
  • Configure automatic charging on deadline
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

User ID

Request Body schema: application/json
required
isEnabled
boolean

Whether split payment option is enabled for this user

paymentDeadline
integer >= 1

Payment deadline in minutes after booking creation

autoChargeOnDeadline
boolean

Whether to automatically charge the remaining balance when payment deadline is reached

Responses

Request samples

Content type
application/json
{
  • "isEnabled": true,
  • "paymentDeadline": 1440,
  • "autoChargeOnDeadline": false
}

Response samples

Content type
application/json
{
  • "isEnabled": true,
  • "paymentDeadline": 1440,
  • "autoChargeOnDeadline": false
}

Update availability timeline preferences

Configure availability timeline display preferences for a specific user. Controls how availability information is shown in calendar and booking widgets.

Display Options:

  • Show/hide unavailable dates and custom messages
  • Configure pricing display on timeline
  • Control maximum display days and limits
  • Manage excerpt display for additional information
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

User ID

Request Body schema: application/json
required
showUnavailable
boolean

Whether to display unavailable dates/times on the timeline

unavailableMessage
string or null <= 15 characters

Custom message to display for unavailable dates (maximum 15 characters)

showPrice
boolean

Whether to display pricing information on timeline items

showOpen
boolean

Whether to show available/open slots on the timeline

maxDays
integer or null >= 1

Maximum number of days to display in the timeline

showOpenMax
integer or null >= 1

Maximum number of open slots to display per day

showExcerpt
boolean

Whether to display additional excerpt/description information

Responses

Request samples

Content type
application/json
{
  • "showUnavailable": true,
  • "unavailableMessage": "Sold Out",
  • "showPrice": true,
  • "showOpen": true,
  • "maxDays": 365,
  • "showOpenMax": 10,
  • "showExcerpt": false
}

Response samples

Content type
application/json
{
  • "showUnavailable": true,
  • "unavailableMessage": "Sold Out",
  • "showPrice": true,
  • "showOpen": true,
  • "maxDays": 365,
  • "showOpenMax": 10,
  • "showExcerpt": false
}

Create data retention preference

Create or update the data retention preference for a seller. When enabled, maskable customer PII (personally identifiable information) associated with purchase items will automatically be cleared after the specified duration following the purchase fulfillment date.

Duration Constraints:

  • Must be a valid ISO 8601 duration string (e.g. P180D, P1Y, P6M)
  • Minimum value: P180D (180 days)
  • Required when enabled is true

Authorization:

  • Requires EDIT_USER_DATA_RETENTION_PREFERENCE permission on the seller
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
enabled
boolean

Whether automatic data retention (PII masking) is enabled for the seller

duration
string or null

ISO 8601 duration after purchase fulfillment date when maskable customer data should be cleared. Required when enabled is true. Minimum value is P180D (180 days).

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "duration": "P365D"
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "duration": "P365D"
}

Update data retention preference

Create or update the data retention preference for a seller. When enabled, maskable customer PII (personally identifiable information) associated with purchase items will automatically be cleared after the specified duration following the purchase fulfillment date.

Duration Constraints:

  • Must be a valid ISO 8601 duration string (e.g. P180D, P1Y, P6M)
  • Minimum value: P180D (180 days)
  • Required when enabled is true

Authorization:

  • Requires EDIT_USER_DATA_RETENTION_PREFERENCE permission on the seller
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Seller ID

Request Body schema: application/json
required
enabled
boolean

Whether automatic data retention (PII masking) is enabled for the seller

duration
string or null

ISO 8601 duration after purchase fulfillment date when maskable customer data should be cleared. Required when enabled is true. Minimum value is P180D (180 days).

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "duration": "P365D"
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "duration": "P365D"
}

Get global questionnaire for a seller

Retrieve the global questionnaire form for a seller. This form applies to all experiences when no experience-specific form exists.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f191e810c19729de860ea

The unique identifier of the seller

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "seller": {
    },
  • "product": {
    },
  • "productType": "experience",
  • "organizerOnly": true,
  • "fields": [
    ],
  • "optionalSourcesList": [
    ],
  • "deletedAt": "2019-08-24T14:15:22Z"
}

timeslots

The Timeslots API returns availability and pricing data for a given experience at a specific date and time. This is a more advanced version of the availability API, and provides additional data beyond just the availability.

The main attributes in a timeslot object are:

Attribute Type Definition
product string The experience which this timeslot is for
date string The date for this timeslot as a YYYY-MM-DD string
time int The time for this timeslot in military format as an integer
arrivalDatetime string The exact arrival date and time as an ISO datetime string
end string The end time for this timeslot as an ISO datetime string
capacity.open int The availability for this timeslot
capacity.max int The max quantity that can be booked for this timeslot
privacy string The privacy supported for this experience. Possible values: public, private
scheduleType string The schedule type for this experience. Possible values: day, time. A scheduleType of time indicates a specific start and end time, while day indicates an "all day" experience with no fixed timeslots
units Unit[] A list of all purchasable demographics (and merchandise) with their price for the particular timeslot. Optional
canBook boolean A simple flag which indicates if a booking can be placed for this timeslot. Optional
canWaitlist boolean A simple flag which indicates if a waitlist entry can be placed for this timeslot. Present only if canBook is false

Sample timeslot

{
    "product": "65bb71b277c4c31b7c0cdcba",
    "time": 1500,
    "scheduleType": "time",
    "date": "2025-05-13",
    "arrivalDatetime": "2025-05-13T15:00:00-04:00",
    "end": "2025-05-13T15:59:59-04:00",
    "privacy": "public",
    "id": "65bb71b277c4c31b7c0cdcba_2025-05-13",
    "capacity": {
        "open": 5,
        "max": 5
    },
    "canBook": true,
    "units": [
        {
            "price": 100,
            "id": "65798d7f7d106453ee05c767",
            "type": "demographic",
            "code": "adult",
            "priceType": "person"
        },
        {
            "price": 50,
            "id": "65798d807d106453ee05c76a",
            "type": "demographic",
            "code": "child",
            "priceType": "person"
        }
    ]
}

Get timeslots

Retrieve available timeslots for experiences. This is a public endpoint that provides detailed schedule information including available time slots, capacity, pricing, and additional data based on included fields.

This endpoint does not require authentication for basic usage. However, authenticated requests from booking engine users (ROLE_BOOKING_ENGINE) unlock additional behavior:

  • includeFees: When provided, controls whether taxes and fees are included in unit prices returned in the response. This parameter is accepted for authenticated booking engine users as well as other authenticated users.
  • Automatic source handling: For booking engine users, the source is automatically set from the user's configured default source. There is no need to pass source explicitly.

For unauthenticated (checkout) requests, the source defaults to checkout and includeFees is determined by the seller's checkout preferences.

Supports comma-separated values for array parameters and comprehensive filtering options for capacity, guides, resources, and schedule types.

Booking Engine Users: For authenticated booking engine users (ROLE_BOOKING_ENGINE), the source is automatically set from the user's default source. The includeFees query parameter is accepted to control whether unit prices include taxes and fees.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

string or Array of strings
Example: product=507f1f77bcf86cd799439011,507f1f77bcf86cd799439012

Filter by product/experience ID(s). Can be a single ID or comma-separated list.

seller
string
Example: seller=507f1f77bcf86cd799439013

Filter by seller ID

string or string or Array of strings
Examples:
  • start=2024-12-15 - Single date
  • start=2024-12-15,2024-12-20 - Date range
  • start=2024-12-15T10:00:00 - Specific datetime

Start date/time for timeslots. Can be:

  • Single date: '2024-12-15'
  • Date range: '2024-12-15,2024-12-20'
  • DateTime: '2024-12-15T10:00:00'
end
string <date>
Example: end=2024-12-20

End date for timeslots (used with start parameter)

timezone
string
Example: timezone=America/New_York

Timezone for the timeslots (IANA timezone identifier)

string or Array of strings
Example: scheduleType=time,day

Filter by schedule type(s). Can be comma-separated list.

capacity.open[gt]
integer >= 0
Example: capacity.open[gt]=5

Filter timeslots with open capacity greater than specified value

capacity_open[gt]
integer >= 0
Example: capacity_open[gt]=5

Alternative syntax for capacity.open[gt] (underscores instead of dots)

capacity_reserved
integer >= 0
Example: capacity_reserved=10

Filter by reserved capacity

string or Array of strings
Example: guide=507f1f77bcf86cd799439015

Filter by assigned guide ID(s). Can be comma-separated list.

string or Array of strings
Example: resource=507f1f77bcf86cd799439016

Filter by resource ID(s). Can be comma-separated list.

event
string
Example: event=507f1f77bcf86cd799439017

Filter by event ID

waitlistCount[gt]
integer >= 0

Filter timeslots with waitlist count greater than specified value

privacy
string
Default: "public"
Enum: "public" "private"
Example: privacy=public

Filter by privacy level

includeFees
boolean
Example: includeFees=true

When true, unit prices in the response include taxes and fees. For unauthenticated (checkout) requests, this is automatically set from the seller's checkout preference. For authenticated booking engine users, this parameter is accepted directly. For other authenticated users, the parameter is passed through when provided.

allowPastSlots
boolean
Default: false

Include past time slots in results

package
string
Example: package=507f1f77bcf86cd799439018

Package ID for package-specific availability

source
string
Example: source=checkout

The pricing source context. For booking engine users (ROLE_BOOKING_ENGINE), this is automatically set from the user's configured default source and does not need to be provided explicitly. For unauthenticated requests, this defaults to checkout. For other authenticated users, this defaults to office.

id[gt]
string
Example: id[gt]=507f1f77bcf86cd799439011_2024-12-15_900

Pagination cursor - get timeslots with ID greater than specified value

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "expand": { },
  • "paging": {
    },
  • "_hasCachedData": false
}

transactions

Transactions track all movement of money in Xola. For any exchange of money from one user to another (e.g. a consumer paying a seller), a new transaction is created. This is true even if the exchange of money happened offline (e.g. physical cash).

Transactions in Xola track movement in several directions:

  • From a traveler to the seller (creating a new booking)
  • From a seller back to the traveler (a refund)
  • From Xola to the seller (a payout)
  • From a seller to an affiliate (paying out commissions)

Transactions are Immutable

Transactions, once created, are never modified. Once fetched, you may cache transactions locally if required.

Transaction Types

Every transaction has a type attribute that indicates the nature of the transaction. Currently Xola has the following transaction types:

Type Description
purchase The traveler paid an amount to the seller for a purchase. This could reflect creation of a new purchase, or an additional charge on a pre-existing purchase.
purchase_affiliate
refund A purchase was refunded — the seller refunded some money back to the traveler.
deposit The traveler paid a deposit amount to the seller for a purchase.
balance The seller collected the balance amount from a deposit (which was previously collected towards a purchase).
payout A payout was initiated from Xola to the seller's bank account. All payout transactions are reflected in the payouts report.
auto_payout An automatic payout was initiated from Xola to the seller's bank account. All payout transactions are reflected in the payouts report.
payout_adjust
affiliate Reflects collecting payment or crediting an affiliate with an amount for their bookings.
modify
subscription Xola charging the seller for their subscription fees. In this situation the seller's registered credit card would be charged.

List transactions

Retrieve a paginated list of transactions. Transactions track all movement of money in Xola, including customer payments, seller payouts, refunds, and adjustments.

Transactions are returned in descending order of creation date by default.

Supports comprehensive filtering by seller, type, amount, date ranges, payment methods, and more.

For export functionality, include a format parameter to receive a job ID for asynchronous processing. Cash flow exports include a TAGS column that may contain contextual labels. For stripe_paydown transactions, the TAGS field is automatically populated with "Stripe Debt Payment". For other transactions with an associated order or purchase, TAGS contains deposit indicators and any order/purchase tags.

ETL Mode: When etl=true is specified (admin only), the endpoint returns data optimized for extract-transform-load operations with higher limits and different sorting.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=60f7b3c4e4b0a1234567890a

Filter transactions by seller ID

type
Array of strings
Items Enum: "purchase" "purchase_affiliate" "refund" "refund_commission" "deposit" "balance" "payout" "affiliate" "modify" "subscription" "subscription_refund" "payout_adjust" "redeem" "gratuity" "partner_reconcile_auto" "partner_reconcile_manual" "partner_purchase" "stripe_paydown"
Example: type=purchase,refund

Filter by transaction type(s)

source
Array of strings
Items Enum: "xola" "admin" "checkout" "office" "partner" "affiliate_credit_top_up" "kiosk" "traveler" "refund" "import" "gift" "stripe" "gratuity"
Example: source=checkout,office

Filter by transaction source(s)

method
Array of strings (TransactionMethod)
Items Enum: "ACH" "Wire" "PayPal" "Check" "Cash" "Other" "Credit Card" "Electronic" "Voucher" "Affiliate Deposit" "Gift" "Store Credit" "Xola Pay" "Plugin" "Klarna" "Afterpay Clearpay" "Affirm" "Zip"
Example: method=Credit Card,PayPal

Filter by payment method(s)

affiliates
string
Example: affiliates=60f7b3c4e4b0a1234567890b

Filter by affiliate ID

partners
string
Example: partners=60f7b3c4e4b0a1234567890c

Filter by partner ID

payout
string
Example: payout=60f7b3c4e4b0a1234567890d

Filter by payout ID

order_id
string
Example: order_id=60f7b3c4e4b0a1234567890e

Filter by order ID

items_product
string
Example: items_product=60f7b3c4e4b0a1234567890f

Filter by product ID in transaction items

number or object
Example: balance=1000

Filter by balance amount. Supports exact match or range operators:

  • Direct value: balance=1000.00
  • Range: balance[gte]=500&balance[lte]=2000
number or object
Example: items_gross=150

Filter by gross amount in transaction items

number or object
Example: items_commission=15

Filter by commission amount in transaction items

number or object
Example: items_net=135

Filter by net amount in transaction items

object (DateTimeFilterSchema)
Examples: createdAt[summary]=Find records where field exists (not null)&createdAt[value]=[object Object] createdAt[summary]=Find records where field is null/missing&createdAt[value]=[object Object] createdAt[summary]=Date range filtering&createdAt[value]=[object Object] createdAt[summary]=Range using comma-separated string&createdAt[value]=[object Object] createdAt[summary]=Using period for today&createdAt[value]=[object Object] createdAt[summary]=Using period for last week&createdAt[value]=[object Object] createdAt[summary]=Exact date-time match&createdAt[value]=[object Object] createdAt[summary]=After specific date&createdAt[value]=[object Object]

Filter by creation timestamp. Supports date-time filtering operations.

object (DateTimeFilterSchema)
Examples: updatedAt[summary]=Find records where field exists (not null)&updatedAt[value]=[object Object] updatedAt[summary]=Find records where field is null/missing&updatedAt[value]=[object Object] updatedAt[summary]=Date range filtering&updatedAt[value]=[object Object] updatedAt[summary]=Range using comma-separated string&updatedAt[value]=[object Object] updatedAt[summary]=Using period for today&updatedAt[value]=[object Object] updatedAt[summary]=Using period for last week&updatedAt[value]=[object Object] updatedAt[summary]=Exact date-time match&updatedAt[value]=[object Object] updatedAt[summary]=After specific date&updatedAt[value]=[object Object]

Filter by last update timestamp. Supports date-time filtering operations.

object (DateTimeFilterSchema)
Examples: escrowedAt[summary]=Find records where field exists (not null)&escrowedAt[value]=[object Object] escrowedAt[summary]=Find records where field is null/missing&escrowedAt[value]=[object Object] escrowedAt[summary]=Date range filtering&escrowedAt[value]=[object Object] escrowedAt[summary]=Range using comma-separated string&escrowedAt[value]=[object Object] escrowedAt[summary]=Using period for today&escrowedAt[value]=[object Object] escrowedAt[summary]=Using period for last week&escrowedAt[value]=[object Object] escrowedAt[summary]=Exact date-time match&escrowedAt[value]=[object Object] escrowedAt[summary]=After specific date&escrowedAt[value]=[object Object]

Filter by escrow timestamp. Used for payment processing and transaction filtering.

object (DateTimeFilterSchema)
Examples: arrivalDateTime[summary]=Find records where field exists (not null)&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Find records where field is null/missing&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Date range filtering&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Range using comma-separated string&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Using period for today&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Using period for last week&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=Exact date-time match&arrivalDateTime[value]=[object Object] arrivalDateTime[summary]=After specific date&arrivalDateTime[value]=[object Object]

Filter by arrival date and time. Commonly used for booking and event filtering.

object (DateTimeFilterSchema)
Examples: summary=Find records where field exists (not null)&value=[object Object] summary=Find records where field is null/missing&value=[object Object] summary=Date range filtering&value=[object Object] summary=Range using comma-separated string&value=[object Object] summary=Using period for today&value=[object Object] summary=Using period for last week&value=[object Object] summary=Exact date-time match&value=[object Object] summary=After specific date&value=[object Object]

Filter by realization date/time from transaction items

remoteTransactions_cardSummary_brand
string
Example: remoteTransactions_cardSummary_brand=visa

Filter by credit card brand

stripeEvent_remoteSystem
string
Example: stripeEvent_remoteSystem=connect

Filter by Stripe remote system

remoteId
string
Example: remoteId=ch_1F0v3H4dlNciCrXqxiARO2o3

Filter by remote transaction ID

object
Example: exists[payout]=false&exists[gratuity]=true

Check for field existence

createdBy
string
Example: createdBy=60f7b3c4e4b0a1234567890g

Filter by creator user ID

context
string
Value: "report"

Special context for data retrieval:

  • report: Optimizes query for reporting by preloading related order/purchase data
etl
boolean
Default: false

Enable ETL mode for bulk data extraction (admin only)

format
string
Enum: "csv" "excel" "json"
Example: format=csv

Export format - returns a job ID for asynchronous processing

include
string
Example: include=id,amount,type,createdAt

Comma-separated list of fields to include in response

fields
string
Example: fields=id,amount,type,createdAt

Alias for 'include' parameter

exclude
string
Example: exclude=meta,remoteTransactions

Comma-separated list of fields to exclude from response

sort
string
Example: sort=createdAt,-amount

Sort order (comma-separated fields)

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "paging": {
    }
}

Create transaction

Create a new transaction. Only admin users with appropriate permissions can create transactions.

Supports creating various transaction types including:

  • Gratuity reconcile transactions
  • Plugin fee transactions
  • Balance reconcile transactions (super admin only)
  • Affiliate top-up transactions
  • Affiliate top-up refund transactions
  • General transactions (admin account managers only)

Transactions created via API are marked with source 'admin'.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
One of
amount
required
number <float>

Transaction amount

earning
number <float>

Seller earnings after commission

currency
required
string

Currency code (ISO 4217)

type
required
string
Enum: "purchase" "purchase_affiliate" "refund" "refund_commission" "deposit" "balance" "payout" "affiliate" "modify" "subscription" "subscription_refund" "payout_adjust" "redeem" "gratuity" "partner_reconcile_auto" "partner_reconcile_manual" "partner_purchase" "stripe_paydown"

Type of transaction

method
string (TransactionMethod)
Enum: "ACH" "Wire" "PayPal" "Check" "Cash" "Other" "Credit Card" "Electronic" "Voucher" "Affiliate Deposit" "Gift" "Store Credit" "Xola Pay" "Plugin" "Klarna" "Afterpay Clearpay" "Affirm" "Zip"

Payment method used for this transaction:

  • ACH: Automated Clearing House transfer
  • Wire: Wire transfer
  • PayPal: PayPal payment
  • Check: Physical check
  • Cash: Cash payment
  • Other: Other payment method
  • Credit Card: Credit/debit card
  • Electronic: Electronic payment
  • Voucher: Voucher/coupon
  • Affiliate Deposit: Affiliate account deposit
  • Gift: Gift card
  • Store Credit: Store credit
  • Xola Pay: Xola's payment system
  • Plugin: Third-party plugin payment
  • Klarna: Klarna buy now, pay later
  • Afterpay Clearpay: Afterpay Clearpay buy now, pay later
  • Affirm: Affirm buy now, pay later
  • Zip: Zip buy now, pay later
source
string
Enum: "xola" "admin" "checkout" "office" "partner" "affiliate_credit_top_up" "kiosk" "traveler" "refund" "import" "gift" "stripe" "gratuity"

Transaction source

comment
string

Additional comments

required
object (ObjectReference)

Seller reference

affiliates
Array of strings

Affiliate IDs (for affiliate transactions)

object

Additional metadata

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 150,
  • "earning": 142.5,
  • "currency": "USD",
  • "type": "purchase",
  • "method": "Credit Card",
  • "source": "checkout",
  • "comment": "Booking payment",
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890d",
  • "amount": 150,
  • "earning": 142.5,
  • "balance": 1393.25,
  • "currency": "USD",
  • "type": "purchase",
  • "source": "admin",
  • "method": "Credit Card",
  • "seller": {
    },
  • "createdAt": "2023-12-07T12:00:00Z",
  • "updatedAt": "2023-12-07T12:00:00Z"
}

Patch transactions

Apply batch operations to update transaction properties. Currently supports updating Stripe gateway fees.

Operations are processed individually, and the endpoint returns HTTP 207 (Multi-Status) if any operations fail. Successful operations are applied immediately, while failed operations are returned with error details.

Supported Operations:

  • setStripeChargeFee: Update the gateway fee for a Stripe charge transaction
  • setStripeRefundFee: Update the gateway fee for a Stripe refund transaction

Required Permission: ROLE_ADMIN_GATEWAY_FEES

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
Array
op
required
string
Enum: "setStripeChargeFee" "setStripeRefundFee"

Operation to perform:

  • setStripeChargeFee: Set the Stripe charge fee for a transaction
  • setStripeRefundFee: Set the Stripe refund fee for a transaction
value
required
number <float>

Fee amount to set (negative for refunds)

required
object

Filter criteria to identify which transactions to update

Responses

Request samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get transaction by ID

Retrieve a single transaction by its ID. The response includes the complete transaction details with all available fields.

Authorization rules are applied to ensure users can only access transactions they have permission to view.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 60f7b3c4e4b0a1234567890a

Transaction ID

Responses

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "amount": 150,
  • "earning": 142.5,
  • "balance": 1250.75,
  • "currency": "USD",
  • "type": "purchase",
  • "source": "checkout",
  • "method": "Credit Card",
  • "comment": null,
  • "coupon": "SAVE10",
  • "seller": {
    },
  • "order": {
    },
  • "purchase": {
    },
  • "affiliates": [ ],
  • "partners": [ ],
  • "items": [
    ],
  • "remoteTransactions": [
    ],
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T10:30:00Z",
  • "createdBy": {
    }
}

Get transaction summary

Retrieve aggregated transaction summary data calculated through database aggregation.

Provides totals, averages, and breakdowns by transaction type and payment method. Supports the same filtering parameters as the transaction list endpoint.

Authorization rules are applied to ensure users can only access summary data for transactions they have permission to view.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=60f7b3c4e4b0a1234567890a

Filter summary by seller ID

type
Array of strings
Items Enum: "purchase" "purchase_affiliate" "refund" "refund_commission" "deposit" "balance" "payout" "affiliate" "modify" "subscription" "subscription_refund" "payout_adjust" "redeem" "gratuity" "partner_reconcile_auto" "partner_reconcile_manual" "partner_purchase" "stripe_paydown"

Filter by transaction type(s)

source
Array of strings
Items Enum: "xola" "admin" "checkout" "office" "partner" "affiliate_credit_top_up" "kiosk" "traveler" "refund" "import" "gift" "stripe" "gratuity"

Filter by transaction source(s)

object (DateTimeFilterSchema)
Examples: createdAt[summary]=Find records where field exists (not null)&createdAt[value]=[object Object] createdAt[summary]=Find records where field is null/missing&createdAt[value]=[object Object] createdAt[summary]=Date range filtering&createdAt[value]=[object Object] createdAt[summary]=Range using comma-separated string&createdAt[value]=[object Object] createdAt[summary]=Using period for today&createdAt[value]=[object Object] createdAt[summary]=Using period for last week&createdAt[value]=[object Object] createdAt[summary]=Exact date-time match&createdAt[value]=[object Object] createdAt[summary]=After specific date&createdAt[value]=[object Object]

Filter by creation timestamp. Supports date-time filtering operations.

method
Array of strings

Filter by payment method(s)

Responses

Response samples

Content type
application/json
{
  • "totalAmount": 15750,
  • "totalEarnings": 14962.5,
  • "transactionCount": 125,
  • "averageAmount": 126,
  • "byType": {
    },
  • "byMethod": {
    }
}

users

A user on Xola can represent any one of three entities:

  • Seller: The primary owner of a business account. Most objects will contain a seller property indicating its owner.
  • Delegate: A user authorized to access a Seller account (e.g. reservationist, curator, etc.).
  • Traveler: A user account that gets created automatically whenever a booking is placed. This type of user will not have a password.

Import travelers from CSV

When a multipart/form-data request is sent with a file field containing a CSV, this endpoint enqueues a traveler import job instead of creating a single user account.

The CSV file is processed asynchronously. A job response is returned immediately with a job ID that can be polled via GET /jobs/{id} to track progress.

Authorization

  • Requires ROLE_IMPORT permission. Returns 403 Forbidden without it.

CSV Format Requirements

Required columns:

  • name - Full name of the traveler

Optional columns:

  • email - Email address (used for duplicate detection)
  • phone - Phone number
  • marketingconsent - Marketing consent value
  • notes, note1, note2, etc. - Notes attached to the traveler (any column matching note(s)?(\d+)?)

Any additional columns not matching the above are stored as custom data fields on the traveler.

Duplicate Detection

If a traveler with the same email already exists for the seller, that row is skipped and counted as a failure with the reason "skipped: already exists".

Form Data Fields

  • file - The CSV file to import (required)
  • seller - The seller ID to import travelers for (required)
Authorizations:
apiKeybasicAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

CSV file containing traveler data to import

seller
required
string (id) ^[0-9a-fA-F]{24}$

Seller ID to import travelers for

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List users

Retrieve a paginated list of users. When a seller parameter is provided, only travelers (customers) for that seller are returned and additional traveler-specific filter parameters become available.

Traveler Filtering

When querying with seller (which implies type=traveler), the following filter parameters are supported: name, email, phone, lifetimeValue, createdAt, updated, tags._id, marketingConsents.value, and isOrganizer.

Export Mode

When a format parameter is included (e.g., format=xlsx), the endpoint triggers an asynchronous export job and returns a 202 Accepted response with a job object. Poll the /jobs/{id} endpoint to track progress. The export includes these columns by default: ID, NAME, IS_ORGANIZER, EMAIL, OTHER_EMAILS, OTHER_NAMES, PHONE, OTHER_PHONES, VALUE, REFERRAL_SOURCE, CREATED, UPDATED, TAGS, plus any marketing consent columns.

Use filters[excludedColumns] to omit specific columns from the export output. Valid values include: id, name, isOrganizer, email, additionalEmails, additionalNames, phone, additionalPhones, lifetimeValue, data.howDidYouHearAboutUs, createdAt, updated, tags._id, marketingConsents.

Authorization

  • A seller parameter is required unless the caller has admin privileges.
  • The authenticated user must have VIEW_USER_CUSTOMERS permission on the seller.
Authorizations:
apiKeybasicAuth
query Parameters
seller
string (id) ^[0-9a-fA-F]{24}$
Example: seller=507f1f77bcf86cd799439012

Seller ID. Required for non-admin callers. When provided, only travelers (type=2) belonging to this seller are returned and traveler-specific filters become available.

type
integer
Enum: 1 2 3
Example: type=2

User type filter. Automatically set to 2 (traveler) when seller is provided.

  • 1 = Seller
  • 2 = Traveler/Customer
  • 3 = Delegate
search
string
Example: search=john@example.com

Free-text search across name, email, and phone fields. If a 24-character hex string is provided, it is treated as an ID lookup.

name
string
Example: name=John

Filter travelers by name (string filter). Only available when seller is provided.

email
string <email>
Example: email=john@example.com

Filter travelers by email address (case-insensitive, trimmed). Only available when seller is provided.

phone
string
Example: phone=+1-555-0123

Filter travelers by phone number (string filter). Only available when seller is provided.

object

Filter travelers by lifetime value (numeric filter). Supports operators like gte, lte, gt, lt, equals. Only available when seller is provided.

object (DateTimeFilterSchema)
Examples: createdAt[summary]=Find records where field exists (not null)&createdAt[value]=[object Object] createdAt[summary]=Find records where field is null/missing&createdAt[value]=[object Object] createdAt[summary]=Date range filtering&createdAt[value]=[object Object] createdAt[summary]=Range using comma-separated string&createdAt[value]=[object Object] createdAt[summary]=Using period for today&createdAt[value]=[object Object] createdAt[summary]=Using period for last week&createdAt[value]=[object Object] createdAt[summary]=Exact date-time match&createdAt[value]=[object Object] createdAt[summary]=After specific date&createdAt[value]=[object Object]

Filter travelers by creation date. Supports date-time filtering operations. Only available when seller is provided.

object (DateTimeFilterSchema)
Examples: updated[summary]=Find records where field exists (not null)&updated[value]=[object Object] updated[summary]=Find records where field is null/missing&updated[value]=[object Object] updated[summary]=Date range filtering&updated[value]=[object Object] updated[summary]=Range using comma-separated string&updated[value]=[object Object] updated[summary]=Using period for today&updated[value]=[object Object] updated[summary]=Using period for last week&updated[value]=[object Object] updated[summary]=Exact date-time match&updated[value]=[object Object] updated[summary]=After specific date&updated[value]=[object Object]

Filter travelers by last updated timestamp. Supports date-time filtering operations. Only available when seller is provided.

tags._id
string
Example: tags._id=VIP

Filter travelers by tag ID (string filter). Only available when seller is provided.

marketingConsents.value
string
Example: marketingConsents.value=true

Filter travelers by marketing consent value (string filter). Only available when seller is provided.

isOrganizer
boolean
Example: isOrganizer=true

Filter travelers by whether they are an organizer (boolean filter). Only available when seller is provided.

format
string
Value: "xlsx"
Example: format=xlsx

Export format. When provided, triggers an asynchronous export job and returns a 202 response with job details instead of the user list.

filters[excludedColumns]
string
Example: filters[excludedColumns]=additionalEmails,additionalPhones,marketingConsents

Comma-separated list of columns to exclude from the export output. Only applicable when format is specified. Valid column identifiers: id, name, isOrganizer, email, additionalEmails, additionalNames, phone, additionalPhones, lifetimeValue, data.howDidYouHearAboutUs, createdAt, updated, tags._id, marketingConsents.

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next": "https://xola.com/api/users?seller=507f1f77bcf86cd799439012&skip=20&limit=20"
}

Get current authenticated user

Returns the full user profile for the currently authenticated user, including id, email, apiKey, name, roles, and preferences.

Uses the authentication headers (X-API-KEY or Authorization) to identify the user.

Authorizations:
apiKeybasicAuth

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "John Smith",
  • "email": "john.smith@example.com",
  • "username": "john.smith@example.com",
  • "apiKey": "xola_test_1234567890abcdef",
  • "roles": [
    ],
  • "type": 1,
  • "enabled": true
}

Get current user's API key

Returns the API key for the authenticated user. This endpoint is for the current user only.

If the user doesn't have an API key, one will be generated automatically. The API key can be reset by providing the reset=true query parameter.

Authorizations:
apiKeybasicAuth
query Parameters
reset
boolean
Default: false
Example: reset=true

Whether to reset/regenerate the API key

Responses

Response samples

Content type
application/json
[
  • "my_api_key_1234567890abcdef"
]

Get user details

Returns details about a specific user account.

Private Access: With the private=true parameter, private data is returned based on authorization level. The seller parameter is required when requesting private data.

Authorization Rules for Private Data:

  1. User must be authenticated
  2. User must be a seller or have seller permissions
  3. Seller must be authorized to view customer data
  4. Data returned is filtered based on user's authorization level
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
private
boolean
Default: false
Example: private=true

Whether to return private user data (requires authentication and seller parameter)

seller
string (id) ^[0-9a-fA-F]{24}$
Example: seller=507f1f77bcf86cd799439012

Seller ID (required when private=true, used for authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "John Smith",
  • "email": "john.smith@example.com",
  • "phone": "+1-555-0123",
  • "username": "john.smith@example.com",
  • "type": 2,
  • "enabled": true,
  • "lastLogin": "2024-01-15T10:30:00Z",
  • "remoteCards": [
    ]
}

Accept Xola Terms of Service for a user

Records that a user has accepted the Xola Terms of Service for a specific version.

The acceptance is recorded with the IP address from which the request was made and the timestamp of acceptance.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
version
required
string^\d{4}\.\d{2}\.\d{2}$

Version identifier of the Terms of Service being accepted (YYYY.MM.DD format)

Responses

Request samples

Content type
application/json
{
  • "version": "2024.01.15"
}

Response samples

Content type
application/json
""

Resend confirmation email

Resends the email confirmation message to a user who has not yet activated their account.

This endpoint can only be used for users whose accounts are not yet enabled (activated). If the user's account is already enabled, a validation error will be returned.

A new confirmation token is generated and the confirmation email is sent to the user's registered email address.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
""

Get user profile picture

Returns the user's profile picture. If the user has uploaded a custom picture, that is returned. Otherwise, the response will redirect to their Gravatar image, or fall back to an initials-based image if no Gravatar exists.

The response is always a redirect (HTTP 302) to the actual image URL, which may be hosted on external services like Gravatar or Xola's media servers.

Image Sizing

You can control the size of the returned image using query parameters:

  • Use size parameter for predefined sizes
  • Use width and height parameters for custom dimensions
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
size
string
Default: "small_square"
Enum: "small" "medium" "large" "small_square" "medium_square" "large_square" "logo" "email"
Example: size=small_square

Predefined image size

width
integer [ 1 .. 2000 ]
Example: width=150

Custom image width in pixels (used with height parameter)

height
integer [ 1 .. 2000 ]
Example: height=150

Custom image height in pixels (used with width parameter)

rounded
boolean
Default: true
Example: rounded=true

Whether to return a rounded/circular image

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Get user's short code

Returns the user's unique short code. If the user doesn't have a short code yet, one will be generated automatically.

Short codes are 5-character unique identifiers that can be used for quick user identification or referencing.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "shortCode": "AB1C2"
}

Update user information

Updates user information including personal details, contact information, and preferences.

Context Handling:

  • When id is "me" or matches the authenticated user's ID, the user updates their own profile
  • When updating other users, proper authorization is required (seller permissions or delegate access)

Authorization Rules:

  • Users can update their own profiles
  • Sellers can update their traveler's profiles
  • Delegates with proper permissions can update profiles on behalf of sellers
  • Admin users have broader update permissions

Special Features:

  • Email changes trigger updates across all related orders, purchases, and gifts
  • Phone changes update associated bookings for the specific seller context
  • Supports user merging via the mergedTo field
  • Can create and associate payment cards when card data is provided

Validation:

  • Email uniqueness is enforced per seller context (bypassed during merge)
  • Name and email changes propagate to all related records
  • Phone changes are seller-scoped

Merge Behavior: When mergedTo is provided, the following validation rules are bypassed:

  • Email format validation is not enforced
  • Duplicate email checks are skipped
  • All other field-level validation (e.g., traveler_lite_creation group) is skipped

The source user's data is merged into the target user, the source user is removed, and email notifications can be controlled via _emailOverrides.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
string or null

User's full name

email
string or null <email>

User's email address (must be unique within seller context)

newEmail
string or null <email>

New email address when current user is changing their own email

phone
string or null

User's phone number (updates are seller-scoped)

username
string or null

User's username (typically same as email)

locale
string or null
Enum: "en-US" "es-ES" "fr-FR" "de-DE" "it-IT" "pt-BR"

User's preferred locale/language

timezone
string or null

User's timezone

object (ObjectReference)

Reference to the seller context (for traveler updates)

object

Target user to merge this user account into. When this field is provided, all field-level validation (including email format and duplicate email checks) is bypassed. The source user's data is merged into the target user account, and the source user is subsequently removed.

data
object or null

Custom data fields and preferences

object or null

Payment card to associate with user

object or null

Email sending overrides for specific operations

Responses

Request samples

Content type
application/json
Example
{
  • "name": "John Doe Smith",
  • "email": "john.smith.updated@example.com",
  • "phone": "+1-555-0199"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "name": "John Doe Smith",
  • "email": "john.smith.updated@example.com",
  • "phone": "+1-555-0199",
  • "username": "john.smith@example.com",
  • "type": 2,
  • "enabled": true,
  • "lastLogin": "2024-01-15T10:30:00Z",
  • "tags": [
    ]
}

Get sellers current user is delegated to

Returns a paginated list of seller accounts that the authenticated user has delegate access to.

This endpoint provides information about all the seller accounts the current user can act on behalf of, including the seller's name, company information, and basic profile details.

Pagination

  • limit - Number of results to return per page. Capped at 500. Defaults to the server's configured page size.
  • skip - Number of results to skip. Must be >= 0. Defaults to 0.

The response includes a paging object with a next field containing the URL for the next page, or null when there are no more results.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 500 ]
Default: 20

Number of items to return per page. Maximum value is 500.

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {}
}

Get all feature flags for a user

Returns all feature flags configured for a specific user account.

Feature flags control access to various features and capabilities within the system. This endpoint requires VIEW_USER_FEATURES permission on the target user.

Authorization:

  • Requires VIEW_USER_FEATURES permission
  • Users can view their own features
  • Admins and authorized sellers can view user features
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "googleAnalytics": true,
  • "advancedReporting": false,
  • "mobileApp": true,
  • "customBranding": true
}

Get the value of a specific feature flag

Returns the value of a specific feature flag for a user.

Public Features: Some features are publicly accessible without authentication:

  • googleAnalytics

Authorization:

  • Public features: No authentication required
  • Private features: Requires VIEW_USER_FEATURES permission
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

feature
required
string
Example: googleAnalytics

The name/key of the feature flag to retrieve

Responses

Response samples

Content type
application/json
Example
true

waivers

Digital waiver management

List waivers

Fetch a list of waivers. By default, only returns waivers that are not linked to any purchases.

If the seller has multi-link day interval configured, waivers created within that interval are included regardless of their link status.

Authorizations:
apiKeybasicAuth
query Parameters
seller
string
Example: seller=507f1f77bcf86cd799439011

Seller ID to fetch waivers for. If not provided, uses the authenticated user's account.

unlinked
boolean
Default: true

Filter for unlinked waivers. When true (default), returns only waivers that are linkable.

traveler
string
Example: traveler=507f1f77bcf86cd799439012

Filter waivers by participant traveler ID. Returns waivers where any participant is linked to the specified traveler.

search
string
Example: search=john doe

Search term to filter waivers. Searches across participant name, email, and phone.

expand
string
Value: "purchase"

You can expand multiple objects at the same time by providing a comma-separated list of values

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

sort
string
Default: "-id"
Enum: "id" "-id" "createdAt" "-createdAt" "signedAt" "-signedAt"
Example: sort=-createdAt

Sort field and direction. Use minus (-) prefix for descending order. IMPORTANT: Specifying a sort order may impact performance.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create waiver

Endpoint for processing waiver completion from external waiver systems.

This endpoint is typically called by waiver plugins when a customer completes signing a waiver. The waiver will be automatically linked to purchases if participants contact info can be matched.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
remoteId
required
string

ID of the waiver on the remote system

remoteSystem
required
string

ID of the remote system (waiver plugin user ID)

customerEmail
required
string <email>

Email address of the person who signed the waiver

url
required
string <uri>

URL to view the signed waiver

waiverTypeId
string or null

ID of the waiver form template (not the filled waiver, but the blank template)

signedAt
required
string <date-time>

Date when the waiver was signed on the remote system

tags
Array of strings

String array of tags associated with the waiver

Array of objects (WaiverParticipant)

Information on waiver participants

itemId
string or null

Purchase Item ID if sent in waiver payload

required
object (ObjectReference)

Seller account tied to this waiver

Responses

Request samples

Content type
application/json
{
  • "remoteId": "123e4567-e89b-12d3-a456-426614174000",
  • "remoteSystem": "507f1f77bcf86cd799439011",
  • "customerEmail": "customer@example.com",
  • "url": "https://waiver-system.com/waivers/123e4567-e89b-12d3-a456-426614174000",
  • "waiverTypeId": "waiver-template-123",
  • "signedAt": "2024-03-15T14:30:00Z",
  • "tags": [
    ],
  • "participants": [
    ],
  • "itemId": "507f1f77bcf86cd799439012",
  • "seller": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439013",
  • "remoteId": "123e4567-e89b-12d3-a456-426614174000",
  • "remoteSystem": "507f1f77bcf86cd799439011",
  • "customerEmail": "customer@example.com",
  • "url": "https://waiver-system.com/waivers/123e4567-e89b-12d3-a456-426614174000",
  • "waiverTypeId": "waiver-template-123",
  • "signedAt": "2024-03-15T14:30:00Z",
  • "tags": [
    ],
  • "participants": [
    ],
  • "itemId": "507f1f77bcf86cd799439012",
  • "seller": {
    },
  • "experiences": [
    ],
  • "purchases": [
    ],
  • "createdAt": "2024-03-15T14:35:00Z",
  • "updatedAt": "2024-03-15T16:20:00Z"
}

Get waiver details

Fetch details for an individual waiver

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439013",
  • "remoteId": "123e4567-e89b-12d3-a456-426614174000",
  • "remoteSystem": "507f1f77bcf86cd799439011",
  • "customerEmail": "customer@example.com",
  • "url": "https://waiver-system.com/waivers/123e4567-e89b-12d3-a456-426614174000",
  • "waiverTypeId": "waiver-template-123",
  • "signedAt": "2024-03-15T14:30:00Z",
  • "tags": [
    ],
  • "participants": [
    ],
  • "itemId": "507f1f77bcf86cd799439012",
  • "seller": {
    },
  • "experiences": [
    ],
  • "purchases": [
    ],
  • "createdAt": "2024-03-15T14:35:00Z",
  • "updatedAt": "2024-03-15T16:20:00Z"
}

Update waiver links

This endpoint supports linking waivers to purchases. You can link to specific items within a purchase, or link to all items if no specific item is provided.

Use the force query parameter to override existing links when multi-link is not configured.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
force
boolean
Default: false

Force the update even if waiver is already linked (when multi-link is not configured)

Request Body schema: application/json
required
purchase
string or null

Purchase ID to link/unlink. Set to null to unlink from all purchases.

item
string or null

Specific item ID within the purchase to link/unlink

object

Guest to link

object

Participant information for linking

remove
boolean
Default: false

Set to true to unlink the waiver

Responses

Request samples

Content type
application/json
{
  • "purchase": "507f1f77bcf86cd799439015",
  • "item": "507f1f77bcf86cd799439016",
  • "guest": {
    },
  • "participant": {
    },
  • "remove": false
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439013",
  • "remoteId": "123e4567-e89b-12d3-a456-426614174000",
  • "remoteSystem": "507f1f77bcf86cd799439011",
  • "customerEmail": "customer@example.com",
  • "url": "https://waiver-system.com/waivers/123e4567-e89b-12d3-a456-426614174000",
  • "waiverTypeId": "waiver-template-123",
  • "signedAt": "2024-03-15T14:30:00Z",
  • "tags": [
    ],
  • "participants": [
    ],
  • "itemId": "507f1f77bcf86cd799439012",
  • "seller": {
    },
  • "experiences": [
    ],
  • "purchases": [
    ],
  • "createdAt": "2024-03-15T14:35:00Z",
  • "updatedAt": "2024-03-15T16:20:00Z"
}

Update waiver participants

Update only the participant information for a waiver. This endpoint allows updating participant details like name, email, date of birth, and form responses without affecting the waiver's link status.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
required
Array of objects (WaiverParticipantUpdate)

Array of participant updates

Responses

Request samples

Content type
application/json
{
  • "participants": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439013",
  • "remoteId": "123e4567-e89b-12d3-a456-426614174000",
  • "remoteSystem": "507f1f77bcf86cd799439011",
  • "customerEmail": "customer@example.com",
  • "url": "https://waiver-system.com/waivers/123e4567-e89b-12d3-a456-426614174000",
  • "waiverTypeId": "waiver-template-123",
  • "signedAt": "2024-03-15T14:30:00Z",
  • "tags": [
    ],
  • "participants": [
    ],
  • "itemId": "507f1f77bcf86cd799439012",
  • "seller": {
    },
  • "experiences": [
    ],
  • "purchases": [
    ],
  • "createdAt": "2024-03-15T14:35:00Z",
  • "updatedAt": "2024-03-15T16:20:00Z"
}

Get signed waiver PDF

Returns the signed PDF document of the waiver by proxying the request to the external waiver system.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get waiver templates

Returns available waiver templates from configured waiver plugins.

Templates represent the blank waiver forms that can be used to create new waivers. This endpoint is used to discover available waiver types for a seller.

Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string
Example: seller=507f1f77bcf86cd799439011

Seller ID to fetch templates for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

wares

Merchandise and ware management

List wares

Retrieve a paginated list of merchandise items (wares) for a seller.

Authorizations:
apiKeybasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

seller
required
string
Example: seller=507f1f77bcf86cd799439020

Filter by seller ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create ware

Create a new merchandise item (ware) for the authenticated seller account.

Required Fields

  • Name and seller are required

Automatic Behavior

  • Creates audit trail entry for the creation
Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the merchandise item

desc
string

Full description of the merchandise item

excerpt
string <= 500 characters

Short description or summary

type
string
Enum: "physical" "digital"

Type of merchandise

object

Terms and conditions for this ware

allowedSources
Array of strings

List of allowed sources for purchasing this ware

required
object (ObjectReference)

Reference to the seller

object (WarePreference)

Ware-specific preferences and policies

object

Down deposit configuration

object (ObjectReference)

Reference to the photo media object

Responses

Request samples

Content type
application/json
{
  • "name": "Adventure T-Shirt",
  • "seller": {
    },
  • "desc": "High-quality cotton t-shirt featuring our adventure logo",
  • "excerpt": "Adventure-themed cotton t-shirt",
  • "type": "physical",
  • "allowedSources": [
    ],
  • "warePreference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "ware",
  • "name": "Adventure T-Shirt",
  • "desc": "High-quality cotton t-shirt featuring our adventure logo",
  • "type": "physical",
  • "seller": {
    },
  • "warePreference": {
    },
  • "createdAt": "2023-08-15T10:30:00Z",
  • "updatedAt": "2023-08-15T10:30:00Z"
}

Get ware

Retrieve detailed information about a specific merchandise item (ware).

Context-Dependent Fields

Some fields are only returned when the caller has seller/edit permissions (EDIT_WARE):

  • attachments: Documents and other attachments. Omitted from public responses.

When accessed without authentication or without EDIT_WARE permission, the response uses the public context and these fields are stripped.

Expansion Options

Use the expand parameter to include related data in a single request.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

query Parameters
expand
string

Comma-separated list of fields to expand

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "ware",
  • "name": "Adventure T-Shirt",
  • "desc": "High-quality cotton t-shirt featuring our adventure logo",
  • "excerpt": "Adventure-themed cotton t-shirt",
  • "type": "physical",
  • "allowedSources": [
    ],
  • "seller": {
    },
  • "photo": null,
  • "medias": [ ],
  • "attachments": [ ],
  • "warePreference": {
    },
  • "downDeposit": null,
  • "catalog": [ ],
  • "createdAt": "2023-08-15T10:30:00Z",
  • "updatedAt": "2023-08-16T14:20:00Z",
  • "deletedAt": null
}

Update ware

Update an existing merchandise item (ware). Only the provided fields will be updated; other fields remain unchanged.

Authorization

  • Must be the owner of the ware or have admin privileges
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the merchandise item

desc
string

Full description of the merchandise item

excerpt
string <= 500 characters

Short description or summary

type
string
Enum: "physical" "digital"

Type of merchandise

object

Terms and conditions for this ware

allowedSources
Array of strings

List of allowed sources for purchasing this ware

required
object (ObjectReference)

Reference to the seller

object (WarePreference)

Ware-specific preferences and policies

object

Down deposit configuration

object (ObjectReference)

Reference to the photo media object

Responses

Request samples

Content type
application/json
{
  • "name": "Adventure T-Shirt v2",
  • "seller": {
    },
  • "desc": "Updated high-quality cotton t-shirt with new adventure logo",
  • "warePreference": {
    }
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "object": "ware",
  • "name": "Adventure T-Shirt",
  • "desc": "High-quality cotton t-shirt featuring our adventure logo",
  • "excerpt": "Adventure-themed cotton t-shirt",
  • "type": "physical",
  • "terms": {
    },
  • "allowedSources": [
    ],
  • "seller": {
    },
  • "photo": {
    },
  • "medias": [
    ],
  • "attachments": [
    ],
  • "warePreference": {
    },
  • "downDeposit": {
    },
  • "status": "draft",
  • "catalog": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z"
}

Delete ware

Delete a merchandise item (ware). This is a soft delete operation.

Important Notes

  • Existing purchases are NOT affected by deletion
  • Ware becomes unavailable for new purchases
  • Historical data and reports remain intact

Authorization

  • Must be the owner of the ware or have admin privileges
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload a photo for a ware

Upload a photo/media for a merchandise item. The image file should be sent as the raw request body with appropriate Content-Type header.

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Get a ware photo

Retrieve a ware photo. Returns a redirect to the CDN URL. Pass 'default' as media to get the primary photo.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string

Media ID or 'default' for primary photo

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update media caption

Update the caption for a ware media item.

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string

Media ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Delete a ware media

Delete a media item (photo) from a ware.

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

media
required
string

Media ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Upload an attachment for a ware

Upload a PDF attachment for a merchandise item.

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Update an attachment

Update attachment metadata (title, caption).

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

attachmentId
required
string

Attachment ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Delete an attachment

Delete an attachment from a ware.

Authorization: Requires EDIT_WARE permission.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Resource ID

attachmentId
required
string

Attachment ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Bulk update inventory lots

Perform bulk operations on one or more inventory lots. Each operation carries a client-supplied id (echoed back in the matching result), an op type, and a data object.

Supported operations:

  • increment: Adjust count or unavailable by a signed, non-zero delta value
  • permanent_removal: Permanently remove physically destroyed units (value must be positive)

Use the top-level errorStrategy to control behavior when an operation fails: stop_on_failure (remaining operations are skipped) or continue_on_failure (default).

Authorization: Requires seller-level access to the inventory lot's seller.

Authorizations:
apiKeybasicAuth
Request Body schema: application/json
required
required
Array of objects (WareInventoryLotOperation) non-empty

List of inventory lot operations to perform

errorStrategy
string
Default: "continue_on_failure"
Enum: "stop_on_failure" "continue_on_failure"

How to handle a failed operation:

  • stop_on_failure: stop processing; remaining operations are marked skipped
  • continue_on_failure: continue processing the remaining operations (default)

Responses

Request samples

Content type
application/json
Example
{
  • "ops": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Get a ware inventory lot

Retrieve a specific WareInventoryLot by its ID.

A WareInventoryLot represents a batch (lot) of stock within a WareInventory. It tracks all quantity counters for that batch including available stock, reserved units, fulfilled units, and audit counters for returns and cancellations.

Counter relationships:

  • available = count - unavailable - reserved
  • reserved = purchased - returned - canceled
  • onHand = count - unavailable
Authorizations:
apiKeybasicAuth
path Parameters
id
required
string^[0-9a-fA-F]{24}$
Example: 507f1f77bcf86cd799439030

Inventory lot ID

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439030",
  • "count": 100,
  • "available": 42,
  • "onHand": 95,
  • "reserved": 53,
  • "pendingFulfillment": 53,
  • "fulfilled": 0,
  • "returned": 0,
  • "canceled": 0,
  • "unavailable": 5,
  • "purchased": 53,
  • "inventory": {
    },
  • "seller": {
    },
  • "unit": {
    },
  • "createdAt": "2026-01-15T10:30:00Z"
}

waitlists

A waitlist captures a customer's request for a slot on an experience that is currently unavailable — full, blacked out, or limited by a per-slot cap. A waitlist holds a single experience item together with the customer's requested arrival date and time (or time range).

Waitlists contain the full purchase payload and have the waitlist status. When a slot opens and the request is fulfilled, the waitlist is converted into a regular purchase, at which point its purchase reference and convertedAt timestamp are populated.

The waitlist feature is enabled or disabled per experience through its waitlist preference see POST/PUT /experiences/{id}/waitlist. The preference controls where the waitlist is offered — including whether it applies to max-capacity (capped) events via the enabledForCappedEvents flag — so a seller can turn waitlisting on or off for capped events independently of the other checkout surfaces.

List waitlists

Retrieve a paginated list of waitlists. The seller query parameter is required.

When a search term is provided together with seller, results are served from Elasticsearch; otherwise they are read directly from the database.

Authorizations:
apiKeybasicAuth
query Parameters
seller
required
string
Example: seller=507f1f77bcf86cd799439011

Seller ID to list waitlists for. Required.

type
string
Enum: "waitlist_purchase" "waitlist"

Waitlist type to filter by. Defaults to waitlist_purchase when a seller is provided, otherwise waitlist.

search
string
Example: search=john@example.com

Search term matched against customer name, email, phone, and other waitlist fields. Triggers Elasticsearch-backed search when combined with seller.

arrivalTimeRange.startTime
string

Filter waitlists by arrival time range start (time-based filter).

arrivalTimeRange.endTime
string

Filter waitlists by arrival time range end (time-based filter).

limit
integer [ 1 .. 100 ]
Default: 20

Number of items to return (max 100)

skip
integer >= 0
Default: 0

Number of items to skip

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paging": {
    }
}

Create a waitlist

Create a waitlist for an experience. A waitlist accepts exactly one item referencing an experience and the requested arrival date/time.

The following rules are enforced:

  • Multi-item waitlists are rejected (multi_item_waitlists_not_supported).
  • The item must reference an experience via experience or product (product_required); the experience must exist (invalid_experience).
  • When the experience has a per-slot waitlist limit enabled, an arrivalTimeRange cannot be supplied (waitlist_limit_enabled) and the request is rejected if the limit for the requested slot has been reached (waitlist_limit_reached).
  • When source is checkout, the requested slot is validated against the experience's maximum capacity and blackout schedules.
Authorizations:
apiKeybasicAuth
query Parameters
dryRun
boolean
Default: false

When true, validates and simulates waitlist creation without persisting it. A dry-run request returns 200 instead of 201.

Request Body schema: application/json
required
customerName
string

Name of the customer joining the waitlist

customerEmail
string <email>

Email address of the customer. If omitted, the top-level email field is used as the customer email when present.

email
string <email>

Fallback customer email, used when customerEmail is not provided.

phone
string or null

Customer's phone number

object (ObjectReference)

Seller the waitlist belongs to

source
string

Source where the waitlist originated. When set to checkout, the requested slot is additionally validated against the experience's maximum capacity and blackout schedules.

required
Array of objects (WaitlistItemRequest) = 1 items

The single item being waitlisted. Must reference an experience (through experience or product) and include the requested arrivalDate.

object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "seller": {
    },
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "waitlist_purchase",
  • "status": "waitlist",
  • "internalStatus": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerLocale": "en-US",
  • "customerTimezoneName": "America/New_York",
  • "phone": "+1234567890",
  • "phoneCanonical": "1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "amounts": {
    },
  • "balances": {
    },
  • "balance": 0,
  • "payNow": 50,
  • "dueNow": 50,
  • "minimumDue": 25,
  • "affiliatePayment": 15,
  • "referenceId": "EXT-BOOKING-123",
  • "source": "website",
  • "seller": {
    },
  • "organizer": {
    },
  • "partnerSeller": {
    },
  • "partner": {
    },
  • "affiliate": {
    },
  • "conversation": {
    },
  • "waitlist": {
    },
  • "travelers": [
    ],
  • "items": [
    ],
  • "lineItems": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "reminders": [
    ],
  • "paymentReminders": [
    ],
  • "splitPayment": {
    },
  • "trackingData": {
    },
  • "telemetry": {
    },
  • "meta": { },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "requiresCaptcha": false,
  • "termsAgreedAt": "2023-12-07T10:25:00Z",
  • "releaseHoldAt": "2023-12-07T12:00:00Z",
  • "notifyAt": "2023-12-07T09:00:00Z",
  • "migratedAt": "2023-12-07T08:00:00Z",
  • "commissionRefundProcessedAt": "2023-12-07T16:00:00Z",
  • "purchase": {
    },
  • "convertedAt": "2024-12-15T10:00:00Z",
  • "deletedAt": "2024-12-16T10:00:00Z"
}

Get a waitlist

Retrieve a single waitlist by its ID.

Requires the VIEW_PURCHASE permission on the waitlist.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

Responses

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "waitlist_purchase",
  • "status": "waitlist",
  • "internalStatus": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerLocale": "en-US",
  • "customerTimezoneName": "America/New_York",
  • "phone": "+1234567890",
  • "phoneCanonical": "1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "amounts": {
    },
  • "balances": {
    },
  • "balance": 0,
  • "payNow": 50,
  • "dueNow": 50,
  • "minimumDue": 25,
  • "affiliatePayment": 15,
  • "referenceId": "EXT-BOOKING-123",
  • "source": "website",
  • "seller": {
    },
  • "organizer": {
    },
  • "partnerSeller": {
    },
  • "partner": {
    },
  • "affiliate": {
    },
  • "conversation": {
    },
  • "waitlist": {
    },
  • "travelers": [
    ],
  • "items": [
    ],
  • "lineItems": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "reminders": [
    ],
  • "paymentReminders": [
    ],
  • "splitPayment": {
    },
  • "trackingData": {
    },
  • "telemetry": {
    },
  • "meta": { },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "requiresCaptcha": false,
  • "termsAgreedAt": "2023-12-07T10:25:00Z",
  • "releaseHoldAt": "2023-12-07T12:00:00Z",
  • "notifyAt": "2023-12-07T09:00:00Z",
  • "migratedAt": "2023-12-07T08:00:00Z",
  • "commissionRefundProcessedAt": "2023-12-07T16:00:00Z",
  • "purchase": {
    },
  • "convertedAt": "2024-12-15T10:00:00Z",
  • "deletedAt": "2024-12-16T10:00:00Z"
}

Update a waitlist

Partially update a waitlist. The waitlist status is always retained as waitlist.

Requires the EDIT_PURCHASE permission on the waitlist.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

query Parameters
dryRun
boolean
Default: false

When true, validates and simulates the update without persisting it.

Request Body schema: application/json
required
customerName
string

Updated customer name

customerEmail
string <email>

Updated customer email

phone
string or null

Updated customer phone number

Array of objects (WaitlistItemRequest)

Updated waitlist items

object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "customerName": "Jane Doe",
  • "phone": "+1987654321"
}

Response samples

Content type
application/json
{
  • "id": "60f7b3c4e4b0a1234567890a",
  • "object": "waitlist_purchase",
  • "status": "waitlist",
  • "internalStatus": "committed",
  • "customerName": "John Doe",
  • "customerEmail": "john.doe@example.com",
  • "customerLocale": "en-US",
  • "customerTimezoneName": "America/New_York",
  • "phone": "+1234567890",
  • "phoneCanonical": "1234567890",
  • "currency": "USD",
  • "amount": 150,
  • "amounts": {
    },
  • "balances": {
    },
  • "balance": 0,
  • "payNow": 50,
  • "dueNow": 50,
  • "minimumDue": 25,
  • "affiliatePayment": 15,
  • "referenceId": "EXT-BOOKING-123",
  • "source": "website",
  • "seller": {
    },
  • "organizer": {
    },
  • "partnerSeller": {
    },
  • "partner": {
    },
  • "affiliate": {
    },
  • "conversation": {
    },
  • "waitlist": {
    },
  • "travelers": [
    ],
  • "items": [
    ],
  • "lineItems": [
    ],
  • "tags": [
    ],
  • "notes": [
    ],
  • "reminders": [
    ],
  • "paymentReminders": [
    ],
  • "splitPayment": {
    },
  • "trackingData": {
    },
  • "telemetry": {
    },
  • "meta": { },
  • "createdAt": "2023-12-07T10:30:00Z",
  • "updatedAt": "2023-12-07T11:45:00Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "requiresCaptcha": false,
  • "termsAgreedAt": "2023-12-07T10:25:00Z",
  • "releaseHoldAt": "2023-12-07T12:00:00Z",
  • "notifyAt": "2023-12-07T09:00:00Z",
  • "migratedAt": "2023-12-07T08:00:00Z",
  • "commissionRefundProcessedAt": "2023-12-07T16:00:00Z",
  • "purchase": {
    },
  • "convertedAt": "2024-12-15T10:00:00Z",
  • "deletedAt": "2024-12-16T10:00:00Z"
}

Add a tag to a waitlist

Add a tag to a waitlist. The waitlist entry may be a waitlist purchase or a waitlist order, and the required permission differs accordingly.

Requires the CREATE_WAITLIST_PURCHASE_TAGS permission for waitlist purchases, or the CREATE_ORDER_TAGS permission for waitlist orders.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

Request Body schema: application/json
required
id
required
string

Tag identifier/label

system
boolean
Default: false

Whether to create the tag as a system tag. Only applied for callers with the ROLE_CREATE_SYSTEM_TAG role; ignored otherwise. System tags cannot be removed.

Responses

Request samples

Content type
application/json
{
  • "id": "Priority"
}

Response samples

Content type
application/json
{
  • "id": "Priority"
}

Remove a tag from a waitlist

Remove a tag from a waitlist. System-generated tags cannot be removed and return a 403 response.

Requires the DELETE_WAITLIST_PURCHASE_TAGS permission for waitlist purchases, or the EDIT_ORDER_TAGS permission for waitlist orders.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

tagId
required
string
Example: Priority

Tag identifier to remove.

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}

Create a waitlist note

Add a note to a waitlist entry. The waitlist entry may be a waitlist purchase or a waitlist order.

Requires the CREATE_WAITLIST_PURCHASE_NOTES permission for waitlist purchases, or the CREATE_ORDER_NOTES permission for waitlist orders.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

Request Body schema: application/json
required
text
required
string

Note content

Responses

Request samples

Content type
application/json
{
  • "text": "Customer flexible on date - contact when a slot opens"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Update a waitlist note

Update the text of an existing waitlist note.

Requires the EDIT_WAITLIST_PURCHASE_NOTES permission for waitlist purchases, or the EDIT_ORDER_NOTES permission for waitlist orders.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Request Body schema: application/json
required
text
required
string

Updated note content

system
boolean

Whether the note is a system-generated note.

Responses

Request samples

Content type
application/json
{
  • "text": "Customer confirmed - moved to a booking"
}

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439011",
  • "text": "Customer requested a window seat",
  • "created": "2019-08-24T14:15:22Z",
  • "updated": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "updatedBy": {
    },
  • "system": false
}

Delete a waitlist note

Delete a waitlist note.

Requires the DELETE_WAITLIST_PURCHASE_NOTES permission for waitlist purchases, or the DELETE_ORDER_NOTES permission for waitlist orders.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string
Example: 507f1f77bcf86cd799439011

Waitlist ID

noteId
required
string
Example: 507f1f77bcf86cd799439013

Note ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "message": "string",
  • "code": 0
}