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.

experiences

Experience and activity management

List experiences

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

Filtering Options

  • Filter by seller, category, location, and completion status
  • Search by name or description text
  • Filter by visibility and review status

Context Behavior

  • Authenticated users: Can see all experiences they have access to
  • Public access: Only shows publicly visible, complete experiences
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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

search
string
Example: search=kayaking

Search experiences by name or description

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

cutoff
integer >= 1

Cutoff time for bookings in minutes

cutoffType
string
Enum: "pre_start" "pre_end"

Type of cutoff (before start or end)

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

Business hours for customer communications

paymentMethod
string
Enum: "cc" "later"

Payment method accepted

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

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

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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,
  • "earlyReturn": false,
  • "isScheduled": true,
  • "balanceDueOffset": 7,
  • "balanceDueReminder": 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

cutoff
integer >= 1

Cutoff time for bookings in minutes

cutoffType
string
Enum: "pre_start" "pre_end"

Type of cutoff (before start or end)

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

Business hours for customer communications

paymentMethod
string
Enum: "cc" "later"

Payment method accepted

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

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

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": { },
  • "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": {
    },
  • "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",
  • "customerNamePreference": "required",
  • "checkInValiditySummary": {
    },
  • "balanceDueOffset": 1440,
  • "balanceDueReminder": 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

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
}

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

events

Event and schedule management

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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
string <date-time>

Filter events starting from this date

end
string <date-time>

Filter events ending before this date

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.

You must be authenticated as the seller or an authorized delegate with administrator or reservationist roles.

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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.

You must be authenticated as the seller or an authorized delegate with administrator or reservationist roles.

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.

You must be authenticated as the seller or an authorized delegate with administrator or reservationist roles.

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.

You must be authenticated as the seller or an authorized delegate with appropriate permissions.

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
{
  • "id": "507f1f77bcf86cd799439021",
  • "guide": {
    },
  • "confirmed": true,
  • "sentAt": "2024-12-14T15:30:00Z"
}

Update event guide

Update an event guide assignment. Currently supports updating the guide assignment itself.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID

Request Body schema: application/json
required
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "guide": {
    },
  • "confirmed": true,
  • "sentAt": "2019-08-24T14:15:22Z"
}

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 confirmation status for the event.

Authorizations:
apiKeybasicAuth
path Parameters
id
required
string

Event ID

guideId
required
string

Guide ID to confirm

Responses

Response samples

Content type
application/json
{
  • "id": "507f1f77bcf86cd799439021",
  • "guide": {
    },
  • "confirmed": true,
  • "sentAt": "2024-12-14T15:30:00Z"
}

users

User management

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
  • Name and email changes propagate to all related records
  • Phone changes are seller-scoped
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

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.

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": [
    ],
  • "next": "https://xola.com/api/delegators?skip=20&limit=20"
}

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
}

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.

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
]

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
}

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

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

Response 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

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

Response samples

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 (embedded checkout, 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 (requires embedded checkout permission)

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 (requires embedded checkout permission)

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.

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 all notification preferences

Configure notification preferences for all notification types. Updates the complete notification preferences configuration.

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.

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

Seller ID

notificationType
required
string
Example: booking_confirmation

Notification type to update

Request Body schema: application/json
required
type
required
string

Type of notification

required
Array of objects

Notification channels and their settings

Responses

Request samples

Content type
application/json
{
  • "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

Responses

Request samples

Content type
application/json
{
  • "destination": "xola",
  • "reviewTemplate": null,
  • "reviewLink": null,
  • "sendReviewEmailToAllTravelers": false
}

Response samples

Content type
application/json
{}

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

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
}

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

purchases

Purchase and booking management

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.

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

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,
  • "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": {
    },
  • "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 see customer-appropriate information
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

  2. Operations-based PATCH with 'ops' property: Use the ops array to perform specific operations

    • Use when adding/removing line items or applying discount codes
    • Operations supported: addLineItem, addLineItemWithPayment, addCode, removeLineItem

Operations-based updates support:

  • 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)

Path format for operations:

  • /lineItems for purchase-level operations
  • /items/{itemId}/lineItems for item-specific operations

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

object

Additional metadata to update

Array of any (PatchOperation) non-empty

Array of operations to perform on the purchase, Use this when adding or removing lineItems

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

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

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

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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": "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,
  • "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": {
    },
  • "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": {
    }
}

Gift Offers

Gift offer and voucher management

List all gift offers

Retrieve all gift offers with optional filtering and pagination

Authorizations:
apiKeybasicAuth
query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

Resource ID

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

The image file to upload

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

purchaseRules

Purchase rule and automation management

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

expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

lineItemTemplates

