Workspace API
A REST API that lets external booking engines and partner systems browse trips, check availability, and create orders in your workspace.
The Workspace API is a REST interface that allows external applications — such as custom booking websites, partner systems, or CRM integrations — to interact with your workspace programmatically. Through the API, external systems can browse your trips, check real-time availability and pricing, and create fully processed orders with automatic payment link generation.
How It Works
External applications authenticate using an API key included in every request. Once authenticated, they can list your trips, retrieve detailed product and pricing information, check availability for specific participant combinations, and submit orders. When an order is created through the API, Itsy handles everything automatically: client record creation, pricing calculation, payment link generation, and confirmation email delivery.
Authentication
Every request must include your API key in the x-api-key header. The key identifies your workspace and enforces the configured rate limit. See API Keys for how to create and manage keys.
Requests without a valid key receive a 401 Unauthorized response.
Available Endpoints
All endpoints are prefixed with /v1/. The full base URL depends on your environment.
Labels
List Labels
GET /v1/labels
Retrieve all active labels in your workspace. Labels are used to tag and categorize trips. External systems can use these labels to filter trips or build themed booking experiences.
Each label in the response includes its name and slug. Use the slug values when filtering trips by label.
Trip Categories
List Trip Categories
GET /v1/trips/categories
Retrieve all active trip categories in your workspace. Trip categories let you organize trips into groups such as "Day Tours", "Multi-day Adventures", or "Cruises".
Each category in the response includes its name and slug. Use the slug values when filtering trips by category.
Trips
List Trips
GET /v1/trips
Retrieve all bookable trips in your workspace with optional filters.
| Parameter | Type | Description |
|---|---|---|
| departingFrom | Date (optional) | Only trips departing on or after this date |
| departingTo | Date (optional) | Only trips departing on or before this date |
| labels | Repeated string (optional) | One or more label slugs to filter by |
| categories | Repeated string (optional) | One or more category slugs to filter by |
| page | Number (optional) | Page number, starting at 1 |
| pageSize | Number (optional) | Items per page (default 25, max 100) |
Only trips with future departures are returned. Static trips are filtered by their departure date, while dynamic trips are included if they have at least one upcoming departure within the requested date range.
Both labels and categories accept repeated query parameters to pass multiple values -- for example, ?labels=slug1&labels=slug2&categories=day-tours. Multiple values for the same filter are ORed together (match any of the listed label slugs, or any of the listed category slugs), while different filters are ANDed (trips must match the labels filter and the categories filter). Comma-separated values in a single parameter are not supported.
Each trip in the response includes:
| Field | Description |
|---|---|
| id | The trip's unique identifier (GUID) |
| name | Trip display name |
| slug | URL-friendly identifier used in other endpoints |
| code | Internal trip code |
| type | Trip type (static or dynamic) |
| departingOn | Departure date (static trips) |
| length | Trip length in days |
| durations | Available duration options (for duration-based trips) |
| labels | Assigned label names and slugs |
| categoryName | Trip category name |
| serieName | Series name (if the trip belongs to a series) |
| productCount | Number of products available on the trip |
| allowDeposit | Whether deposit payment is available for this trip |
Get Trip Details
GET /v1/trips/{slug}
Retrieve complete information for a single trip by its slug. The response includes everything from the list endpoint plus:
| Field | Description |
|---|---|
| description | Full trip description text |
| overrideDepositAmount | Trip-specific deposit amount (overrides workspace default) |
| overrideDepositDayCount | Trip-specific deposit day count (overrides workspace default) |
| bookingCutoffInDays | Days before departure when booking closes |
| groups | Product groups, each containing its products with pricing and availability |
| ungroupedProducts | Products not assigned to any group |
This gives an external system everything it needs to display a booking interface.
Get Trip Products
GET /v1/trips/{slug}/products
Retrieve the products available on a trip, with pricing calculated for a specific participant combination. Unlike Get Trip Details, this endpoint accepts participant counts so prices reflect the actual booking scenario.
| Parameter | Type | Description |
|---|---|---|
| slug | Path string | The trip slug |
| adults | Query number | Number of adult participants |
| children | Query number | Number of child participants |
| infants | Query number | Number of infant participants |
The response includes product groups and ungrouped products, each with rate details, capacity, current availability, variants, and duration-specific pricing.
Get Field Requirements
GET /v1/trips/{slug}/fields
Retrieve the data fields required for clients and participants when booking a specific trip. The response contains two field maps:
| Field Map | Description |
|---|---|
| client | Fields for the booking client (e.g., first name, last name, email, phone). Each field is true if required, false if optional. |
| participant | Fields for each participant (e.g., name, passport number, nationality, date of birth). Each field is true if required, false if optional. |
If the trip has custom field overrides, those take precedence over workspace defaults. This endpoint helps external booking forms collect the right information before submitting an order.
Check Availability
POST /v1/trips/{slug}/availability
Submit a participant combination and product selections to validate availability and get a price calculation.
What you send:
| Field | Description |
|---|---|
| adults | Number of adult participants |
| children | Number of child participants |
| infants | Number of infant participants |
| duration | Selected duration (for duration-based trips) |
| products | List of product selections, each with a product ID, optional variant ID, and participant counts or indexes |
What you receive:
| Field | Description |
|---|---|
| isValid | Whether the booking is still available (checks capacity and booking cutoff) |
| errorMessage | Reason if the booking is not valid |
| totalPrice | Calculated total for the selected products and participants |
| totalPricePerParticipant | Average price per person |
| deposit | Deposit details (see below) |
| lineItems | Per-product price breakdown |
The deposit object includes:
| Field | Description |
|---|---|
| isAllowed | Whether a deposit payment is available for this booking |
| disallowedReason | Why deposits are not available (e.g., departure too soon) |
| amount | Deposit amount to collect |
| balanceDue | Remaining amount after the deposit |
| balanceDueOn | Date when the remaining balance is due |
| fullPaymentDueDayCount | Days before departure when full payment is required |
| daysUntilDeparture | Days until the trip departs |
Use this before creating an order to show customers accurate pricing and confirm availability.
Get Seat Maps
GET /v1/trips/{slug}/seats
Retrieve seat maps for one or more products on a trip. Products that have a seating layout return their seat grid with per-seat availability and pricing.
| Parameter | Type | Description |
|---|---|---|
| slug | Path string | The trip slug |
| products | Query string | Comma-separated list of product IDs to fetch seat maps for |
At least one product ID is required. Products without a seat map are silently omitted from the response.
Each seat map in the response includes:
| Field | Description |
|---|---|
| productId | The product this seat map belongs to |
| totalRows | Number of rows in the layout |
| totalColumns | Number of columns in the layout |
| seatSelectionMode | How seats are selected (e.g., manual pick or automatic assignment) |
| totalSeats | Total seats in the layout |
| availableSeats | Seats currently available for booking |
| seats | List of individual seats with row, column, label, per-participant-type rates, characteristics, and availability status |
Use the Get Trip Products endpoint first to determine which products have a seat map (via the hasSeatMap flag), then request seat maps only for those products.
Orders
Create Order
POST /v1/orders
Submit a complete order with client details, participants, and product selections. Itsy processes the order end-to-end:
- Client matching — If a client with the same email exists, the existing record is used. Otherwise, a new client is created.
- Participant creation — All travelers are added to the order with their details.
- Pricing calculation — Product prices are calculated based on rate types, participant counts, and any promo codes.
- Payment setup — If a payment provider is configured, a payment link or form data is generated for the selected payment intention (full payment or deposit).
- Confirmation email — An order confirmation email is automatically sent to the client.
- Event publishing — Events are published for any configured actions (e.g., triggers on external order creation).
What you send:
| Field | Description |
|---|---|
| tripId | The trip ID (GUID) to book |
| adults | Number of adult participants |
| children | Number of child participants |
| infants | Number of infant participants |
| duration | Selected duration (for duration-based trips) |
| products | Selected products, each with product ID, optional variant ID, and participant assignments |
| client | Client details: first name, last name, email, and optional phone and unique ID |
| participants | Participant details: type (adult/child/infant), name, and optional fields (email, phone, gender, nationality, address, passport details, date of birth) |
| promoCode | Optional discount code |
| paymentIntention | PayInFull or PayDeposit |
What you receive:
| Field | Description |
|---|---|
| orderId | The created order's unique identifier |
| orderCode | Human-readable order reference code |
| price | Total order price |
| depositAmount | Deposit amount (if deposit payment was selected) |
| status | Order status |
| paymentStatus | Payment status |
| paymentProvider | The payment provider used (Stripe, Rapyd, Teya, or Straumur). Valitor is a legacy provider and is intentionally excluded from Workspace API responses. |
| paymentUrl | URL to redirect the customer to for payment (if applicable) |
| paymentFormData | Form data for payment providers that use form submission instead of URL redirect |
| createdOn | Order creation timestamp |
| startingOn | Trip start date |
| endingOn | Trip end date |
| fullyPaidOn | Date the order was fully paid (null until paid) |
| conflicts | Non-fatal issues that occurred during order creation but did not prevent it (e.g., a seat reservation that lost a race to another booking). Empty on a clean success. |
Find Order
GET /v1/orders/public-url
Look up an order by its code and client email, and receive a public URL where the customer can view their order. This is useful for building "find my order" flows in external booking engines.
| Parameter | Type | Description |
|---|---|---|
| code | Query string | The order reference code |
| Query string | The client's email address |
The response is the public URL for the order. If no matching order is found, a 404 Not Found is returned.
Get Order
GET /v1/orders/{orderId}
Retrieve the current status of an order created through the API. Use the order ID returned from the Create Order response.
| Field | Description |
|---|---|
| orderId | The order's unique identifier |
| orderCode | Human-readable order reference code |
| price | Total order price |
| depositAmount | Deposit amount |
| status | Current order status |
| paymentStatus | Current payment status |
| createdOn | Order creation timestamp |
| startingOn | Trip start date |
| endingOn | Trip end date |
| fullyPaidOn | Date the order was fully paid (null until paid) |
Rate Limiting
Each API key has a configured rate limit (requests per minute). Requests exceeding the limit receive an error response. You can adjust the rate limit from the API Keys settings page.
What the API Can and Cannot Do
Can do:
- List available labels and trip categories
- Browse and filter trips by date range, labels, and categories
- Retrieve full product and pricing details for a specific participant combination
- Retrieve seat maps with per-seat availability and pricing for products with seating layouts
- Check real-time availability and get accurate deposit calculations
- Retrieve field requirements for booking forms (client and participant fields)
- Create orders with automatic client matching, payment link generation, and confirmation emails
- Look up an order by code and email to get its public URL
- Track order status and payment status
Cannot do:
- Modify or cancel existing orders, trips, or products
- Access sensitive payment instrument details (e.g., full card numbers, CVV, bank account numbers); non-sensitive fields such as
price,depositAmount, andpaymentStatusremain available. - Manage clients or participants independently of orders
- Access data from other workspaces
- Bypass rate limits or authentication
How It Connects
- API Keys — Each API key grants access to one workspace's API with a configured rate limit and environment.
- Trips — The API exposes your trips, products, and pricing for external consumption.
- Orders — Orders created through the API appear in your admin interface like any other order, with the origin marked as "Workspace API". Each order tracks which API key created it for auditing purposes.
- Actions — Order creation triggers configured actions, so automations work the same for API-created orders.
- Payment Providers — The API generates payment links using your configured payment provider (Stripe, Rapyd, Teya, or Straumur). Valitor is a legacy provider and is intentionally excluded from Workspace API responses.
- Labels — External systems can list all labels and filter trips by label slugs to build themed or filtered booking experiences.
- Trip Categories — External systems can list all categories and filter trips by category slugs to present organized booking options.