Line item template management for billing and pricing

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

expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=unit

Comma-separated list of related objects to expand in the response. Supported values: unit (for UnitLineItemTemplate objects only)

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

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=unit

Comma-separated list of related objects to expand in the response. Supported values: unit (for UnitLineItemTemplate objects only)

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
}

payments

Payment and transaction management

calendar

Calendar and timeslot management

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.

Supports comma-separated values for array parameters and comprehensive filtering options for capacity, guides, resources, and schedule types.

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: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

allowPastSlots
boolean
Default: false

Include past time slots in results

package
string
Example: package=507f1f77bcf86cd799439018

Package ID for package-specific availability

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
}

forms

Questionnaire management

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

media

Media and attachment management

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

expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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: "daily" "weekly" "monthly" "custom" "once"

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"

Whether departure time is fixed or varies

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

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: "daily" "weekly" "monthly" "custom" "once"

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"

Whether departure time is fixed or varies

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

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": [
    ]
}

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 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: "daily" "weekly" "monthly" "custom" "once"

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: "daily" "weekly" "monthly" "custom" "once"

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: "daily" "weekly" "monthly" "custom" "once"

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": "daily",
  • "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: "daily" "weekly" "monthly" "custom" "once"

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": "daily",
  • "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
}

conversations

Conversation management

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
}

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 message content using template variables and customer data.

This endpoint renders the message template with actual or dummy data to show how the final message will appear. Returns HTML content suitable for preview display.

Supports the same filtering and template options as the send messages endpoint.

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 sample customer data for the preview

Responses

Request samples

Content type
application/json
Example
{
  • "messageTemplate": {
    },
  • "filters": {
    }
}

Response samples

Content type
text/html
<h1>Welcome John!</h1>
<p>Thank you for booking Adventure Tour for 2 guests.</p>
<p>Date: January 20, 2024</p>
<p>Questions? Contact us at (555) 123-4567</p>

Send message in conversation

Creates a new message within an existing conversation.

Supports two types of messages:

  • User messages: Regular messages with body and from fields
  • 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": "seller@example.com"
}

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef456",
  • "body": "Thank you for your inquiry. We'll get back to you shortly.",
  • "from": "seller@example.com",
  • "to": "customer@example.com",
  • "createdAt": "2024-01-15T10:30:00Z",
  • "status": "sent",
  • "locale": "en"
}

Update message

Updates a message within a conversation. Currently supports updating message status and error information.

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"

Message status

error
string

Error message if applicable

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "60f7d1234567890abcdef456"
}

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

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
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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
query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

Display name of the catalog item

type
required
string
Enum: "quantity" "choices" "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"

Visibility level of the catalog item

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

Get catalog item by ID

Retrieve a specific catalog item by its unique identifier

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

Resource ID

query Parameters
expand
string
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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

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

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
}

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
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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
[
  • {
    }
]

reports

Analytics and reporting

Coupons

Coupon management and discount configuration

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

expand
Array of strings
Items Value: "purchaseRule"
Example: expand=purchaseRule

Fields to expand in the response

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
Array of strings
Items Value: "purchaseRule"
Example: expand=purchaseRule

Fields to expand in the response

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 to update

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 to delete

Responses

Response samples

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

Coupon Codes

Coupon code creation and management

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 to update

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 to void

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
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
expand
Array of strings
Items Value: "coupon"
Example: expand=coupon

Fields to expand in the response

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

purchaseItems

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)

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

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
}

transactions

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.

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"
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
Items Enum: "ACH" "Wire" "PayPal" "Check" "Cash" "Other" "Credit Card" "Electronic" "Voucher" "Affiliate Deposit" "Gift" "Store Credit" "Xola Pay" "Plugin"
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"

Type of transaction

method
string
Enum: "ACH" "Wire" "PayPal" "Check" "Cash" "Other" "Credit Card" "Electronic" "Voucher" "Affiliate Deposit" "Gift" "Store Credit" "Xola Pay" "Plugin"

Payment method

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"

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

Blackout Schedules

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
}

Affiliates

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
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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
Enum: "aggregation" "breakdown" "checkInValiditySummary" "combo" "conversation" "coupon" "demographic" "event" "experience" "experiences" "fundingDestination" "items" "membership" "membershipItem" "membershipPurchaseItem" "notes" "organizer" "package" "partnerPackage" "partnerSeller" "product" "purchase" "purchaseRule" "purchaseRuleLink" "selectedProducts" "seller" "seller.name" "template" "transaction" "travelers" "unit" "updated" "user" "waiver"
Example: expand=experience,seller

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a PurchaseItem might have an associated Experience ID. You can expand these objects in line with the expand request parameter.

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