openapi: 3.1.0 x-stoplight: id: obltqlvi1ac1n info: title: FareHarbor Integration Center version: '1.0' contact: email: support@fareharbor.com name: FareHarbor url: 'https://help.fareharbor.com/hc/' servers: - url: 'https://fareharbor.com/api/external/v1' description: production - url: 'https://demo.fareharbor.com/api/external/v1' description: demo tags: - name: Getting Started description: | FareHarbor offers powerful APIs and webhooks designed to streamline integrations, increase automation, and scale your business--whether you're an affiliate aiming to integrate live booking capabilities, or a software partner enhancing backend operations. ### Who Can Access the API? FareHarbor offers API access to: - **Affiliates** looking to sell FareHarbor client inventory directly within their own platforms - **Software Partners** integrating FareHarbor into systems like CRMs, POS, accounting tools, or waiver and photo platforms All requests are reviewed for eligibility. To begin, email [support@fareharbor.com](mailto:support@fareharbor.com) with a brief summary of your use case. If you are a distribution affiliate, please fill out our application for API [here](https://airtable.com/appn3FgNIepgAu6GD/shra6tuh90diXXOFr). ### For Affiliates Affiliates can use our External API to access and book inventory in real time. This enables platforms like OTAs, concierges, and marketplaces to create seamless booking experiences. #### Key Capabilities: - **API Access:** Available to qualified Affiliates for distribution purposes - **Query Inventory:** Retrieve real-time availability, pricing, and item metadata ("items") for operators in your partner network or through the FareHarbor Distribution Network (FHDN) - **Create and Manage Bookings:** Use the Bookings endpoints to create and manage bookings and manage customer data - **Testing Environment:** Safely test your implementation in our demo environment ### For Software Partners Software and integration partners can connect with FareHarbor to automate workflows and synchronize client data. #### Typical Use Cases: - CRMs, POS systems, accounting tools - Waiver and photo capture platforms - Support and marketing automation tools #### Integration Capabilities: - **Webhook Access:** Built for Software Partners to support non-distribution use cases - **Real-Time Sync:** Configure webhooks so that you receive automatic updates on bookings, customers, and payments - **Data Management:** Use the External API to pull booking, availability, and customer records - **Custom Integrations:** Build tailored workflows using booking-level data, custom fields, and waiver metadata ### Resources and Support Both affiliates and software partners have access to the following tools and documentation to support their FareHarbor integrations: - **Production API Documentation:** [https://developer.fareharbor.com/](https://developer.fareharbor.com/) — Contains all necessary technical details about endpoints, data formats, and sample code - **Demo API Environment:** [https://demo.fareharbor.com/api/external/v1/](https://demo.fareharbor.com/api/external/v1/) — A testing platform where you can safely experiment with API calls without affecting live data - **Help Center:** [https://fareharbor.com/help/](https://fareharbor.com/help/) — Guidance and support articles for technical and operational questions - **Technical Support:** Our experienced support team is ready to assist you with any questions or challenges during your integration process Get started today to enhance your platform's capabilities and provide a seamless experience to your users with FareHarbor's comprehensive integration solutions. ## API Certification To receive your live API credentials you must first successfully complete API Certification. This process ensures your integration accurately supports core FareHarbor functionality for scalability with FareHarbor operators. Once certification is complete, we will provide a short survey before issuing your production API credentials. If you have any questions throughout development or certification, please contact your FareHarbor representative at [api-support@fareharbor.com](mailto:api-support@fareharbor.com). ### Required Integration Capabilities Your integration must support the following FareHarbor functionality before certification can be completed. - Must pull ticket pricing from FareHarbor (see [Availabilities endpoints](#tag/Availabilities-Endpoints)). - Must support multiple [API User keys](#tag/Authentication) (issued per currency). - Must support [Custom Fields](#tag/Custom-Fields) and applicable [Custom Field pricing](#tag/Custom-Fields/Priced-vs-unpriced-custom-fields). - Must support Product Tour Options under a single ID (see [Items endpoints](#tag/Items-Endpoints)). - Must correctly display availability level [Public Headlines](#tag/Data-Types/Schemas/Availability) (may require a demo/sample product for review). - Must correctly translate General Admission or Opening Hours products with entry times (see [Availabilities endpoints](#tag/Availabilities-Endpoints)). - Must support multiple FareHarbor [customer types](#tag/Data-Types/Schemas/Customer-Type) within a single ticket category, if set categories exist. - Must utilize the [Validate Endpoint](#tag/Bookings-Endpoints/operation/post-validate) prior to instant confirmation. - Utilize the [Bookings Webhook](#tag/Webhooks/Configuring-webhooks/Booking-notifications) to register booking updates (i.e. supplier initiated cancellations). **NOTE:** It's not required, but highly recommended, to use the [Items Webhook](#tag/Webhooks/Configuring-webhooks/Item-notifications) to register content updates. ### Certification Testing Create at least one booking for every product available in the assigned Dolphin Tours sandbox environment (see [POST bookings](#tag/Bookings-Endpoints/operation/post-bookings)). - Each booking must include: - Customer name - Phone number - Email address - Submit at least one booking containing a [Booking Note](#tag/Bookings-Endpoints/operation/put-update-booking-note). - Create bookings using at least two different [Customer Types](#tag/Data-Types/Schemas/Customer-Type), where applicable. - Create a booking using all [custom fields](#tag/Custom-Fields) identified in the Dolphin Tour (custom field) item. Verify pricing at time of booking, where applicable. - If applicable, submit bookings using at least two different [Transportation/Lodging](#tag/Lodging-Endpoints) selections. - [Rebook](#tag/Rebooking) one existing booking. - [Cancel](#tag/Bookings-Endpoints/operation/delete-booking) one existing booking. ### Certification Validation As part of certification, FareHarbor will assess your integration using a variety of sample booking scenarios to confirm your integration correctly supports the required functionality across different operator configurations. Validation may include a review of either a sample product or live demo of the expected booking process to ensure feature implementation. ## Rate Limits We enforce two rate limits on requests to the FareHarbor External API. Both are applied per IP address, not per app key. - At most 30 requests per second per IP. - At most 3,000 requests per 5-minute period per IP. If multiple app keys are being used from the same IP, their requests all count toward the same pool. Going over either limit will result in an HTTP 429 Too Many Requests or 403 Forbidden response until the time window resets. To avoid hitting these thresholds, partners should spread requests evenly across time rather than sending large batches all at once. ## Timeouts Certain requests to the FareHarbor External API are especially time-intensive, such as some of the [Availabilities endpoints](#tag/Availabilities-Endpoints). Our infrastructure enforces an upper bound of 60 seconds on the duration of all requests to our endpoints. When a request exceeds this limit, it will be terminated with a `504 Gateway Timeout` HTTP status code. If you experience a 504 timeout for an availability request (such as by date range), we recommend re-trying the request after shortening the requested date range. ## TLS Version As of 2020-09-01 we require clients that connect to our API to make use of TLS1.2 in order to ensure a speedy and secure connection. You can test this by running a curl command against our API and if you see something like `SSL_ERROR_SYSCALL in connection to fareharbor.com:443` or `Unknown SSL protocol error in connection` you are trying to use a TLS version we do not support. If that is the case it is likely that you will need to upgrade your local openssl version, which is outside the scope of this document. ## Determining User Keys FareHarbor will provide approved API partners with User Keys that can be used to make requests and create bookings for suppliers. The supplier must confirm their approval of your API access before you are able to make bookings for them via API. If you are using the FareHarbor API to book for suppliers across multiple countries/currencies, you may be provided with one User Key per currency. You can find more information about the authentication process [here](#tag/Authentication). Alternatively, you may contact for assistance with User Keys. ## Structuring Requests and Responses All requests and responses are simple JSON objects; see [`Format`](#tag/Format). ## Interacting with the API The FareHarbor API provides a powerful way to manage bookings, customers, and inventory programmatically. Here's a quick start guide to help you set up and begin integrating with the FareHarbor API. ### Step 1: Obtain API Credentials Register for API Access: Contact FareHarbor to request API access. This typically involves setting up an account and verifying your business details. Receive API Keys: Once approved, you will be provided with API keys which are essential for authenticating requests. ### Step 2: Set Up Your Environment Choose an API Client: Decide on a programming environment and API client that suits your development needs (e.g., Postman, cURL, or any HTTP client libraries available for your preferred programming language). Install Necessary Libraries: For example, if you're using Python, you might use requests library to handle API calls. ### Step 3: Making Your First API Call Test API Connection: Start by making a simple API request to ensure your API keys are working correctly. A typical first request might be to retrieve information about available companies. Request: curl -X GET 'https://fareharbor.com/api/external/v1/companies/' -H "X-FareHarbor-API-App: APP-KEY" -H "X-FareHarbor-API-User: USER-KEY" Response: { "companies": [ { 'name': 'XYZ Scuba', 'shortname': 'xyz' } ] } ### Step 4: Common API Interactions Retrieve a list of available companies: The first thing you might want to do is retrieve the list of companies that a given affiliate has access to in FareHarbor. See [`Companies`](#tag/Company-Endpoints) to learn more. Retrieve a list of bookable items: Next you can identify all of the items on a particular provider that a given affiliate can book. Continuing the above example, we can determine which items on "XYZ Scuba" the user identified by USER-KEY can book. See [`Items`](#tag/Items-Endpoints) to learn more. Retrieve a list of availability for an item: Having found an item to book, you can access its availability on a per-day basis. See [`Availabilities`](#tag/Availabilities-Endpoints) to learn more. Create a booking for an availability: Once you've found a bookable availability you can book it by simply POSTing to the availability's booking collection. See [`Bookings`](#tag/Bookings-Endpoints) to learn more. Retrieve a booking: Given a booking by uuid it's straightforward to access the booking details. See [`Get Booking`](#tag/Bookings-Endpoints/operation/get-booking) to learn more. ### Step 5: Handling API Responses Check Response Status: Ensure each API call successfully completes by checking the status codes and response messages. Parse Data: Extract relevant information from the JSON responses for use within your application. ### Step 6: Automate and Scale Automate Frequent Tasks: Develop scripts or applications that automate common tasks, such as getting availability or fetching regular booking reports. Handle Errors: Implement robust error handling to deal with potential issues like network errors, API limits, or data inconsistencies. ### Step 8: Security and Compliance Secure API Keys: Protect your API keys to prevent unauthorized access. Data Protection: Follow best practices for data protection and ensure compliance with relevant legal regulations such as GDPR (if operating in Europe) or others specific to your location and industry. ### Step 8: Explore Advanced Features Webhooks: Use FareHarbor's webhook system for real-time updates on bookings and availability changes. See [`Webhooks`](#tag/Webhooks) to learn more. Custom Integration: Depending on your needs, explore custom integrations that go beyond the basic functionalities, such as integrating with third-party CRM or financial software. ### Documentation and Support Refer to the Official Documentation: Regularly consult the FareHarbor API documentation for detailed advice on different API endpoints and updates. Seek Support When Needed: Utilize FareHarbor’s developer support for troubleshooting and guidance on complex integration scenarios. - name: Availabilities Endpoints description: | The `/availabilities` endpoint is used to retrieve all bookable availabilities for a single item within a specified date or date range. The request pulls availability data from the Item calendar of the FareHarbor dashboard. Each individual availability shows a unique PK, which is then used during the booking process, as well as a summary of its related settings, including start/end times, capacity, valid ticket options and their prices, custom fields, party size restrictions, and more. Here the API Partner can gather the relevant PKs that they need to create their booking, and they can use the data on the API to connect and display the bookable dates and times on the product calendars on their end. The more frequently they hit this endpoint, the more accurate their product calendars will be in respect to FareHarbor. Online Booking Status: Each availability has an online booking status, which controls how it can be viewed and booked by online customers. In most cases, the status will be set to `auto`, which automatically prevents online customers from booking after a certain time cutoff, based on [item’s settings](https://help.fareharbor.com/dashboard/items/online-booking-settings/). For a complete description of these statuses and their meaning, go to [https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/](https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/). Booking Cutoff: The `effective_booking_cutoff` field exposes the last possible moment bookings are allowed for an availability, accounting for the item's online bookability settings and any custom booking restrictions. This field is only included in the response when `?detailed=yes` is passed on the request. **Things to Note:** * API Partners may pull availability at whatever intervals they want, as long as they fall within the rate limit, but we generally recommend that, at minimum, partners pull availability for the next 90 days (in 7 day segments) once per week, for the next 30 days once per day, and for the current day every 2 hours. * The standard availability endpoints will return the fully detailed availability, including custom field information and headlines. If you are not connecting to custom fields, you can include `/minimal` in your request to exclude custom field information from the response. This can also help with performance speed. * We are constantly monitoring our API and optimizing for performance. Depending on the complexity of certain products and how they are configured in our system, availability requests for some products may take longer than others. In these cases it helps to reduce the date range being pulled. * Availability Restrictions: * FareHarbor supports optional party size booking restrictions at the availability level. The following properties will be included for each availability provided by the availability endpoints to indicate applicable restrictions: * `minimum_party_size`: minimum number of customers currently allowed on a booking. * `maximum_party_size`: maximum number of customers currently allowed on a booking. * Note: a number value will be provided for enabled restrictions; a null value will be provided for restrictions that are not enabled. * Customer Type Rate Restrictions: * FareHarbor also supports optional party size booking restrictions at the customer type rate level. The following properties will be included for each customer type rate provided by availability endpoints to indicate applicable restrictions: * `minimum_party_size`: minimum number of the associated customer type allowed in a party. * `maximum_party_size`: maximum number of the associated customer type allowed in a party. * Note: the minimum_party_size restriction only applies when at least one customer of the associated customer type is in the party. * Note: a number value will be provided for enabled restrictions; a null value will be provided for restrictions that are not enabled. * Availability start and end times are in the company's local timezone. When providing a date or date range for availabilities, those dates are taken as local time of the company. - name: Bookings Endpoints description: | The bookings endpoints in the FareHarbor API provide comprehensive functionalities for managing reservations efficiently. These endpoints enable developers and business owners to integrate and automate booking-related operations seamlessly into their services. Through these endpoints, users can create, retrieve, update, and cancel bookings directly through the API. Key functionalities offered by the bookings endpoints include: * **Creating Bookings:** Enables the creation of new bookings, allowing customers to reserve spots for tours and activities directly through third-party applications. * **Retrieving Bookings:** Offers the ability to query and retrieve details of existing bookings, providing essential information like booking status, customer details, and payment information. * **Updating Bookings:** Supports modifications to existing bookings, which is crucial for managing changes in customer plans. * **Cancelling Bookings:** Allows for the cancellation of bookings, helping to manage availability and customer expectations effectively. These endpoints are designed to foster a more connected experience between tour and activity operators and their customers by simplifying the booking process through automation and integration. This ensures that businesses can focus more on providing an exceptional service experience, while the logistical aspects of bookings are handled efficiently through the API. **Things to Note:** * Orders: * Orders are a way of grouping collections of bookings so that they can be created or cancelled as a block. * A booking can belong to an order, but it doesn't have to. An order can include any number of bookings. * When `order` is not `null`, `order` is an object that provides the following property: * `display_id`: `string` - A unique identifier for the order. * See [Orders](#tag/Orders) to learn more about creating and retrieving orders. - name: Checkin Endpoints description: | The check-in endpoints in the FareHarbor API provide essential capabilities for managing the check-in processes efficiently and seamlessly. These endpoints are crucial for businesses in the tour and activity sector, as they allow for real-time, automated check-in operations through integrated systems. Key functionalities offered by the check-in endpoints include: * **Checking In Participants:** Automates the process of marking customers as present for an activity, streamlining operations and reducing manual errors. * **Listing Check-In Status:** Provides the ability to pull information on who has checked in and who hasn't, ensuring staff are well-informed and can make necessary arrangements. * **Updating Check-In Records:** Supports modifications to check-in records, which can be crucial for managing late arrivals or last-minute changes in customer plans. * **Integration with Scanning Devices:** Some endpoints are designed to work with barcode or QR code scanning devices to facilitate faster and more reliable check-in procedures. Integrating these check-in endpoints into business systems helps in providing a smoother and more efficient customer service experience, minimizing wait times, and allowing staff to focus on customer interaction rather than manual check-in processes. By leveraging these APIs, businesses can enhance operational efficiency and improve customer satisfaction. - name: Company Endpoints description: | The Company endpoints in the FareHarbor API provide robust functionalities for accessing and managing information related to companies that offer tours and activities. These endpoints are crucial for developers who need to integrate company-specific data into their applications, ensuring that users have up-to-date and detailed information about the services they are interested in. Key functionalities offered by the Company endpoints include: * **Retrieving Company Information:** Enables access to detailed information about a company, including its description, contact details, and available locations. This is vital for providing comprehensive data to users looking to book activities or tours. * **Listing Services Offered:** Allows for the enumeration of all services and activities offered by a company, which is essential for users to find and book relevant offerings. * **Accessing Operational Details:** Provides insights into the operational aspects of a company, such as business hours, peak times, and special events, assisting in better planning and resource management. These endpoints serve as a critical connection between companies in the tour and activity sectors and their potential customers, facilitating seamless information sharing and service discovery. By leveraging these API endpoints, businesses can offer enriched, detailed, and updated data to users, which enhances transparency and trust while promoting ease of access to company offerings. - name: Items Endpoints description: | The Items endpoints in the FareHarbor API provide comprehensive access to detailed information about the various activities and services offered by a company. These endpoints are essential for any application that needs to integrate, display, or manage bookings for specific items or activities within a company's portfolio. Key functionalities offered by the Items endpoints include: * **Retrieving Item Details:** Facilitates access to in-depth information about each item, including descriptions, pricing, availability, and any special requirements or features associated with the item. * **Listing All Items:** Allows users to obtain a list of all available items offered by a company, making it easier to browse and select suitable options based on preferences and requirements. * **Item Availability:** Provides endpoints to check the availability of items, helping to ensure that the booking process is up-to-date and accurate, preventing overbookings and scheduling conflicts. * **Customizable Responses:** Supports filtering and customization of the data returned, enabling developers to tailor the API responses to specific needs and ensure that the integration feels native to the application. By integrating these Items endpoints, developers can enhance their applications with powerful, real-time access to activity data, ensuring that users receive a seamless, accurate, and engaging booking experience. This integration is crucial for facilitating efficient and effective interactions between customers and tour or activity providers. - name: Crew Members Endpoints description: | The Crew Members endpoints in the FareHarbor API provide comprehensive functionality for managing crew assignments on availabilities. These endpoints allow you to assign, update, and remove crew members from specific availability slots, ensuring proper staffing and crew coordination for tours and activities. Key functionalities offered by the Crew Members endpoints include: * **Listing Crew Members:** Retrieve all crew members currently assigned to a specific availability, including their roles and notes. * **Adding Crew Members:** Assign users to availabilities as crew members with optional role assignments and notes. * **Updating Crew Members:** Modify existing crew member assignments, specifically changing roles or updating notes. * **Removing Crew Members:** Remove crew members from availabilities when they are no longer needed. These endpoints are essential for tour operators who need to manage staffing levels, assign specific roles to crew members, and maintain clear communication about crew responsibilities through notes and role assignments. - name: Users Endpoints description: | The Users endpoints provide access to user information within the context of company operations, specifically for crew management purposes. - name: Roles Endpoints description: | The Roles endpoints provide access to role definitions within companies, enabling structured crew member assignments with specific responsibilities and permissions. - name: Lodging Endpoints description: | With our `/lodgings` endpoints our API Partners are able to retrieve our charters’ lodging options, both on a dashboard level as well as on the availability level, and offer these for customers to choose from when creating a booking. - name: Affiliates And Integrations description: | Read about the robust network and capabilities that FareHarbor offers through its affiliate networks and integrations, facilitating enhanced services and operations for different user types. ## For Affiliates Available Integrations: * **FHDN API:** Learn more about our distribution network [here](https://fareharbor.com/scale/distribution-network/fareharbor-distribution-network/) * **Inventory Access:** Affiliates can access real-time inventory across diverse operators. - Access companies items & availabilities - Check customers in via QR codes - Provide lodging & transportation options * **Booking Capabilities:** Direct booking functionalities integrated into affiliate platforms. - Create bookings for customers - Update bookings - Collect custom fields for unique business requirements ## For Software Partners To learn more about software partners visit [here](https://compass.fareharbor.com/partners/software/). Connected Software Partners: * **CRM Systems:** - Call Centers & Automated Inbound Calling - Web Chats - Review Management - Podium - Yonder * **Marketing Tools:** - SMS Marketing - Digital Marketing - Sojern - TourisSolved - EMail Marketing - TourAdvantage - Mailchimp * **Customer Experience Tools:** - Advanced Ticketing - Datatrax - Waivers - Wherewolf - Smartwaiver - Photos - Fotaflo - PicThrive - Turnstiles - Alvarado - Boat Insurance - Buoy * **Other Software Partners:** - Independent Accounting Solutions - Business Consultants - Escape Rooms - Virtual Reality Management - name: Authentication description: | An app key and a user key are required to authenticate all requests to the FareHarbor external API. The app key identifies your application, and can be used for all of your affiliates. The user key identifies a specific user on a specific affiliate. These keys are in UUID format. Note that these keys *must* be kept private. If your key is disclosed publicly please contact support@fareharbor.com to have it rotated. ## Keys sent as headers (recommended) The recommended approach to passing your keys is via the custom headers `X-FareHarbor-API-App` and `X-FareHarbor-API-User`. ``` GET /api/external/v1/companies/ HTTP/1.1 Host: fareharbor.com X-FareHarbor-API-App: APP-KEY X-FareHarbor-API-User: USER-KEY $ curl -H "X-FareHarbor-API-App: APP-KEY" -H "X-FareHarbor-API-User: USER-KEY" https://fareharbor.com/api/external/v1/companies/ ``` ## Requesting Keys If you would like to pursue an integration with the FareHarbor API, please contact strategicpartnerships@fareharbor.com so that we can review your request. Note that we cannot grant access in all cases. - name: Booking Overlay Links description: | Partners can deep-link customers into FareHarbor's online booking flow with query parameters that pre-select affiliate attribution, party size, and related booking context. These URLs open the FareHarbor booking lightbox (often called the booking overlay) for a specific company, item, and availability. Use them when an integration should send a customer into FareHarbor's hosted checkout instead of creating the booking through the External API. ## URL pattern Build the URL from External API identifiers: ``` https://fareharbor.com/embeds/book/{company_shortname}/items/{item_pk}/availability/{availability_pk}/book/ ``` | Path segment | Source | | --- | --- | | `{company_shortname}` | Company `shortname` | | `{item_pk}` | Item `pk` | | `{availability_pk}` | Availability `pk` | Example: ``` https://fareharbor.com/embeds/book/test-company/items/123/availability/456/book/?full-items=yes&asn=demoaffiliate&asn-ref=DEMO-REF-001&ref=PartnerCheckout&ctrs=123456:2 ``` This opens the booking form for availability `456` on item `123`, attributes the booking to affiliate `demoaffiliate`, stores `DEMO-REF-001` as the affiliate voucher/reference, sets online booking reference `PartnerCheckout`, and pre-selects 2 of customer type rate `123456`. ## Example query parameters The parameters below are common examples for pre-populated booking overlay links. They are not an exhaustive list of every embed query parameter. | Parameter | Purpose | Example | | --- | --- | --- | | `asn` | Affiliate company shortname | `asn=demoaffiliate` | | `asn-ref` | Affiliate voucher / reference for `asn` | `asn-ref=DEMO-REF-001` | | `back` | Redirect URL used when closing or going back | `back=https://example.com/tours` | | `branding` | Show company branding in the booking overlay | `branding=yes` | | `ctrs` | Pre-select customer type rate quantities | `ctrs=123456:2` or `ctrs=123456:2,123457:1` | | `full-items` | Open the full item details booking experience | `full-items=yes` | | `language` | Preferred language, when supported | `language=en-us` | | `ref` | Online booking reference on the resulting booking | `ref=PartnerCheckout` | ### Affiliate parameters (`asn` and `asn-ref`) * `asn` is the FareHarbor shortname of the affiliate company attached to the booking. * `asn-ref` is the affiliate voucher/reference value for that relationship. For many direct affiliate integrations: ``` ?asn=demoaffiliate&asn-ref=YOUR-VOUCHER-OR-REFERENCE ``` For FareHarbor Distribution Network (FHDN) flows, use the FHDN affiliate shortname in `asn` and the selling affiliate's shortname in `asn-ref`: ``` ?asn=fhdn&asn-ref=demoaffiliate ``` Confirm the exact FHDN shortname and affiliation setup for your integration with FareHarbor before using this pattern in production. ### Customer type quantities (`ctrs`) `ctrs` pre-fills ticket counts using **customer type rate** primary keys from the availability response, not customer type primary keys. ``` ctrs={customer_type_rate_pk}:{quantity}[,{customer_type_rate_pk}:{quantity}...] ``` Examples: ``` ctrs=123456:2 ctrs=123456:2,123457:1 ``` * Each `{customer_type_rate_pk}` must match a visible customer type rate on the target availability. * Quantities must be positive integers. * Prefill is all-or-nothing: if any requested customer type rate cannot be matched, no quantities are prefilled. Use `availability.customer_type_rates[].pk` from the [Availabilities endpoints](#tag/Availabilities-Endpoints). See [Customer Type Rate](#tag/Data-Types/Schemas/Customer-Type-Rate). ### Online booking reference (`ref`) `ref` sets the booking's online booking reference. When present, it is available on booking responses and booking webhooks as `online_booking_references`. ### Display and navigation (`branding`, `language`, `back`) * `branding=yes` shows company branding in the booking overlay. * `language` requests a preferred language using a language code such as `en-us`; it applies only when that language is supported. * `back` sets a redirect URL used when the customer closes or navigates back from the overlay. It must be a full URL. ## Contact information Name, email, and phone cannot currently be pre-populated through public booking overlay URL query parameters. Customers enter contact details in the FareHarbor booking form, or the partner creates the booking through the [Bookings endpoints](#tag/Bookings-Endpoints) and supplies contact information in the request body. ## Notes * These links open FareHarbor's hosted booking UI. They do not replace External API booking creation. * Customer type rate primary keys are availability-specific. Always build `ctrs` from the availability you are linking to. * Affiliate attribution requires a valid affiliation between the affiliate (`asn`) and the company being booked. * Demo environment links use the same path shape on `https://demo.fareharbor.com/`. - name: Cancellation Policies description: | In order for cancellations to be made via API, all connections must be assigned a technical cancellation policy in the supplier’s settings in FareHarbor. As a standard step in the enablement process, we assign the **Default - API** cancellation policy when we set up every new API partner with access to mutual suppliers. *The Default - API cancellation policy allows for a booking to be canceled up until the availability start time (which are given in company local time). If a cancellation is attempted through the API for a booking after the exact start time of that availability has passed, it will be met with an error.* This allows the API partner to set cancellation policies and restrictions in their own system, and regardless of the cancellation policy agreed to between the API partner and the supplier (ex. 72 hours, 24 hours, 2 hours) our system will always allow the cancellation as long as the start time of that availability has not yet passed. We do this to allow API partners to implement cancellation restrictions on their end and to defer to their policy for when they allow their customer to cancel. **Grace Period** Regardless of any cancellation policy, the FareHarbor API will allow the immediate cancellation of a booking if it is requested within 5 minutes. **Disclaimer** API Partners should discuss and determine the cancellation terms for bookings made in their partnerships with suppliers, and the API Partner should have the ability to enforce them in their integrations. The Default API cancellation policy is intentionally open so that FareHarbor can always facilitate the cancellation and keep the supplier's availabilities up to date, but it should not be interpreted as the supplier’s "official" policy. Just because this default setting will technically allow the cancellation request up until the start time does not mean the supplier allows it. ## Understanding Cancellation Policy Fields in the API Cancellation policies are referenced in a few different ways, which we will aim to make clear here. Firstly, the Default API cancellation policy that we have been describing here is exposed on the **[Detailed Items](#tag/Items-Endpoints/operation/get-items)** endpoint (when `detailed=yes` is specified in the query string) as the `effective_cancellation_policy`. It indicates that the API will allow a cancellation up until 0.0 hours before the start of the availability. API Partners should **not** import this field, as it only reflects the default setting across all integrations and does not reflect the supplier’s preferences or any policy that they have agreed to with the API Partner. Separately on the **Items** endpoint you will find the `cancellation_policy` field, where the supplier may input their own cancellation information as text. ``` "cancellation_policy": "A full refund will be issued if notice is given at least 24 hours before start time.", ``` This is where the supplier may describe their cancellation policies and processes, however it is important to note that this field is not required for suppliers, so it may be blank. It is also important to note that whatever is written in the `cancellation_policy` field is what suppliers display on their own website - so it is not customized for API Partners. If you receive an unexpected `400 booking-cancellation-error` code, you may contact api-support@fareharbor.com to confirm the cancellation settings and see if any changes are needed. ## Items Endpoint When `detailed=yes` is specified as the query string for the items endpoint, an `effective_cancellation_policy` property will be provided for each item that specifies data regarding the effective cancellation policy as shown in the responses to the following endpoints: * [GET items](#tag/Items-Endpoints/operation/get-items) * [GET item](#tag/Items-Endpoints/operation/get-item). The `type` property specifies the effective cancellation policy type. The following types are supported: * `hours-before-start` - bookings are eligible for cancellation some number of hours before availability start time. * `hours-before-midnight` - bookings are eligible for cancellation some number of hours before midnight on availability start date. * `always` - bookings are eligible for cancellation up until a cutoff that is determined by the availability (usually the availability start time). * `never` - bookings are never eligible for cancellation (e.g. no effective cancellation policy, insufficient privileges, cancellation disallowed by policy). The `cutoff_hours_before` property specifies the number of hours for the `hours-before-start` and `hours-before-midnight` types. Note: this value can be negative indicating that bookings can be cancelled some number of hours after availability start time (when type is `hours-before-start`) or some number of hours after midnight on availability start date (when type is `hours-before-midnight`). The `cutoff_hours_before` property provides `null` when no cutoff is applicable (when bookings are never eligible for cancellation). ## Availability Endpoints When `detailed=yes` is specified as the query string for the availabilities endpoints, an `effective_cancellation_policy` property is provided for each availability that specifies data regarding the effective cancellation policy as shown in the responses of the following availabilities endpoints: * [GET availabilities by date](#tag/Availabilities-Endpoints/operation/get-minimal-availabilities-by-date) * [GET availabilities by date range](#tag/Availabilities-Endpoints/operation/get-minimal-availabilities-by-date-range) The `type` property specifies the effective cancellation policy type (see the items endpoint section for more details). The `cutoff` property specifies the last possible time (ISO8601 timestamp in company local time) bookings are eligible for cancellation. The `cutoff` property provides `null` when no cutoff is applicable (when bookings are never eligible for cancellation). ## Retrieve Booking Endpoint An `is_eligible_for_cancellation` and `effective_cancellation_policy` property is provided in the response to the following booking endpoints: * [GET booking](#tag/Bookings-Endpoints/operation/get-booking) * [DELETE booking](#tag/Bookings-Endpoints/operation/delete-booking) * [PUT booking note](#tag/Bookings-Endpoints/operation/put-update-booking-note) * [POST bookings](#tag/Bookings-Endpoints/operation/post-bookings) The `is_eligible_for_cancellation` property provides a boolean value indicating whether the booking is currently eligible for cancellation. The `type` property specifies the effective cancellation policy type (see the items endpoint section for more details). The `cutoff` property specifies the last possible time (ISO8601 timestamp in company local time) the booking is eligible for cancellation. The `cutoff` property provides `null` when no cutoff is applicable (when the booking is never eligible for cancellation). - name: Custom Fields description: | Custom fields allow an activity company to provide booking options and collect information from their customers during the booking process. For example, scuba companies often use custom fields to collect the height, weight, and shoe size of their customers during the booking process so they can set aside gear that fits properly for a dive. ## Custom Field Instances A custom field instance represents an available booking option. Details regarding the booking option are specified by the custom field associated with the custom field instance. ## Custom Field Types The API currently supports the following custom field types: `short`, `long`, `extended-option`, `yes-no`, `count` and `date`. Values for `short` and `long` custom fields can be any string under 2048 characters. Values for `extended-option` custom fields must be an `extended_option` pk defined in the `extended_options` property for the custom field. Values for `yes-no` custom fields must be boolean. Values for `count` custom fields must be an integer. Values for `date` custom fields must be a date string in `YYYY-MM-DD` format. (Email-type custom fields are not supported in the external API due to PII concerns.) ## Customer and Booking Level Custom Fields `custom_field_instances` under a `customer_type_rate` specify customer level custom fields (i.e. custom fields that are applicable to the `customer_type` specified by the `customer_type_rate`). `custom_field_instances` under an availability specify booking level custom fields (i.e. custom fields that are applicable to the entire booking). ## Priced vs unpriced custom fields - Priced CFs change the booking price when selected (e.g., a yes/no with a % modifier, or an extended option with a fixed/percentage surcharge/discount). - Unpriced CFs do not change price. Defaulting rules: - Unpriced CFs: May be defaulted when omitted from the POST payload, subject to visibility/requirements. - Priced CFs: Not auto-defaulted. They only affect price when explicitly included in `custom_field_values`. - Required CFs remain required; missing required priced CFs produce a validation error. ## Custom Field Values Booking custom fields: Values for booking custom fields are specified by including a `custom_field_values` property at the root level with the following form: * `custom_field_values`: `array` * `custom_field`: `CustomField.pk` * `value`: `string` If a custom field is priced, include it explicitly in `custom_field_values` to apply its price; priced defaults are not auto-applied. Customer custom fields: Values for customer custom fields are specified by including a `custom_field_values` property at the customer level with the following form: * `customers`: `array` * `custom_field_values`: `array` * `custom_field`: `CustomField.pk` * `value`: `string` If a custom field is priced, include it explicitly in `custom_field_values` to apply its price; priced defaults are not auto-applied. Example: { "contact": { "name": "John Doe", "phone": "+1-415-789-4563", "email": "johndoe@example.com" }, "customers": [ { "customer_type_rate": 8964453, "custom_field_values": [ { "custom_field": 123, "value": "true" } // priced yes-no ] } ], "custom_field_values": [ { "custom_field": 456, "value": "6745" // unpriced } ], "voucher_number": "V-35791209" } ## Example Consider the following example availability response (the ellipses represent properties that have been left out for the sake of brevity): { "availabilities": [ { "start_at": "2016-05-10T10:30:00-1000", "end_at": "2016-05-10T11:00:00-1000", "online_booking_status": "auto", "item": { "pk": 5000, "name": "Glider Rides" }, "pk": 9999, "customer_type_rates": [ { "pk": 555, "customer_type": { "pk": 1111, "plural": "Scenic Ride (1 passenger)", "singular": "Scenic Ride (1 passenger)" }, "custom_field_instances": [ { "pk": 4321, "custom_field": { "pk": 1, "type": "yes-no", "name": "Add an extra 30 minutes of flight time?", ... }, ... }, ... ], ... }, ... ], "custom_field_instances": [ { "pk": 1234, "custom_field": { "pk": 2, "type": "short", "name": "Hotel and Room Reservation Name", ... } }, ... ], ... }, ... ] } ### Customer Level Custom Field The custom field in the above example with `pk` 1 is a customer level custom field. It is a `yes-no` type custom field, so it accepts true/false values. ### Booking level Custom Field The custom field in the above example with `pk` 2 is a booking level custom field. It is a `short` type custom field, so it accepts any string value (less than 2048 characters). ### Booking Creation The example data below shows how one specifies custom field values for customer level custom fields (`pk` 1) and booking level custom fields (`pk` 2) when creating a booking. { "voucher_number": "123", "customers": [ { "custom_field_values": [ { "custom_field": 1, "value": true } ], "customer_type_rate": 555 } ], "contact": { "phone": "+1-123-456-7890", "name": "John Doe", "email": "johndoe@example.com" }, "custom_field_values": [ { "custom_field": 2, "value": "Hawaiian Village Waikiki Beach Resort Room 415" } ] } - name: Data Types description: | # Fields ## Markdown fields Many of the fields returned by the API contain user-defined Markdown. We also return the rendered HTML version of the field. In the following schemas, fields of type `markdown` actually contain a `string`, and imply a second field in the schema containing the rendered HTML. So the following: * `field`: `markdown` Should be treated as if it were: * `field`: `string` * `field_safe_html`: `string` The "safe" part of the field name indicates that only a limited subset of HTML is allowed; all other HTML entities are escaped. ## Amount fields All currency amounts are returned as an integer number of the smallest negotiable unit of money in the company's currency. In the case of USD, this means USD cents. So, for instance, `1425` means $14.25 USD. Some amount fields may have corresponding fields whose names are suffixed with `_display`. These fields will contain strings representing the same amount of money, but using the customary formatting for the company's country. For instance, in the case of US/USD, this will be the string `14.25`. Note that some countries may use a comma rather than a period as the decimal point. * `field`: `number` * `field_display`: `string` ## Datetime fields All datetimes are returned in ISO8601 format; for example `2013-02-04T06:21:36+0000` * `field`: `string` # Schemas ## Address Structured address data. * `city`: `string` * `country`: `string` * `postal_code`: `string` * `province`: `string` * `street`: `string` Example: { "city": "Honolulu", "country: "US", "postal_code": "96821", "province": "HI", "street": "123 Wailupe Cir" } ## Company ### Minimal Representation A `Company` object represent an affiliate or provider. * `shortname`: `string` The company's ID. * `name`: `string` The company's name. * `currency`: `string` The company's currency. Example: { "shortname": "hawaiianadventures", "name": "Hawaiian Adventures", "currency": "usd" } ### Extended Representation The extended representation provides additional information about the company (see below). * `about`: `markdown` About page content for the company. * `booking_notes`: `markdown` General notes for booking customers. * `faq`: `markdown` FAQ page content for the company. * `intro`: `markdown` Homepage content for the company. * `summary`: `string` A short tagline or summary for the company. * `url`: `string` The company's website address. * `facebook_url`: `string` The company's Facebook address. * `instagram_url`: `string` The company's Instagram address. * `tripadvisor_url`: `string` The company's TripAdvisor address. * `twitter_url`: `string` The company's Twitter address. * `yelp_url`: `string` The company's Yelp address. * `youtube_url`: `string` The company's Youtube address. * `pinterest_url`: `string` The company's Pinterest address. * `address`: `Address` The company's physical address. * `affiliated_since`: `datetime` If the API user’s company is an affiliate, then we will see a timestamp of when the relationship started. * `billing_address`: `Address` The company's billing address. * `health_and_safety_policy`: `markdown` The company's health and safety policy. This is supplemental to the item level `health_and_safety_policy` field, and is only displayed on the FareHarbor Dashboard if the specific item does not have a value for `health_and_safety_policy` set. * `open_hours`: `object | null` Represents the company's general opening and closing times. Used for general company information or for context for all-day availabilities, but should not be used in place of specific availability start and end times. If open hours have been set for this company, then `open_hours` is an object whose keys are names of days of the week. The value for each day is either `null`, if the company is closed that day; or an object whose keys are `open_time` and `close_time`, which specify the open time and close time that day in 24-hour HH:MM format. Otherwise, `open_hours` will be `null`. Example: { "company": { "shortname": "hawaiianadventures", "name": "Hawaiian Adventures", "currency": "usd", "about": "Hawaiian Adventures offers several water activities that you are sure to enjoy.", "about_safe_html": "

Hawaiian Adventures offers several water activities that you are sure to enjoy.

", "booking_notes": "Weather conditions will be evaluated at the time of check-in.\n\n-If using a voucher, please bring the voucher with you.", "booking_notes_safe_html": "

Weather conditions will be evaluated at the time of check-in.\n\n-If using a voucher, please bring the voucher with you.

", "faq": "# What should I bring?\n\nWe suggest that you bring a swimming suit, a towel, and sunscreen.", "faq_safe_html": "

What should I bring?

\n

We suggest that you bring a swimming suit, sunscreen, and a towel.

", "intro": "We offer the best water activities on Oahu", "intro_safe_html": "

We offer the best water activities on Oahu

", "summary": "Water activities 365 days a year", "url": "https://company-url.com", "facebook_url": "https://facebook.com/url", "instagram_url": "https://instagram.com/url", "tripadvisor_url": "https://tripadvisor.com/url", "twitter_url": "https://twitter.com/url", "yelp_url": "https://yelp.com/url", "youtube_url": "https://youtube.com/url", "pinterest_url": "https://pintrest.com/url", "address": { "city": "Honolulu", "country": "US", "postal_code": "96821", "province": "HI", "street": "123 Wailupe Cir" }, 'affiliated_since': '2020-06-17T15:44:03+0000', "billing_address": { "city": "Honolulu", "country": "US", "postal_code": "96821", "province": "HI", "street": "123 Wailupe Cir" }, "health_and_safety_policy": "Your health is our top priority, and we have put special measures in place to keep all guests safe both during and after your activity.\n\n* Stringent Cleaning – We've increased the frequency of disinfecting surfaces and high touch areas.\n* Social Distancing – Guests are required to stay 6 feet apart.\n* Wellness Checks – Employees receive daily wellness checks to ensure they are healthy and symptom-free.", "health_and_safety_policy_safe_html": "

Your health is our top priority, and we have put special measures in place to keep all guests safe both during and after your activity.

\n", "open_hours": { "monday": { "open_time": "10:00", "close_time": "17:00" }, "tuesday": { "open_time": "10:00", "close_time": "17:00" }, "wednesday": { "open_time": "10:00", "close_time": "17:00" }, "thursday": { "open_time": "10:00", "close_time": "17:00" }, "friday": { "open_time": "10:00", "close_time": "17:00" }, "saturday": null, "sunday": null } } } ## Agent * `pk`: `number` The agent's unique ID. * `name`: `string` The agent's name. Example: { "pk": 231, "name": "Eddie" } ## Desk * `pk`: `number` The desk's unique ID. * `name`: `string` The desk's name. Example: { "pk": 231, "name": "Windward Side" } ## Lodging * `pk`: `number` The lodging's unique ID. * `name`: `string` The Lodging's name. * `phone`: `string` The lodging's phone number. * `address`: `string` The lodging's address. * `url`: `string` The lodging's URL. * `is_self_lodging`: `bool` Whether the lodging is a customer provided, non-hotel lodging (e.g. private residence). Example: { "pk": 231, "name": "Wyndham Royal Garden", "phone": "(808) 943-0202", "address": "440 Olohana St Honolulu, HI 96815", "url": "https:\/\/www.extraholidays.com\/honolulu-hawaii\/royal-garden-at-waikiki.aspx", "is_self_lodging": false } ## Image * `pk`: `number` The image's unique ID. * `gallery`: `string` The image's gallery name. * `image_cdn_url`: `string` The image's URL. Example: { "pk": 687, "gallery": "carousel", "image_cdn_url": "https:\/\/d1a2dkr8rai8e2.cloudfront.net\/api\/file\/rvybRyLWTgyV5w4xg42p\/" } ## Location * `pk`: `number` The location's unique ID. * `type`: `string` The location's type. * `note`: `markdown` A brief note about this location that can be displayed to end users. * `address`: `Address` The location's physical address. * `longitude`: `number | null` The location's longitude. * `latitude`: `number | null` The location's latitude. * `google_place_id`: `string` The location's Google Place ID. * `tripadvisor_url`: `string` The location's TripAdvisor URL. Example: { "pk": 234234, "type": "primary", "note": "Next to the blue fence.", "note_safe_html": "

Next to the blue fence.

", "address": { "city": "Honolulu", "country": "US", "postal_code": "96821", "province": "HI", "street": "123 Wailupe Cir" }, "longitude": 21.3069, "latitude": -157.8583, "google_place_id": "ChIJYZ4srGUSAHwRT1Da4amp3x", "tripadvisor_url": "https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html", } ## Cancellation Policy * `type`: `string` The cancellation policy's type. Supported types: * `hours-before-start` Bookings are eligible for cancellation some number of hours before availability start time. * `hours-before-midnight` Bookings are eligible for cancellation some number of hours before midnight on availability start date. * `always` Bookings are eligible for cancellation up until a cutoff that is determined by the availability (usually the availability start time). * `never` Bookings are never eligible for cancellation (e.g. no effective cancellation policy, insufficient privileges, cancellation disallowed by policy). * `cutoff_hours_before`: `number` The number of hours for the `hours-before-start` and `hours-before-midnight` types. Note: this value can be negative indicating that bookings can be cancelled some number of hours after availability start time (when type is `hours-before-start`) or some number of hours after midnight on availability start date (when type is `hours-before-midnight`). The `cutoff_hours_before` property will provide `null` when no cutoff is applicable (when bookings are never elgible for cancellation). Example: { "type": "hours-before-start", "cutoff_hours_before": "24" } ## Tag * `name`: `string` The tag's display name. * `short_name`: `string` The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. Example: { "name": "Jet ski tour", "short_name": "jet-ski-tour" } ## Item Items represent a particular kind of tour that the company offers. * `pk`: `number` The item's unique ID. * `name`: `string` The name of the item. * `headline`: `string` The item's headline. * `description`: `markdown` The item's description. * `description_text`: `string` The item's plain-text description. * `description_bullets`: `[ string ]` An array containing plain-text descriptive bullet points for the item. * `cancellation_policy`: `markdown` The item's cancellation policy. * `location`: `string` The location of the item; generally where the activity takes place or where the tour leaves from, but can be anything. Unstructured. * `locations`: `[ Location ]` An array of `Location` objects associated with the item. * `is_pickup_ever_available`: `bool` Indicates whether the item is configured to provide pickups. * `image_cdn_url`: `string` A URL to the item's primary image. * `images`: `[ Image ]` An array of `Image` objects associated with the item. * `customer_prototypes`: `[ CustomerPrototype ]` An array of `CustomerPrototype` objects associated with the item. * `health_and_safety_policy`: `markdown` The item's health and safety policy. It includes details and procedures related to specific activities for the item like the precautions being taken, equipment to bring, and any additional special rules. Example: { "pk": 1867, "name": "Jet Ski Tour", "headline": "Epic Jet Ski Tour", "description": "We are conveniently located just 5 minutes from Waikiki and will arrange for pickup\/dropoff at or near your hotel.", "description_safe_html": "\u003cp\u003eWe are conveniently located just 5 minutes from Waikiki and will arrange for pickup\/dropoff at or near your hotel.\u003c\/p\u003e", "description_text": "We are conveniently located just 5 minutes from Waikiki and will arrange for pickup\/dropoff at or near your hotel.", "description_bullets": [ "Located just 5 minutes from Waikiki.", "Transportation included." ], "cancellation_policy": "A full refund will be issued if notice is given at least 24 hours before start time.", "cancellation_policy_safe_html": "\u003cp\u003eA full refund will be issued if notice is given at least 24 hours before start time.\u003c\/p\u003e", "location": "Honolulu, HI", "locations": [ { "pk": 234234, "type": "primary", "note": "Next to the blue fence.", "note_safe_html": "

Next to the blue fence.

", "address": { "city": "Honolulu", "country": "US", "postal_code": "96821", "province": "HI", "street": "123 Wailupe Cir" }, "longitude": 21.3069, "latitude": -157.8583, "google_place_id": "ChIJYZ4srGUSAHwRT1Da4amp3x", "tripadvisor_url": "https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html", } ], "is_pickup_ever_available": true, "image_cdn_url": "https:\/\/d1a2dkr8rai8e2.cloudfront.net\/api\/file\/rvybRyLWTgyV5w4xg42p\/", "images": [ { "pk": 687, "gallery": "carousel", "image_cdn_url": "https:\/\/d1a2dkr8rai8e2.cloudfront.net\/api\/file\/rvybRyLWTgyV5w4xg42p\/" } ], "customer_prototypes": [ { "pk": 2522, "display_name": "Adult", "total": 20000 } ], "health_and_safety_policy": "Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat.", "health_and_safety_policy_safe_html": "

Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat.

" } ### Item Details When `detailed=yes` is specified as the query string for the items endpoint, additional details are provided for each item. * `effective_cancellation_policy`: `CancellationPolicy` Cancellation policy data for the item. * `tags`: `[ Tag ]` An array of `Tag` objects associated with the item. Example: { "pk": 1867, "effective_cancellation_policy": { "type": "hours-before-start", "cutoff_hours_before": 24 }, "tags": [ { "name": "Jet ski tour", "short_name": "jet-ski-tour" }, { "name": "Water activity", "short_name": "water-activity" }, { "name": "Transportation included", "short_name": "transportation" }, ... ], ... } ## Customer Type Customer types represent different kinds of customers that might do an activity, for example "Adults", "Children", "Infants". Note however that FareHarbor companies use customer types to represent a range of different sorts of customers; for instance, some SCUBA companies use types like "Diver", "Snorkeler", and "Observer". * `pk`: `number` The customer type's unique ID. * `singular`: `string` * `plural`: `string` The singular and plural forms of the name of this customer type; ex. "adult", "adults". * `note`: `string` A brief note about this customer type that can be displayed to end users. Example: { "pk": 589, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old." } ## Customer Prototype * `pk`: `number` The customer prototype's unique ID. * `display_name`: `string` The customer prototype's display name. * `total`: `amount` The price of a single customer of this type. * `total_including_tax`: `amount` The price of a single customer of this type plus applicable taxes. Example: { "pk": 2522, "display_name": "Adult", "total": 20000, "total_including_tax": 21550 } ## Customer Type Rate Customer type rates set capacity and pricing information for customer types on a particular availability. ### Minimal Representation * `pk`: `number` The customer type rate's unique ID. * `customer_type`: `CustomerType` The customer type being priced. * `capacity`: `number` The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. * `is_exclusive`: `bool` Indicates that this customer type rate is "exclusive"; see below for how exclusivity affects bookability. Example: { "pk": 978, "capacity": 10, "is_exclusive": false, "customer_type": { "pk": 589, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old.", "customer_prototype": { "pk": 2522, "display_name": "Adult", "total": 20000, "total_including_tax": 21550 } } } ### Extended Representation The extended representation provides additional information about the customer type rate (see below). * `total`: `amount` The price of a single customer of this type. * `total_including_tax`: `amount` The price of a single customer of this type plus applicable taxes. * `custom_field_instances`: `[ CustomFieldInstance ]` A list of custom field instances for the customer type rate. Example: { "pk": 978, "total": 20000, "total_including_tax": 21550, "capacity": 10, "is_exclusive": false, "customer_type": { "pk": 589, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old.", "customer_prototype": { "pk": 2522, "display_name": "Adult", "total": 20000, "total_including_tax": 21550 } }, "custom_field_instances": [ { "pk": 8629, "custom_field": { "pk": 43879, "type": "yes-no", ... } } ] } ## Cost A cost object represents the different facets that might have an impact on how individual line items affect the price of a booking, such as taxes, fees, etc. * `price`: `number` The line item price. * `tax`: `number` The tax price. * `taxable`: `number` The portion of the price that is subject to taxes. * `feeable`: `number` The portion of the price the is subject to fees. * `tax_by_type`: A breakdown of taxes by tax type. * `total`: `number` The total cost after taxes and fees. Example: "total_cost": { "price": 38900, "tax": 0, "taxable": 38900, "feeable": 38900, "tax_by_type": { 53558: 0 }, "total": 38900 } ## Availability Availability objects represent particular datetimes that an item goes out. ### Minimal Representation * `pk`: `number` The availabilities's unique ID. * `start_at`: `datetime` * `end_at`: `datetime` The availability's start and end time; note that this time can be arbitrarily long or short, and that `start_at` can equal `end_at` for "point" availabilities. * `capacity`: `number` The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. * `customer_type_rates`: `[ CustomerTypeRate ]` Pricing information for available customer types (minimal version). * `online_booking_status`: `string` The availability's status. Supported types: `auto`, `open`, `call`, `closed`, `cancelled`. Example: { "pk": 50291151, "start_at": "2023-08-18T00:30:00-0600", "end_at": "2023-08-18T03:30:00-0600", "capacity": 3, "minimum_party_size": 1, "maximum_party_size": null, "online_booking_status": "auto", "customer_type_rates": [ { "pk": 65675, "capacity": 10, "customer_type": { "pk": 978, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old.", "customer_prototype": { "pk": 2522, "display_name": "Adult", "total": 20000 } } } ] } ### Extended Representation The extended representation provides additional information about the availability (see below). * `item`: `Item` The availability's item (minimal version). * `headline`: `string` The availability's headline. * `customer_type_rates`: `[ CustomerTypeRate ]` Pricing information for available customer types (extended version). * `custom_field_instances`: `[ CustomFieldInstance ]` A list of custom field instances for the availability. Example: { "pk": 4786, "start_at": "2015-01-22T11:30:00-1000", "end_at": "2015-01-22T13:30:00-1000", "capacity": 10, "item": { "pk": 1867, "name": "Jet Ski Tour" }, "headline": "Epic Jet Ski Tour", "customer_type_rates": [ { "pk": 65675, "total": 20000, "capacity": 10, "customer_type": { "pk": 978, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old.", "customer_prototype": { "pk": 2522, "display_name": "Adult", "total": 20000 }, "custom_field_instances": [ { "pk": 8629, "custom_field": { "pk": 43879, "type": "yes-no", ... } } ] } } ], "custom_field_instances": [ { "pk": 47974, "custom_field": { "pk": 3387, "type": "yes-no", ... } } ] } ## Order Orders are a way of grouping collections of bookings so that they can be created or cancelled as a block. A booking can belong to an order, but it doesn't have to. An order can include any number of bookings. * `display_id`: `string` A unique identifier for the order. Example: { "display_id": "ABTT" } ## Booking When `with_payments=yes` is specified as a query string to the bookings endpoint, the payment information is provided for the booking. The `payments` parameter will be the same as the `payments` in webhooks that can be found [here](#tag/Webhooks/Webhook-Schemas/Booking-with-Payments). * `pk`: `number` The booking's unique ID. * `uuid`: `string` The booking's universally unique identifier; used to access the booking via the API. * `display_id`: `string` The customer's "ticket number;" used only for rendering. * `availability`: `Availability` The availability to which this booking corresponds. * `contact`: `Contact` Contact information for this booking. A contact consists of: * `name`: `string` The name of the head of the party. * `phone`: `string` The contact phone number for the party. * `normalized_phone`: `string` The party's contact phone number. This will have a plus sign, the country code, and no extra characters such as commas or dashes. * `country_phone`: `string` The contact phone's country code. * `language`: `string` The contact language. * `email`: `string` The contact email for the party. * `is_subscribed_for_email_updates`: `bool` Whether or not the contact would like email updates. * `customers`: `[ Customer ]` A list of customers on this booking. Customers consist of: * `checkin_url`: `string` A short URL that can be rendered as a QR code for check-in purposes (the QR code should be "type 4" with "error correction H"). * `checkin_status`: `CheckinStatus | null` The customer's checkin status. When there is no checkin status associated with the customer, `checkin_status` will be `null`. When a checkin status is available, it consists of: * `name`: `string` The checkin status' name. * `type`: `string` The checkin status' type. Supported types are: `checked-in` and `no-show`. * `invoice_cost`: `Cost` The `invoice_cost` will be included only if the permission *View invoice prices* is enabled, otherwise it will be `null`. * `total_cost`: `Cost` The `total_cost` will be included only if the permission *View amounts* is enabled, otherwise it will be `null`. * `customer_type_rate`: `CustomerTypeRate` The customer type rate to which this customer corresponds. * `custom_field_values`: `[ CustomFieldValue ]` A list of custom field values for the customer. * `custom_field_values`: `[ CustomFieldValue ]` A list of custom field values for the booking. * `invoice_price`: `amount | null` The invoice price of this booking. Assuming that the user of the API is a reseller this will be the amount that the user of the API owes the vendor on this booking, if the vendor has opted to set up that information; otherwise it will be `null`. * `confirmation_url`: `string` The booking's confirmation page URL. * `external_id`: `string` An additional identifier if necessary. Max Length 128. * `order`: `Order | null` When there is no order associated with the booking, `order` will be `null`. * `dashboard_url`: `string` The booking's dashboard URL. * `customer_count`: `number` The number of customers on this booking. * `is_subscribed_for_sms_updates`: `boolean` Whether or not the contact would like the booking company to send them SMS updates about this booking. Note that the value of this field does not reflect whether or not the user has sent a STOP request to FareHarbor. If the user sends a STOP request to an External API client, that API client should respect that request. * `payments`: `[ Payment ]` (optional through query string) Payment information for the booking, only visible through [webhooks](#tag/Webhooks/Webhook-Schemas) or with the `with_payments=yes` query string. If there is no query string, then the `payments` won't show. Payments consist of: * `amount_paid`: `amount | null` The total amount that has been paid for the booking. * `created_at`: `datetime` When the payment has been paid for the booking. * `currency`: `string` The company's currency. * `initial_amount_paid`: `amount | null` The amount paid when the booking was first created. * `refunds`: `Refund | null` Refund detail of a booking (if there is a refund). * `amount_refunded`: `amount` Amount that is refunded. * `created_at`: `datetime` Datetime of when the refund occured. * `is_cancelled`: `boolean` Wheter or not the booking was cancelled. * `status`: `string` Status of the payment for the booking. Supported types are `initialed`, `pending`, `succeeded` and `failed`. * `type`: `string` What was used to pay for the booking. Supported types are: `card`, `in-store`, `affiliate`, 'stored-value-card`, `ideal`, `sofort`, `paypal`, `bancontact`. Example: { "pk": 6876876, "uuid": "d75102be-9732-4523-90a8-c698eff2b983", "availability": { "pk": 4786, "start_at": "2015-01-22T11:30:00-1000", "end_at": "2015-01-22T13:30:00-1000", "capacity": 10, "online_booking_status": "auto", "item": { "pk": 1867, "name": "Jet Ski Tour" }, "customer_type_rates": [ { "pk": 65675, "total": 20000, "capacity": 10, "is_exclusive": false, "customer_type": { "pk": 978, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old."" } } ] }, "contact": { "name": "Surfer Dude", "phone": "+1-443-222-1100", "phone_country": "US", "normalized_phone": "+14432221100", "email": "surfer@dude.com" }, "customers": [ { "checkin_url": "https://fhchk.co/abc", "checkin_status": { "name": "checked in", "type": "checked-in" }, "invoice_cost": { "price": 20000, "tax": 0, "taxable": 0, "feeable": 20000, "tax_by_type": { 53558: 0 }, "total": 20000 }, "total_cost": { "price": 20000, "tax": 0, "taxable": 20000, "feeable": 20000, "tax_by_type": { 53558: 0 }, "total": 20000 }, "customer_type_rate": { "pk": 65675, "total": 20000, "capacity": 10, "is_exclusive": false, "customer_type": { "pk": 978, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old."" } } }, { "checkin_url": "https://fhchk.co/def", "checkin_status": { "name": "checked in", "type": "checked-in" }, "invoice_cost": { "price": 20000, "tax": 0, "taxable": 0, "feeable": 20000, "tax_by_type": { 53558: 0 }, "total": 20000 }, "total_cost": { "price": 20000, "tax": 0, "taxable": 20000, "feeable": 20000, "tax_by_type": { 53558: 0 }, "total": 20000 }, "customer_type_rate": { "pk": 65675, "total": 20000, "capacity": 10, "is_exclusive": false, "customer_type": { "pk": 978, "singular": "Adult", "plural": "Adults", "note": "At least 18 years old."" } } } ], "invoice_price": null, "order": null, "dashboard_url": "https://fareharbor.com/hawaiianadventures/dashboard/?overlay=/contacts/7/bookings/d75102be-9732-4523-90a8-c698eff2b983/", "customer_count": 1, "is_subscribed_for_sms_udpates": false, "payments": [ { "pk": 236495, "created_at": "2022-03-23T11:36:36-0700", "type": "card", "in_store_payment_type": null, "status": "succeeded", "currency": "usd", "initial_amount_paid": 40000, "initial_amount_paid_display": "400.00", "amount_paid": 40000, "amount_paid_display": "400.00", "refunds": [] } ] } ## Capacities Note that availabilities have both an overall capacity, and customer type rates have an (optional) capacity. Both capacities, if specified, cannot be exceeded, despite the fact that the sum of available capacities of the customer type rates may not match the available capacity of the availability itself. ## Extended Option Extended options are applicable to custom fields of type `extended-option`. * `pk`: `number` The extended option's unique ID. * `name`: `string` The extended option's name. * `description`: `markdown` The extended option's description. * `modifier_kind`: `string` Can be `offset` or `percentage`. Determines whether an offset or percentage is used when the total is adjusted or set. * `modifier_type`: `string` Can be `adjust` or `set`. Determines whether the total is adjusted or set. * `offset`: `amount` When `modifier_type` is `adjust`: a positive or negative amount value. When `modifier_type` is `set`: a positive amount value. Only applicable when `modifier_kind` is `offset`. * `percentage`: `number` When `modifier_type` is `adjust`: a number between -100 and 100 inclusive. When `modifier_type` is `set`: a number between 0 and 100 inclusive. Only applicable when `modifier_kind` is `percentage`. * `is_always_per_customer`: `bool` Whether pricing should be applied to each customer (when the customer field is at the booking level). * `is_taxable`: `bool` Whether the cost of this option should affect the taxable total of a booking. Example: { "pk": 105, "name": "Helmet", "description": "Need a helmet?", "modifier_kind": "percentage", "modifier_type": "adjust", "offset": null, "percentage": 35, "is_always_per_customer": true, "is_taxable": false } ## Custom Field * `pk`: `number` The custom field's unique ID. * `type`: `string` The custom field's type. Supported types: `yes-no`, `short`, `long`, `extended-option`, `count`, and `date`. * `is_required`: `bool` Indicates whether the custom field requires a value. * `description`: `markdown` The custom field's description. * `name`: `string` The name of the custom field. * `booking_notes`: `markdown` Notes for the customer specific to the custom field. * `offset`: `amount` A positive or negative amount value. * `extended_options`: `[ ExtendedOption ]` A list the custom field's extended options. This will only be provided for custom fields that have type `extended-option`. Example: { "pk": 4502, "type": "extended-option" "is_required": false, "description": "Do you need additional safety equipment?", "name": "Safety Equipment", "offset": 100, "extended_options": { "pk": 105, "name": "Helmet", "description": "Need a helmet?", "modifier_kind": "percentage", "modifier_type": "adjust", "offset": null, "percentage": 35, "is_always_per_customer": true, "is_taxable": false } } ## Custom Field Instance * `pk`: `number` The custom field instance's unique ID. * `custom_field`: `CustomField` The custom field associated with the custom field instance. Example: { "pk": 2681, "custom_field": { "pk": 4502, "type": "yes-no" "is_required": false, "description": "Do you need additional safety equipment?", "name": "Safety Equipment", "offset": 100, "extended_options": { "pk": 105, "name": "Helmet", "description": "Need a helmet?", "modifier_kind": "percentage", "modifier_type": "adjust", "offset": null, "percentage": 35, "is_always_per_customer": true, "is_taxable": false } } } ## Custom Field Value * `custom_field`: `CustomField.pk` A valid Custom Field pk. * `value`: `string` A string up to 2048 characters. If the custom field is of type `yes-no`, "true" or "false" must be specified. If the custom field is of type `extended-option`, an extended option pk must be specified. If the custom field is of type `date`, a date string in `YYYY-MM-DD` format must be specified. Example: { "custom_field": 4502, "value": "false", "extended-option": 105 } ## Crew Member A `CrewMember` object represents a user assigned to work on a specific availability. Crew members can have assigned roles and notes that provide context about their responsibilities or special instructions. * `pk`: `integer` The crew member's unique identifier. This ID is specific to the crew member assignment and can be used for updating or removing the crew member from the availability. * `user`: `User` The user assigned as a crew member. Contains the user's name and username for identification purposes. * `role`: `Role | null` The role assigned to the crew member, if any. Roles help categorize crew members and define their responsibilities within the organization. This field is optional and can be null if no specific role is assigned. * `note`: `string` A text note providing additional context, instructions, or information about the crew member's assignment. This can include special responsibilities, equipment assignments, or any other relevant details. Example: { "crew_member": { "pk": 12345, "user": { "name": "John Smith", "username": "jsmith" }, "role": { "pk": 1, "short_name": "captain" }, "note": "Responsible for safety briefing and equipment check" } } Example with no role assigned: { "crew_member": { "pk": 12346, "user": { "name": "Jane Doe", "username": "jdoe" }, "role": null, "note": "General crew member" } } ## User A `User` object represents a person who can be assigned as a crew member to availabilities. Users are identified by their name and username within the system. * `name`: `string` The user's full name as it appears in the system. This is typically the user's first and last name combined and is used for display purposes in crew rosters and assignments. * `username`: `string` The user's unique username within the system. This is used for identification and assignment purposes when adding crew members to availabilities. The username must be unique across the system. Example: { "user": { "name": "John Smith", "username": "jsmith" } } Example in crew member context: { "users": [ { "name": "John Smith", "username": "jsmith" }, { "name": "Jane Doe", "username": "jdoe" }, { "name": "Mike Johnson", "username": "mjohnson" } ] } ## Role A `Role` object represents a specific position or responsibility that can be assigned to crew members. Roles help organize crew members by their duties and responsibilities within the company's operations. * `pk`: `integer` The role's unique identifier. This ID is used when assigning roles to crew members and for referencing the role in other operations. * `short_name`: `string` The role's short name or title. This is a concise identifier for the role that is used in crew member assignments and displays. Examples might include "captain", "guide", "safety_officer", or "mechanic". Example: { "role": { "pk": 1, "short_name": "captain" } } Example in roles list context: { "roles": [ { "pk": 1, "short_name": "captain" }, { "pk": 2, "short_name": "guide" }, { "pk": 3, "short_name": "safety_officer" }, { "pk": 4, "short_name": "mechanic" } ] } Example in crew member context: { "crew_member": { "pk": 12345, "user": { "name": "John Smith", "username": "jsmith" }, "role": { "pk": 1, "short_name": "captain" }, "note": "Responsible for safety briefing and equipment check" } } - name: Error Codes description: | This document provides more information about the following types of error codes and messages: | status | Code | Error | | ------- | ------ | ------- | | 400 |availability-date-range-invalid | Please specify an end date that comes after start date `start_date` | | 400 |book-data-amount-paid-invalid | Amount paid cannot be negative | | 400 |book-data-amount-paid-rebooking-invalid | Amount paid cannot be provided for rebooking | | 400 |book-data-parse-error | Unable to parse request body | | 400 |book-data-validation-error | Validation error: `message` | | 400 |bookability-error | Unable to create booking: [bookability-error](#tag/Error-Codes/Bookability-error) | | 400 |booking-cancellation-error | Unable to cancel booking: [booking-cancellation-error](#tag/Error-Codes/Booking-cancellation-error) | | 400 |booking-creation-error | Unable to create booking: [booking-creation-error](#tag/Error-Codes/Booking-creation-error) | | 400 |booking-custom-field-value-creation-error | Unable to create custom field value for custom_field pk %s: ensure a valid value is specified| | 400 |booking-custom-field-values-invalid |

Duplicate values provided for the following custom_field pks
The following custom_field pk values are invalid for pk
The following custom_field pk values are required for pk
The value is not valid for custom_field pk

| | 400 |booking-note-error | Unable to update booking note: `booking_note` | | 400 |contact-error | Unable to create contact: `message`| | 400 |content-type-invalid-error | Invalid content-type| | 400 |customer-custom-field-value-creation-error | Unable to create customer custom field value for customer custom_field pk %s: ensure a valid value is specified| | 400 |customer-custom-field-value-update-error | Unable to update customer custom field value: `message`| | 400 |customer-custom-field-values-invalid |

Duplicate values provided for the following customer custom_field pks
The following customer custom_field pk values are invalid for pk
The following customer custom_field pk values are required for pk
The value is not valid for customer custom_field pk

| | 400 |customer-type-rates-invalid | The following 'customer_type_rate' pk values are invalid for availability pk : | | 400 |invalid-checkin-already-checked-in | already checked in | | 400 |invalid-checkin-customer | invalid customer| | 400 |invalid-checkin-status-error | invalid checkin status | | 400 |invalid-qr-code-error | invalid QR code | | 400 |key-missing | X-FareHarbor-API-App/X-FareHarbor-API-User header or api-app/api-user parameter is required | | 400 |lodging-pk-invalid | `pk` is not a valid lodging pk for company shortname| | 400 |no-default-checkin-status-error | no default checkin status| | 400 |orderize-booking-uuid-invalid-error | `UUID` is not a valid UUID | | 400 |payment-error | Unable to create payment: `message`| | 400 |rebooking-uuid-invalid-error | `UUID` is not a valid UUID| | 400 |resend-confirmation-validation-error | Validation error: `message` | | 400 |resource-bookability-error | explicit_customer_count causes resources to be overused. Unable to satisfy resources. Please refresh the page and try again. | | 400 |voucher-number-invalid | Voucher number cannot be specified for non-affiliate bookings | | 400 |voucher-number-not-specified | Unable to create booking: a voucher number is required| | 403 |app-invalid | Invalid application | | 403 |app-key-invalid | API app key is invalid | | 403 |invalid-checkin-permissions-error | you do not have permissions to update checkin status| | 403 |orderize-booking-uuid-invalid-error | Orders not allowed | | 403 |user-key-invalid | API user key is invalid | | 404 |availability-pk-invalid | `pk` is not a valid availability pk for company shortname `shortname` | | 404 |booking-uuid-invalid | `UUID` is not a valid booking uuid for company shortname `shortname` | | 404 |company-shortname-invalid | `shortname` is not a valid company shortname | | 404 |customer-custom-field-value-pk-invalid | `pk` is not a valid customer custom field value pk for booking uuid `UUID` | | 404 |item-pk-invalid | is not a valid item pk for company shortname `shortname` | | 429 |Too Many Requests | [You have sent too many requests in too short a time interval](#tag/Getting-Started/Rate-Limits) | | 504 |Gateway Timeout | [Your request required more than 60 seconds to be processed and was terminated](#tag/Getting-Started/Timeouts) | ## Bookability error | Message | Description | | ------- | ------ | | Auto-open time not reached |Please contact api-support@fareharbor.com | | Availability was removed | Availability no longer available | | Call to book |Availability is not available for online or API booking | | Closed | Availability is closed | | Cutoff time reached |Availability is no longer bookable. Please contact the supplier or choose a different availability. | | Full for all customer types| Availability is full | | Full for customer type |Capacity is full for your selected customer type | | Invalid customer type rate for availability |Please use a different customer_type_rate pk | | Item is not available |Product is no longer offered for online or API booking | | Item is private |Product is no longer offered for online or API booking | | No bookings cutoff time reached |Availability is no longer bookable. | | Over maximum for customer type |Your selected quantity exceeds the maximum set by the supplier | | Party size is too large |Your selected quantity exceeds the maximum party size set by the supplier | | Party size is too small |Your selected quantity does not meet the minimum party size set by the supplier | | Resources are not available |Please contact api-support@fareharbor.com | | Sorry, this date and time is not available. Please call us or choose a different date or time. Error: a-already-has-exclusive. |Please contact the supplier, or select a different availability. | | Sorry, this date and time is not available. Please call us or choose a different date or time. Error: a-already-has-non-exclusive. |Please contact the supplier, or select a different availability. | | The time you are trying to book is no longer available. Please call us or go back and choose a different time.|Availability is no longer bookable. Please contact the supplier or choose a different availability. | | Under minimum for customer type |Your selected quantity does not meet the minimum set by the supplier | ## Booking creation error | Message | Description | | ------- | ------ | | Affiliates cannot be changed while rebooking without first refunding all affiliate payments. |Please contact api-support@fareharbor.com | | Availability is not bookable. |This time cannot be booked. Please try another availability. | | Cannot skip payment. |Insufficient permission, please contact api-support@fareharbor.com. | | Invalid order. |Please contact api-support@fareharbor.com | | Must make full payment. |Insufficient permission, please contact api-support@fareharbor.com. | | New bookings cannot be created for availabilities on archived items. |Product is no longer offered | | New bookings cannot be created for this contact until demo mode is disabled. |Please contact api-support@fareharbor.com | | New bookings cannot be created for this contact until demo mode is enabled. |Please contact api-support@fareharbor.com | | Non-test bookings cannot be rebooked because demo mode is enabled. |Please contact api-support@fareharbor.com | | Partial amount paid cannot exceed booking total. |Partial payment amount cannot exceed the booking total. | | Please specify a voucher number. |Voucher field is required. | | Please specify at least one customer. |Cannot create a booking for zero customers | | Sorry, you are not an affiliate for this company. |Insufficient permission, please contact api-support@fareharbor.com | | Sorry, you cannot add bookings to this contact for this company.|Please contact api-support@fareharbor.com | | Sorry, you cannot rebook this booking to this company. |Insufficient permission, please contact api-support@fareharbor.com | | Sorry, you cannot rebook while adding a booking to a customer. |Please contact api-support@fareharbor.com | | Test bookings cannot be rebooked when demo mode is not enabled.|Please contact api-support@fareharbor.com | | This booking has already been rebooked. |Cannot rebook a cancelled booking | | Unable to add to order. |Please contact api-support@fareharbor.com | | Unable to satisfy resources. |Insufficient inventory for supplier to operate the product for your selections | ## Booking cancellation error | Message | Description | | ------- | ------ | | This booking has already been cancelled. | Cannot cancel a cancelled booking | | You don't have permission to cancel this booking. | Insufficient permission, please contact api-support@fareharbor.com| - name: Examples description: | # PHP ### Dependencies Httpful PHP library. See the [installation instructions](http://phphttpclient.com/) for more information. include("./httpful.phar"); ### Request headers $api_app = "your app key"; $api_user = "your user key"; ### Root URL $root_url = "https://test.fareharbor.com/api/external/v1"; ## Listing companies ``` $companies_url = "$root_url/companies/"; $response = \Httpful\Request::get($companies_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $companies = $response->body->companies; echo "

Companies

"; echo "

$companies_url

"; echo "
    "; foreach ($companies as $company) { echo "
  • "; echo $company->shortname; echo "
    • "; } echo "
"; ``` ## Listing items for a company ``` $company = array_values($companies)[0]; $items_url = "$root_url/companies/$company->shortname/items/"; $response = \Httpful\Request::get($items_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $items = $response->body->items; echo "

Items

"; echo "

$items_url

"; echo "
    "; foreach ($items as $item) { echo "
  • "; echo "$item->pk ($item->name)"; echo "
    • "; } echo "
"; ``` ## Listing availabilities for an item ``` $item = array_values($items)[0]; $availabilities_url = "$root_url/companies/$company->shortname/items/$item->pk/availabilities/date/2015-12-01/"; $response = \Httpful\Request::get($availabilities_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $availabilities = $response->body->availabilities; echo "

Availabilities

"; echo "

$availabilities_url

"; echo "
    "; foreach ($availabilities as $availability) { echo "
  • "; echo "$availability->pk ($availability->start_at)"; echo "
    • "; } echo "
"; ``` ## Listing customer type rates for an availability ``` $availability = array_values($availabilities)[0]; $customer_type_rates = $availability->customer_type_rates; echo "

Customer Type Rates

"; echo "

Availability $availability->pk

"; echo "
    "; foreach ($customer_type_rates as $customer_type_rate) { echo "
  • "; echo "$customer_type_rate->pk ({$customer_type_rate->customer_type->plural})"; echo "
    • "; } echo "
"; ``` ## Creating a booking for an availability ``` $customer_type_rate = array_values($customer_type_rates)[0]; $book_url = "$root_url/companies/$company->shortname/availabilities/$availability->pk/bookings/"; $contact = array( "name" => "John Doe", "phone" => "415-098-1234", "email" => "johndoe@gmail.com" ); $customers = array( array("customer_type_rate" => $customer_type_rate->pk) ); $data = array( "contact" => $contact, "customers" => $customers, "note" => "Optional booking note.", "voucher_number" => "V-35791209" ); $body = json_encode($data); $response = \Httpful\Request::post($book_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->sendsJson() ->body($body) ->send(); $booking = $response->body->booking; echo "

Create Booking

"; echo "

$book_url

"; echo "Created booking $booking->uuid"; ``` ## Retrieving a booking ``` $booking_url = "$root_url/companies/$company->shortname/bookings/$booking->uuid/"; $response = \Httpful\Request::get($booking_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $booking = $response->body->booking; echo "

Retrieve Booking

"; echo "

$booking_url

"; echo "Retrieved booking $booking->uuid"; ``` ## Entire script ``` addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $companies = $response->body->companies; echo "

Companies

"; echo "

$companies_url

"; echo "
    "; foreach ($companies as $company) { echo "
  • "; echo $company->shortname; echo "
    • "; } echo "
"; # ITEMS $company = array_values($companies)[0]; $items_url = "$root_url/companies/$company->shortname/items/"; $response = \Httpful\Request::get($items_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $items = $response->body->items; echo "

Items

"; echo "

$items_url

"; echo "
    "; foreach ($items as $item) { echo "
  • "; echo "$item->pk ($item->name)"; echo "
    • "; } echo "
"; # AVAILABILITIES $item = array_values($items)[0]; $availabilities_url = "$root_url/companies/$company->shortname/items/$item->pk/availabilities/date/2015-12-01/"; $response = \Httpful\Request::get($availabilities_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $availabilities = $response->body->availabilities; echo "

Availabilities

"; echo "

$availabilities_url

"; echo "
    "; foreach ($availabilities as $availability) { echo "
  • "; echo "$availability->pk ($availability->start_at)"; echo "
    • "; } echo "
"; # CUSTOMER TYPE RATES $availability = array_values($availabilities)[0]; $customer_type_rates = $availability->customer_type_rates; echo "

Customer Type Rates

"; echo "

Availability $availability->pk

"; echo "
    "; foreach ($customer_type_rates as $customer_type_rate) { echo "
  • "; echo "$customer_type_rate->pk ({$customer_type_rate->customer_type->plural})"; echo "
    • "; } echo "
"; # CREATE BOOKING $customer_type_rate = array_values($customer_type_rates)[0]; $book_url = "$root_url/companies/$company->shortname/availabilities/$availability->pk/bookings/"; $contact = array( "name" => "John Doe", "phone" => "415-098-1234", "email" => "johndoe@gmail.com" ); $customers = array( array("customer_type_rate" => $customer_type_rate->pk) ); $data = array( "contact" => $contact, "customers" => $customers, "voucher_number" => "V-35791209" ); $body = json_encode($data); $response = \Httpful\Request::post($book_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->sendsJson() ->body($body) ->send(); $booking = $response->body->booking; echo "

Create Booking

"; echo "

$book_url

"; echo "Created booking $booking->uuid"; # RETRIEVE BOOKING $booking_url = "$root_url/companies/$company->shortname/bookings/$booking->uuid/"; $response = \Httpful\Request::get($booking_url) ->addHeader("X-FareHarbor-API-App", $api_app) ->addHeader("X-FareHarbor-API-User", $api_user) ->send(); $booking = $response->body->booking; echo "

Retrieve Booking

"; echo "

$booking_url

"; echo "Retrieved booking $booking->uuid"; ?> ``` # Python ### Dependencies The Python json package. import json The Python requests library. Installation instructions: http://docs.python-requests.org/en/latest/user/install/#install import requests ### Request headers APP_KEY = 'your app key' USER_KEY = 'your user key' HEADERS = { 'X-FareHarbor-API-App': APP_KEY, 'X-FareHarbor-API-User': USER_KEY } ### Root URL ROOT_URL = 'https://test.fareharbor.com/api/external/v1' ## Listing companies ``` companies_url = '%s/companies/' % ROOT_URL print(companies_url) response = requests.get(companies_url, headers=HEADERS) response_data = json.loads(response.text) companies = response_data['companies'] for company in companies: print(company) ``` ## Listing items for a company ``` company = companies[0] items_url = '%s/companies/%s/items/' % (ROOT_URL, company['shortname'],) print(items_url) response = requests.get(items_url, headers=HEADERS) response_data = json.loads(response.text) items = response_data['items'] for item in items: print(item) ``` ## Listing availabilities for an item ``` item = items[0] availabilities_url = '%s/companies/%s/items/%i/availabilities/date/2015-12-01/' % ( ROOT_URL, company['shortname'], item['pk'], ) print(availabilities_url) response = requests.get(availabilities_url, headers=HEADERS) response_data = json.loads(response.text) availabilities = response_data['availabilities'] for availability in availabilities: print(availability) ``` ## Listing customer type rates for an availability ``` availability = availabilities[0] customer_type_rates = availability['customer_type_rates'] for customer_type_rate in customer_type_rates: print(customer_type_rate) ``` ## Creating a booking for an availability ``` customer_type_rate = customer_type_rates[0] book_url = '%s/companies/%s/availabilities/%i/bookings/' % ( ROOT_URL, company['shortname'], availability['pk'], ) print(book_url) request_data = { 'contact': { 'name': 'John Doe', 'phone': '415-098-1234', 'email': 'johndoe@gmail.com' }, 'customers': [ { 'customer_type_rate': customer_type_rate['pk'] } ], "note": "Optional booking note.", "voucher_number": "V-35791209" } request_data = json.dumps(request_data) response = requests.post(book_url, data=request_data, headers=HEADERS) response_data = json.loads(response.text) booking = response_data['booking'] print(booking) ``` ## Retrieving a booking ``` booking_url = '%s/companies/%s/bookings/%s/' % ( ROOT_URL, company['shortname'], booking['uuid'], ) print(booking_url) response = requests.get(booking_url, headers=HEADERS) response_data = json.loads(response.text) booking = response_data['booking'] print(booking) ``` ## Entire script ``` import json import requests APP_KEY = 'your app key' USER_KEY = 'your user key' HEADERS = { 'X-FareHarbor-API-App': APP_KEY, 'X-FareHarbor-API-User': USER_KEY } ROOT_URL = 'https://test.fareharbor.com/api/external/v1' # COMPANIES companies_url = '%s/companies/' % ROOT_URL print(companies_url) response = requests.get(companies_url, headers=HEADERS) response_data = json.loads(response.text) companies = response_data['companies'] for company in companies: print(company) # ITEMS company = companies[0] items_url = '%s/companies/%s/items/' % (ROOT_URL, company['shortname'],) print(items_url) response = requests.get(items_url, headers=HEADERS) response_data = json.loads(response.text) items = response_data['items'] for item in items: print(item) # AVAILABILITIES item = items[0] availabilities_url = '%s/companies/%s/items/%i/availabilities/date/2015-12-01/' % ( ROOT_URL, company['shortname'], item['pk'], ) print(availabilities_url) response = requests.get(availabilities_url, headers=HEADERS) response_data = json.loads(response.text) availabilities = response_data['availabilities'] for availability in availabilities: print(availability) # CUSTOMER TYPE RATES availability = availabilities[0] customer_type_rates = availability['customer_type_rates'] for customer_type_rate in customer_type_rates: print(customer_type_rate) # CREATE BOOKING customer_type_rate = customer_type_rates[0] book_url = '%s/companies/%s/availabilities/%i/bookings/' % ( ROOT_URL, company['shortname'], availability['pk'], ) print(book_url) request_data = { 'contact': { 'name': 'John Doe', 'phone': '415-098-1234', 'email': 'johndoe@gmail.com' }, 'customers': [ { 'customer_type_rate': customer_type_rate['pk'] } ], "voucher_number": "V-35791209" } request_data = json.dumps(request_data) response = requests.post(book_url, data=request_data, headers=HEADERS) response_data = json.loads(response.text) booking = response_data['booking'] print(booking) # RETRIEVE BOOKING booking_url = '%s/companies/%s/bookings/%s/' % ( ROOT_URL, company['shortname'], booking['uuid'], ) print(booking_url) response = requests.get(booking_url, headers=HEADERS) response_data = json.loads(response.text) booking = response_data['booking'] print(booking) ``` # Retrieve Bookings ``` #!/usr/bin/env python """Retrieve bookings via FH External API To use this sample script, set the FH_API_APP and FH_API_USER environment variables in your shell. """ import os import requests api_base_url = os.environ.get('FH_API_BASE_URL', 'https://fareharbor.com/api/external/v1/') HEADERS = { 'X-FareHarbor-API-App': os.environ.get('FH_API_APP', ''), 'X-FareHarbor-API-User': os.environ.get('FH_API_USER', ''), } date_ranges = [ ('2023-01-01', '2023-01-08'), ('2023-01-08', '2023-01-15'), # etc. ] def bookings_for_item(company_shortname, item_pk): item_bookings = [] company_url = f'{api_base_url}companies/{company_shortname}/' for first, last in date_ranges: availabilities_url = f'{company_url}items/{item_pk}/minimal/availabilities/date-range/{first}/{last}/?bookable_only=no' print(availabilities_url) availabilities = requests.get(availabilities_url, headers=HEADERS).json()['availabilities'] for availability in availabilities: url = f'{company_url}availabilities/{availability["pk"]}/bookings/' print(url) bookings = requests.get(url, headers=HEADERS).json()['bookings'] print(bookings) item_bookings += bookings return item_bookings all_bookings = [] companies_url = f'{api_base_url}companies/' print(companies_url) companies = requests.get(companies_url, headers=HEADERS).json()['companies'] print(companies) for company in companies: items_url = f'{companies_url}{company["shortname"]}/items/' items = requests.get(items_url, headers=HEADERS).json()['items'] for item in items: all_bookings += bookings_for_item(company['shortname'], item['pk']) print(f'{len(all_bookings)} total bookings') ``` - name: Format description: | # Interchange Format All interactions with the API are done via JSON. # Requests ## Request Body Some requests (particularly the `POST` to create a booking) require a body. The body should consist entirely of a JSON object. ## Authentication You'll need to authenticate every request you make the API; see [authentication](#tag/Authentication). # Responses ## General Structure The body of every response is a valid JSON object (and in particular *not* a JSON array, number, string, and so on). ### Success responses Successful responses contain the data requested. The structure of these responses is described in detail in [data-types](#tag/Data-Types) however in general they follow this structure: * ``: `object` or * ``: `array` Examples: ``` { "company": { "shortname": "hawaiianadventures", "name": "Hawaiian Adventures" } } ``` ``` { "companies": [ { "shortname": "hawaiianadventures", "name": "Hawaiian Adventures" } ] } ``` ### Error responses * `error`: `string` A message describing the error. * `status`: `number` The HTTP status code for the response. Example: { "error": "Method not allowed", "status": 405 } Assuming that `response` contains the entire JSON response, a response is an error when `response.error` is defined; otherwise it is a success. ## HTTP Codes We use the usual HTTP statuses to indicate success: * 200: Succcess * 201: Created A `2xx` response is always indicative of a successful request. We also use HTTP error codes to indicate the usual sorts of errors; the following are the ones you are most likely to encounter. * 400: Bad Request The request was invalid and could not be processed. This is most likely to occur when attempting to create a booking, and can correspond to things like attempting to overbook an availability or providing invalid data like customer name, phone number, etc. * 403: Forbidden You do not have permission to access this endpoint in this way. Review [authentication](#tag/Authentication) and verify that you are sending the correct API keys, and that you do indeed have permission to access to endpoint you are attempting to access. * 404: Not Found The company, item, or availability does not exist; it may have been deleted or otherwise become unavailable, or you may have an incorrect ID. * 405: Method Not Allowed You are trying to use an unsupported HTTP method (`GET`, `POST`, and so on) with this endpoint. * 420: Enhance Your Calm Returned when a request has been rate-limited due to too many concurrent connections. It is *very* unlikely that you will encounter this in normal usage. * 500: Internal Server Error An unexpected error occured. * 503: Service Unavailable FareHarbor is temporarily unavailable, but will return shortly. Try again later. A `4xx` request is always indicative of an problem with the request being made, while a `5xx` error indicates a server-side error. A detailed list of error codes and messages are described in [error-codes](#tag/Error-Codes) - name: Orders description: | Multiple bookings can be grouped into an **Order**. This feature is beneficial for API Partners and Affiliates who want to offer bundled experiences to increase guest satisfaction and revenue. For example, they can allow guests to book multiple activities at once or to create custom packages booking activities one by one. This can increase operational efficiency for activity providers. # General Outline of the Creation of an Order An **Order** represents a bundle of **Bookings**, and every booking is created the same way (whether as part of an order or not), with one crucial difference. In every case, the `POST` **Bookings** endpoint is used (see [Bookings](#tag/Bookings-Endpoints/operation/post-bookings)) following the flow detailed below: 1. Make the first booking. 2. Save the `uuid` field value from the response. 3. From the second booking on, insert the `uuid` value from step 2 into the `orderize_booking` field of the request. 4. Every additional booking will have the same value in the response field `order.display_id`. This is the order id in common to all the bookings making up the order. ### Example Response ``` { "booking": { "affiliate_company": { "currency": "usd", "name": "Test Affiliate", "shortname": "affiliate" }, ... "order": { "display_id": "ABTU" }, ... "source_type": "external-api", "status": "booked", "uuid": "869b0840-80ce-46a6-abf9-4fb12c7d4143", "voucher_number": "V1", "waiver_signatures": {} } } ``` # Requirements 1. Before adding bookings to an order, the charter company offering the availabilities being booked must have Orders enabled in their FareHarbor dashboard under company advanced settings. 1. All availabilities booked under an order must belong to the same charter company. 1. Every booking bundled inside an order will be created for the `contact` passed in the `POST` request for the initial booking. The `contact` in all subsequent booking `POST` requests will be ignored. ### Error Response If the charter company does not have orders enabled, the following error will be returned: ``` {"error":"Orders not allowed","status":403,"code":"orderize-booking-uuid-invalid-error"} ``` # Retrieving an Order The only identifier necessary for retrieving an order is the `uuid` of one of the bookings in the order. Since the `uuid` of the first booking was used when creating the second booking and possibly all the subsequent bookings, the same `uuid` can be used for retrieval, as well. But any of the other bookings' `uuid`s would work, as well. The endpoint used is the normal `GET` [Booking](#tag/Bookings-Endpoints/operation/get-booking). When the booking being retrieved is part of an order, the response will contain the following `related_bookings` data structure: ``` {..., related_bookings: { related_order: { id: AHWS, bookings: [ uuid1, uuid2, ... ], }, }, ... } ``` As this example illustrates, the booking in question belongs to `order_id: AHWS`, and the array of `bookings` below that order lists all the `uuid`s of bookings in the same order. Currently, the API only permits the creation of a single order of related bookings. If the retrieved booking belongs to an order, the `related_bookings` object will contain its `order_id` and a list of bookings. Otherwise, `related_bookings` will be an empty object. - name: Rebooking description: | If it is necessary to change a booking to another date/time or change customer types/count, the booking must be cancelled and a new booking must be created. Rebooking is a shortcut for that process. To rebook an existing booking, specify the existing booking's UUID value for the `rebooking` property when creating a booking. Note: valid values for all properties required by the create booking request must be provided. Example request: $ curl -X POST \ -H "X-FareHarbor-API-App: YOUR-APP-KEY" \ -H "X-FareHarbor-API-User: YOUR-USER-KEY" \ -d \ '{ "rebooking": "d75102be-9732-4523-90a8-c698eff2b983", "contact": { "name": "John Doe", "phone": "+1-415-789-4563", "email": "johndoe@example.com" }, "customers": [ { "customer_type_rate": 65675 }, { "customer_type_rate": 65675 } ], "note": "Optional booking note.", "voucher_number": "V-35791209" }' \ https://fareharbor.com/api/external/v1/companies/hawaiianadventures/availabilities/5796/bookings/ Example response: { "booking": { "pk": 7974877, "uuid": "10414711-3d20-4f4d-8ab3-eeaea26c2be3", "rebooked_from": "d75102be-9732-4523-90a8-c698eff2b983", "status": "booked", ... } The response includes a `rebooked_from` property that provides the source booking's UUID. Bookings that have been rebooked have a "rebooked" status. The `rebooked_to` property provides the UUID of the new booking. Example rebooked booking: { "booking": { "pk": 6876876, "uuid": "d75102be-9732-4523-90a8-c698eff2b983", "rebooked_to": "10414711-3d20-4f4d-8ab3-eeaea26c2be3" "status": "rebooked", ... } ### Cancelling a Rebooked Booking If you create a booking, then rebook it, and then cancel *either the original or the rebooked booking*, you will get the same response: the `Booking` object for the rebooked booking (not the original). Assuming the cancellation succeeds, the `status` of the rebooked booking will become `cancelled`. (The status of the original booking remains `rebooked` even after you have cancelled the rebooked booking.) - name: Webhooks description: | # What is a webhook A webhook is an HTTPS request sent from FareHarbor to a server of your choice as a result of an event. FareHarbor can send webhooks when bookings are created, updated, rebooked, or cancelled, when a contact changes, when a checkin occurs, when items are updated, when crew members are created, updated, or deleted, etc. For ideas about how to use webhooks in concert with the External API, see [FAQ and Best Practices](#tag/FAQ-And-Best-Practices). # Configuring webhooks You can provide two webhook URLs to FareHarbor: one for production webhooks and one for test webhooks. Contact to configure these. (Note: The server for the production webhook URL must have a valid SSL certificate. If it doesn't have one, then the webhook will not be delivered. It is up to you to ensure that your SSL certificates get renewed as needed.) (Note: Companies in demo mode do not trigger webhooks.) Your server should respond to the webhook with an HTTP success response code. If FareHarbor receives an HTTP error response or no response at all, then the webhook will be retried some number of times, with a significant pause between attempts. If FareHarbor detects too many failures (non-200 statuses) within a short period of time, we may deactivate the webhook and contact you. ## Booking notifications When a booking-related event occurs, FareHarbor sends a `POST` request to the webhook URL that you have provided. Depending on how your webhooks are configured, these `POST` requests will be sent for: * all changes to bookings (including creations, modifications, and cancellations); * creations only; or * cancellations only. The body of this request contains an up-to-date JSON representation of the booking. There are four booking data types that can be sent to a webhook: A full set of data contained in the booking fields, as well as optimized versions of each type to reduce the amount of fields, thereby decreasing the amount of data you need to store and process (filter). * **Bookings only** (default setting). The data returned in this data type includes: *Contact Name*, *Phone*, *Email*, *Activity*, *Availability*, *Customer Types*, *Custom Fields*, *Subtotal*, *Tax*, *Total* and *Amount paid* from a booking. Note that payment and refund information is not included with this data type. * **Bookings only (Optimized)**: This data type returns a smaller group of fields as compared to **Bookings only**, in order to improve performance and give you only the data that is of most importance to you. Note that these fields also **do not** include payment or refund information. The following data fields are returned using this data type: *Item*, *Company*, *Contact*, *Availability*, *Customers*, *Custom field values*, *Effective cancellation policy*, *Invoice*, *Receipt*, *Amount paid*, *Agent*, *Desk*, *Status* and *Rebooked*. * **Bookings + payments**: If you want to send payment and refund data, in addition to what is sent with Bookings only, select this type for all bookings fields and including payment information. * **Bookings + payments (Optimized)**: Use this data type when you want to receive a subset of bookings data, as compared to the full **Bookings + payments** output. The data returned for the optimized call will also include payment and refund information. Sending data using an optimized connection can enhance server performance during the API call by filtering out only the most frequently used fields. This will also allow you to more effectively manage only the data that is of interest. * **Create custom booking schema:** This data type allows you to customize what specific booking data will be included. You can update the included booking data for a custom webhook at any time by clicking the webhook’s **Edit** option under the **Webhook** tab. Some of the fields are described [here](#tag/Data-Types). Depending how your webhook is configured and what fields you are allowed to view, there may also be a `payments` property: { "booking": { "pk": 456, "payments": [ { "amount_paid": 1939, "amount_paid_display": "19.39", "created_at": "2020-07-23T14:43:30-1000", "currency": "usd", "initial_amount_paid": 2154, "initial_amount_paid_display": "21.54", "pk": 6234, "refunds": [ { "amount_refunded": 215, "amount_refunded_display": "2.15", "created_at": "2020-07-23T14:43:41-1000", "is_cancelled": false, "pk": 1123 } ], "status": "succeeded", "type": "affiliate", "in_store_payment_type": { "pk": 137, "name": "Cash", "note_label": "Note" }, "in_store_payment_note": "" } ], ... } } When the payment is `type: "in-store"`, the `in_store_payment_type` in the response has the pk, name, and note label of the in-store payment type. The `in_store_payment_note` is the note value entered for that payment (for example, a room number). When the payment is `type: "affiliate"` and the payment is an affiliate in-store payment, the `in_store_payment_type` in the response has the pk of the in-store payment type and may have the name as well. When the payment is not an in-store payment, the `in_store_payment_type` in the response is `null`. ## Item notifications When an item-related event occurs, FareHarbor sends a `POST` request to the webhook URL that you have provided. The body of this request contains a JSON representation of some of the details that will help you identify the item that was updated. For further details on what actually changed on the item, the webhook contains the external API URL and the dashboard URL. * The `external_api_url` found in the JSON can be used by interested parties to make an additional External API call to the particular item which will return the most up to date item information. * The `dashboard_url` found in the JSON can be used to find out what has changed. The activity log can be used to see what has been changed and when. { "item": { "pk": 1867, "name": "Jet Ski Tour", "company": { "name": "Hawaiian Adventures", "shortname": "hawaiianadventures", "currency": "usd" }, "external_api_url": "https://fareharbor.com/api/external/v1/companies/hawaiianadventures/items/1867", "dashboard_url": "https://fareharbor.com/hawaiianadventures/dashboard/items/1867/" } } Contact to have the item webhook turned on for your account. ## Crew member notifications When a crew member-related event occurs, FareHarbor sends a `POST` request to the webhook URL that you have provided. These `POST` requests will be sent for: * crew member creations and modifications; * crew member disabling/enabling; or * crew member deletions. The body of this request contains a JSON representation of the crew member, including the user information, role, and status. { "crew_member": { "pk": 789, "user": { "name": "John Smith", "username": "jsmith" }, "role": { "pk": 12, "short_name": "captain" }, "note": "Experienced captain with 10+ years", "availability_id": 1234, "status": "active" } } Contact to have the crew member webhook turned on for your account. ## Third-party servers If you do not have your own servers, you can use third-party services that receive webhooks on your behalf. ## Failing webhooks If your webhook is functioning normally, it should always return a 200 HTTP status. Sometimes FareHarbor sends a webhook to your server and there is a failure of one sort or another. See [Question: 500s and 40x responses from webhooks](#tag/Webhooks/Webhook-FAQs/Question:-500s-and-40x-responses-from-webhooks) for a discussion of why this might happen and how you can fix it. If FareHarbor detects too many failures (non-200 statuses) within a short period of time, we may deactivate the webhook and contact you. Ultimately, it is your responsibility to make sure that the webhook is working. # Webhook Schemas ## Booking ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "booking": { "$ref": "#/definitions/booking" } }, "required": ["booking"], "additionalProperties": false, "definitions": { "availability": { "type": "object", "properties": { "pk": { "type": "number" }, "start_at": { "type": "string" }, "end_at": { "type": "string" }, "capacity": { "type": "number" }, "minimum_party_size": { "type": ["number", "null"] }, "maximum_party_size": { "type": ["number", "null"] }, "online_booking_status": { "type": "string" }, "headline": { "type": "string" }, "item": { "$ref": "#/definitions/item" }, "customer_type_rates": { "type": "array", "items": { "$ref": "#/definitions/customer_type_rate" } }, "custom_field_instances": { "type": "array", "items": { "$ref": "#/definitions/custom_field_instance" } } }, "required": [ "pk", "start_at", "end_at", "capacity", "minimum_party_size", "maximum_party_size", "online_booking_status", "headline", "item", "customer_type_rates", "custom_field_instances" ], "additionalProperties": false }, "booking": { "type": "object", "properties": { "pk": { "type": "number" }, "uuid": { "type": "string" }, "availability": { "$ref": "#/definitions/availability" }, "company": { "$ref": "#/definitions/company" }, "affiliate_company": { "$ref": "#/definitions/affiliate_company" }, "contact": { "$ref": "#/definitions/contact" }, "customers": { "type": "array", "items": { "$ref": "#/definitions/customer" } }, "invoice_price": { "type": ["number", "null"] }, "invoice_price_display": { "type": ["string", "null"] }, "display_id": { "type": "string" }, "external_id": { "type": "string" }, "order": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "display_id": { "type": "string" } } } ] }, "status": { "type": "string", "enum": ["booked", "cancelled", "rebooked"] }, "rebooked_from": { "type": ["string", "null"] }, "rebooked_to": { "type": ["string", "null"] }, "confirmation_url": { "type": "string" }, "receipt_subtotal": { "type": ["number", "null"] }, "receipt_subtotal_display": { "type": ["string", "null"] }, "receipt_taxes": { "type": ["number", "null"] }, "receipt_taxes_display": { "type": ["string", "null"] }, "receipt_total": { "type": ["number", "null"] }, "receipt_total_display": { "type": ["string", "null"] }, "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "voucher_number": { "type": "string" }, "online_booking_references": { "type": "string" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } }, "note": { "type": "string" }, "note_safe_html": { "type": "string" }, "pickup": { "$ref": "#/definitions/pickup" }, "arrival": { "$ref": "#/definitions/arrival" }, "effective_cancellation_policy": { "$ref": "#/definitions/effective_cancellation_policy" }, "is_eligible_for_cancellation": { "type": "boolean" }, "agent": { "$ref": "#/definitions/agent" }, "desk": { "$ref": "#/definitions/desk" }, "dashboard_url": { "type": "string" }, "external_api_url": { "type": "string" }, "customer_count": { "type": "number" }, "is_subscribed_for_sms_updates": { "type": "boolean" }, "is_follow_up_email_disabled": { "type": "boolean" }, "is_reminder_email_disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "datetime" }, "source_type": { "type": "string", "enum": ["online", "direct", "pos", "reseller", "external-api", "kiosk", "imported", "unkown"], "example": "online" }, "booked_by": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } ] }, "affiliate_metadata": { "$ref": "#/definitions/affiliate_metadata" } }, "required": [ "pk", "uuid", "availability", "contact", "company", "affiliate_company", "customers", "invoice_price", "invoice_price_display", "display_id", "external_id", "order", "status", "rebooked_from", "rebooked_to", "confirmation_url", "voucher_number", "online_booking_references", "receipt_subtotal", "receipt_subtotal_display", "receipt_taxes", "receipt_taxes_display", "receipt_total", "receipt_total_display", "amount_paid", "amount_paid_display", "custom_field_values", "note", "note_safe_html", "pickup", "arrival", "effective_cancellation_policy", "is_eligible_for_cancellation", "agent", "desk", "dashboard_url", "customer_count", "is_subscribed_for_sms_updates", "is_follow_up_email_disabled", "is_reminder_email_disabled", "created_at", "source_type", "booked_by", "affiliate_metadata" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false }, "affiliate_company": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false } ] }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "phone_country": { "type": ["string", "null"] }, "normalized_phone": { "type": "string" }, "language": { "type": "string" }, "email": { "type": "string" }, "is_subscribed_for_email_updates": { "type": "boolean" } }, "required": ["name", "phone", "phone_country", "normalized_phone", "email", "is_subscribed_for_email_updates"], "additionalProperties": false }, "customer": { "type": "object", "properties": { "pk": { "type": "number" }, "checkin_url": { "type": "string" }, "checkin_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/definitions/checkin_status" } ] }, "invoice_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "total_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "customer_type_rate": { "$ref": "#/definitions/customer_type_rate" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } } }, "required": ["pk", "checkin_url", "customer_type_rate", "custom_field_values"], "additionalProperties": false }, "checkin_status": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["pk", "name", "type"], "additionalProperties": false }, "customer_type": { "type": "object", "properties": { "pk": { "type": "number" }, "singular": { "type": "string" }, "plural": { "type": "string" }, "note": { "type": "string" } }, "required": ["pk", "singular", "plural"], "additionalProperties": false }, "customer_prototype": { "type": "object", "properties": { "pk": { "type": "number" }, "display_name": { "type": "string" }, "note": { "type": "string" }, "total": { "type": "number" }, "total_including_tax": { "type": "number" } }, "required": ["pk", "display_name", "note", "total"], "additionalProperties": false }, "customer_type_rate": { "type": "object", "properties": { "pk": { "type": "number" }, "total": { "type": "number" }, "total_including_tax": { "type": "number" }, "capacity": { "type": ["number", "null"] }, "minimum_party_size": { "type": ["number", "null"] }, "maximum_party_size": { "type": ["number", "null"] }, "customer_type": { "$ref": "#/definitions/customer_type" }, "customer_prototype": { "$ref": "#/definitions/customer_prototype" }, "custom_field_instances": { "type": "array", "items": { "$ref": "#/definitions/custom_field_instance" } } }, "required": [ "pk", "total", "capacity", "minimum_party_size", "maximum_party_size", "customer_type", "customer_prototype" ], "additionalProperties": false }, "custom_field": { "type": "object", "properties": { "pk": { "type": "number" }, "type": { "type": "string", "enum": ["yes-no", "short", "long", "extended-option", "count", "multi-campaign", "date"] }, "is_required": { "type": "boolean" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "booking_notes": { "type": "string" }, "booking_notes_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" }, "extended_options": { "type": "array", "items": { "$ref": "#/definitions/extended_option" } } }, "required": [ "pk", "type", "is_required", "description", "description_safe_html", "name", "booking_notes", "booking_notes_safe_html", "offset" ], "additionalProperties": false }, "custom_field_instance": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" } }, "required": ["pk", "custom_field"], "additionalProperties": false }, "custom_field_value": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" }, "name": { "type": "string" }, "value": { "type": "string", "maxLength": 2048 }, "display_value": { "type": "string", "maxLength": 2048 } }, "required": ["pk", "custom_field", "name", "value", "display_value"], "additionalProperties": false }, "extended_option": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" } }, "required": [ "pk", "name", "description", "description_safe_html", "modifier_kind", "modifier_type", "offset", "percentage", "is_always_per_customer", "is_taxable" ], "additionalProperties": false }, "item": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "headline": { "type": "string" }, "primary_location": { "oneOf": [ { "$ref": "#/definitions/primary_location" }, { "type": "null" } ] } }, "required": ["pk", "name", "headline", "primary_location"], "additionalProperties": false }, "pickup": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "map_url": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "name", "description", "description_safe_html", "map_url", "display_text" ], "additionalProperties": false } ] }, "arrival": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "notes": { "type": "string" }, "notes_safe_html": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "notes", "notes_safe_html", "display_text" ], "additionalProperties": false } ] }, "effective_cancellation_policy": { "type": "object", "properties": { "type": { "type": "string" }, "cutoff": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "cutoff" ], "additionalProperties": false }, "agent": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "desk": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "primary_location": { "type": "object", "properties": { "pk": { "type": "number", "format": "int32", "description": "The location's unique ID.", "example": 234234 }, "type": { "type": "string", "description": "The location's type.", "example": "primary" }, "note": { "type": "string", "format": "markdown", "description": "A brief note about this location that can be displayed to end users.", "example": "Next to the blue fence." }, "note_safe_html": { "type": "string", "format": "markdown", "description": "A brief note about this location that can be displayed to end users.", "example": "

Next to the blue fence.

" }, "address": { "$ref": "#/definitions/address", "description": "The location's physical address." }, "longitude": { "oneOf": [ { "type": "number", "example": 21.30 }, { "type": "null" } ], "description": "The location's longitude." }, "latitude": { "oneOf": [ { "type": "number", "example": -157.85 }, { "type": "null" } ], "description": "The location's latitude." }, "google_place_id": { "type": "string", "format": "uuid", "description": "The location's Google Place ID.", "example": "ChIJYZ4srGUSAHwRT1Da4amp3x" }, "tripadvisor_url": { "type": "string", "format": "uri", "description": "The location's TripAdvisor URL.", "example": "https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html" } }, "required": [ "pk", "type", "note", "note_safe_html", "address", "longitude", "latitude", "google_place_id", "tripadvisor_url" ], "additionalProperties": false }, "address": { "type": "object", "properties": { "city": { "type": "string", "example": "Honolulu" }, "country": { "type": "string", "example": "US" }, "postal_code": { "type": "string", "example": "96821" }, "province": { "type": "string", "example": "HI" }, "street": { "type": "string", "example": "123 Wailupe Cir" } }, "required": [ "city", "country", "postal_code", "province", "street" ], "additionalProperties": false }, "waiver_signatures": { "type": "object", "properties": { "fareharbor": { "$ref": "#/definitions/fh_waiver_signatures" } }, "additionalProperties": false }, "fh_waiver_signatures": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johnsmith@example.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "is_marketing_allowed": { "type": "boolean", "description": "Whether the person signing the waiver has opted in for marketing communications.", "example": true }, "is_customer_parent": { "type": "boolean", "description": "Indicating if the signature has any related minor records.", "example": false }, "dob": { "type": ["string", "null"], "example": "1991-01-05" }, "phone_number": { "type": ["string", "null"], "example": "+16468109900" }, "address_line": { "type": ["string", "null"], "example": "7824 15th Ave" }, "city": { "type": ["string", "null"], "example": "Brooklyn" }, "state_province": { "type": ["string", "null"], "example": "NY" }, "postcode": { "type": ["string", "null"], "example": "11228" }, "country": { "type": ["string", "null"], "example": "US" } }, "required": [ "email", "first_name", "last_name", "is_marketing_allowed", "is_customer_parent", "dob", "phone_number", "address_line", "city", "state_province", "postcode", "country" ], "additionalProperties": false }, "description": "A list of FareHarbor waivers signatures with details." }, "affiliate_metadata": { "type": "object", "properties": { "airbnb": { "$ref": "#/definitions/airbnb_metadata" } }, "description": "Metadata from affiliate sources." }, "airbnb_metadata": { "type": "object", "properties": { "activity_id": { "type": ["string", "null"], "description": "The Airbnb activity ID.", "example": "6137649" }, "offering_id": { "type": ["string", "null"], "description": "The Airbnb offering ID.", "example": "5495433" }, "channel_thread_id": { "type": ["string", "null"], "description": "The Airbnb channel thread ID.", "example": "2199079188" }, "guest_id": { "type": ["string", "null"], "description": "The Airbnb guest ID.", "example": "17780410" }, "host_id": { "type": ["string", "null"], "description": "The Airbnb host ID.", "example": "1234" }, "guest_profiles": { "type": ["array", "null"], "items": { "$ref": "#/definitions/airbnb_guest_profile" }, "description": "List of Airbnb guest profiles." } }, "description": "Metadata from Airbnb bookings." }, "airbnb_guest_profile": { "type": "object", "properties": { "direct_thread_id": { "type": ["string", "null"], "description": "The direct thread ID for the guest.", "example": "2164961599" }, "user_id": { "type": ["string", "null"], "description": "The Airbnb user ID.", "example": "17780410" } }, "description": "An Airbnb guest profile." } } } ``` ## Booking with Payments ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "booking": { "$ref": "#/definitions/booking" } }, "required": ["booking"], "additionalProperties": false, "definitions": { "availability": { "type": "object", "properties": { "pk": { "type": "number" }, "start_at": { "type": "string" }, "end_at": { "type": "string" }, "capacity": { "type": "number" }, "minimum_party_size": { "type": ["number", "null"] }, "maximum_party_size": { "type": ["number", "null"] }, "online_booking_status": { "type": "string" }, "headline": { "type": "string" }, "item": { "$ref": "#/definitions/item" }, "customer_type_rates": { "type": "array", "items": { "$ref": "#/definitions/customer_type_rate" } }, "custom_field_instances": { "type": "array", "items": { "$ref": "#/definitions/custom_field_instance" } } }, "required": [ "pk", "start_at", "end_at", "capacity", "minimum_party_size", "maximum_party_size", "online_booking_status", "headline", "item", "customer_type_rates", "custom_field_instances" ], "additionalProperties": false }, "booking": { "type": "object", "properties": { "pk": { "type": "number" }, "uuid": { "type": "string" }, "availability": { "$ref": "#/definitions/availability" }, "company": { "$ref": "#/definitions/company" }, "affiliate_company": { "$ref": "#/definitions/affiliate_company" }, "contact": { "$ref": "#/definitions/contact" }, "customers": { "type": "array", "items": { "$ref": "#/definitions/customer" } }, "invoice_price": { "type": ["number", "null"] }, "invoice_price_display": { "type": ["string", "null"] }, "display_id": { "type": "string" }, "external_id": { "type": "string" }, "order": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "display_id": { "type": "string" } } } ] }, "status": { "type": "string", "enum": ["booked", "cancelled", "rebooked"] }, "rebooked_from": { "type": ["string", "null"] }, "rebooked_to": { "type": ["string", "null"] }, "confirmation_url": { "type": "string" }, "receipt_subtotal": { "type": ["number", "null"] }, "receipt_subtotal_display": { "type": ["string", "null"] }, "receipt_taxes": { "type": ["number", "null"] }, "receipt_taxes_display": { "type": ["string", "null"] }, "receipt_total": { "type": ["number", "null"] }, "receipt_total_display": { "type": ["string", "null"] }, "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "voucher_number": { "type": "string" }, "online_booking_references": { "type": "string" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } }, "note": { "type": "string" }, "note_safe_html": { "type": "string" }, "pickup": { "$ref": "#/definitions/pickup" }, "arrival": { "$ref": "#/definitions/arrival" }, "effective_cancellation_policy": { "$ref": "#/definitions/effective_cancellation_policy" }, "is_eligible_for_cancellation": { "type": "boolean" }, "agent": { "$ref": "#/definitions/agent" }, "desk": { "$ref": "#/definitions/desk" }, "payments": { "type": "array", "items": { "$ref": "#/definitions/payment" } }, "dashboard_url": { "type": "string" }, "external_api_url": { "type": "string" }, "customer_count": { "type": "number" }, "is_subscribed_for_sms_updates": { "type": "boolean" }, "is_follow_up_email_disabled": { "type": "boolean" }, "is_reminder_email_disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "datetime" }, "source_type": { "type": "string", "enum": ["online", "direct", "pos", "reseller", "external-api", "kiosk", "imported", "unkown"], "example": "online" }, "booked_by": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } ] }, "affiliate_metadata": { "$ref": "#/definitions/affiliate_metadata" } }, "required": [ "pk", "uuid", "availability", "contact", "company", "affiliate_company", "customers", "invoice_price", "invoice_price_display", "display_id", "external_id", "order", "status", "rebooked_from", "rebooked_to", "confirmation_url", "voucher_number", "online_booking_references", "receipt_subtotal", "receipt_subtotal_display", "receipt_taxes", "receipt_taxes_display", "receipt_total", "receipt_total_display", "amount_paid", "amount_paid_display", "custom_field_values", "note", "note_safe_html", "pickup", "arrival", "effective_cancellation_policy", "is_eligible_for_cancellation", "agent", "desk", "payments", "dashboard_url", "customer_count", "is_subscribed_for_sms_updates", "is_follow_up_email_disabled", "is_reminder_email_disabled", "created_at", "source_type", "booked_by", "affiliate_metadata" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false }, "affiliate_company": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false } ] }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "phone_country": { "type": ["string", "null"] }, "normalized_phone": { "type": "string" }, "language": { "type": "string" }, "email": { "type": "string" }, "is_subscribed_for_email_updates": { "type": "boolean" } }, "required": ["name", "phone", "phone_country", "normalized_phone", "email", "is_subscribed_for_email_updates"], "additionalProperties": false }, "customer": { "type": "object", "properties": { "pk": { "type": "number" }, "checkin_url": { "type": "string" }, "checkin_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/definitions/checkin_status" } ] }, "invoice_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "total_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "customer_type_rate": { "$ref": "#/definitions/customer_type_rate" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } } }, "required": ["pk", "checkin_url", "customer_type_rate", "custom_field_values"], "additionalProperties": false }, "checkin_status": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["pk", "name", "type"], "additionalProperties": false }, "customer_type": { "type": "object", "properties": { "pk": { "type": "number" }, "singular": { "type": "string" }, "plural": { "type": "string" }, "note": { "type": "string" } }, "required": ["pk", "singular", "plural"], "additionalProperties": false }, "customer_prototype": { "type": "object", "properties": { "pk": { "type": "number" }, "display_name": { "type": "string" }, "note": { "type": "string" }, "total": { "type": "number" }, "total_including_tax": { "type": "number" } }, "required": ["pk", "display_name", "note", "total"], "additionalProperties": false }, "customer_type_rate": { "type": "object", "properties": { "pk": { "type": "number" }, "total": { "type": "number" }, "total_including_tax": { "type": "number" }, "capacity": { "type": ["number", "null"] }, "minimum_party_size": { "type": ["number", "null"] }, "maximum_party_size": { "type": ["number", "null"] }, "customer_type": { "$ref": "#/definitions/customer_type" }, "customer_prototype": { "$ref": "#/definitions/customer_prototype" }, "custom_field_instances": { "type": "array", "items": { "$ref": "#/definitions/custom_field_instance" } } }, "required": [ "pk", "total", "capacity", "minimum_party_size", "maximum_party_size", "customer_type", "customer_prototype" ], "additionalProperties": false }, "custom_field": { "type": "object", "properties": { "pk": { "type": "number" }, "type": { "type": "string", "enum": ["yes-no", "short", "long", "extended-option", "count", "multi-campaign", "date"] }, "is_required": { "type": "boolean" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "booking_notes": { "type": "string" }, "booking_notes_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" }, "extended_options": { "type": "array", "items": { "$ref": "#/definitions/extended_option" } } }, "required": [ "pk", "type", "is_required", "description", "description_safe_html", "name", "booking_notes", "booking_notes_safe_html", "offset" ], "additionalProperties": false }, "custom_field_instance": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" } }, "required": ["pk", "custom_field"], "additionalProperties": false }, "custom_field_value": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" }, "name": { "type": "string" }, "value": { "type": "string", "maxLength": 2048 }, "display_value": { "type": "string", "maxLength": 2048 } }, "required": ["pk", "custom_field", "name", "value", "display_value"], "additionalProperties": false }, "extended_option": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" } }, "required": [ "pk", "name", "description", "description_safe_html", "modifier_kind", "modifier_type", "offset", "percentage", "is_always_per_customer", "is_taxable" ], "additionalProperties": false }, "item": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "headline": { "type": "string" }, "primary_location": { "oneOf": [ { "$ref": "#/definitions/primary_location" }, { "type": "null" } ] } }, "required": ["pk", "name", "headline", "primary_location"], "additionalProperties": false }, "pickup": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "map_url": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "name", "description", "description_safe_html", "map_url", "display_text" ], "additionalProperties": false } ] }, "arrival": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "notes": { "type": "string" }, "notes_safe_html": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "notes", "notes_safe_html", "display_text" ], "additionalProperties": false } ] }, "effective_cancellation_policy": { "type": "object", "properties": { "type": { "type": "string" }, "cutoff": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "cutoff" ], "additionalProperties": false }, "agent": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "desk": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "payment": { "type": "object", "properties": { "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "created_at": { "type": "string", "maxLength": 2048 }, "currency": { "type": "string", "maxLength": 3 }, "initial_amount_paid": { "type": ["number", "null"] }, "initial_amount_paid_display": { "type": ["string", "null"] }, "pk": { "type": "number" }, "refunds": { "type": "array", "items": { "$ref": "#/definitions/refund" } }, "type": { "type": "string", "maxLength": 2048 }, "in_store_payment_type": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string", "maxLength": 128 }, "note_label": { "type": "string", "maxLength": 128 } }, "required": [ "pk", "name", "note_label" ] } ] }, "in_store_payment_note": { "type": ["string", "null"], "maxLength": 128 }, "status": { "type": "string", "maxLength": 2048 } }, "required": [ "amount_paid", "amount_paid_display", "created_at", "currency", "initial_amount_paid", "initial_amount_paid_display", "pk", "refunds", "type", "in_store_payment_type", "in_store_payment_note", "status" ], "additionalProperties": false }, "refund": { "type": "object", "properties": { "amount_refunded": { "type": ["number", "null"] }, "amount_refunded_display": { "type": ["string", "null"] }, "created_at": { "type": "string", "maxLength": 2048 }, "is_cancelled": { "type": "boolean" }, "pk": { "type": "number" } }, "required": ["amount_refunded", "amount_refunded_display", "created_at", "pk"], "additionalProperties": false }, "primary_location": { "type": "object", "properties": { "pk": { "type": "number", "format": "int32", "description": "The location's unique ID.", "example": 234234 }, "type": { "type": "string", "description": "The location's type.", "example": "primary" }, "note": { "type": "string", "format": "markdown", "description": "A brief note about this location that can be displayed to end users.", "example": "Next to the blue fence." }, "note_safe_html": { "type": "string", "format": "markdown", "description": "A brief note about this location that can be displayed to end users.", "example": "

Next to the blue fence.

" }, "address": { "$ref": "#/definitions/address", "description": "The location's physical address." }, "longitude": { "oneOf": [ { "type": "number", "example": 21.3069 }, { "type": "null" } ], "description": "The location's longitude." }, "latitude": { "oneOf": [ { "type": "number", "example": -157.8583 }, { "type": "null" } ], "description": "The location's latitude." }, "google_place_id": { "type": "string", "format": "uuid", "description": "The location's Google Place ID.", "example": "ChIJYZ4srGUSAHwRT1Da4amp3x" }, "tripadvisor_url": { "type": "string", "format": "uri", "description": "The location's TripAdvisor URL.", "example": "https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html" } }, "required": [ "pk", "type", "note", "note_safe_html", "address", "longitude", "latitude", "google_place_id", "tripadvisor_url" ], "additionalProperties": false }, "address": { "type": "object", "properties": { "city": { "type": "string", "example": "Honolulu" }, "country": { "type": "string", "example": "US" }, "postal_code": { "type": "string", "example": "96821" }, "province": { "type": "string", "example": "HI" }, "street": { "type": "string", "example": "123 Wailupe Cir" } }, "required": [ "city", "country", "postal_code", "province", "street" ], "additionalProperties": false }, "waiver_signatures": { "type": "object", "properties": { "fareharbor": { "$ref": "#/definitions/fh_waiver_signatures" } }, "additionalProperties": false }, "fh_waiver_signatures": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johnsmith@example.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "is_marketing_allowed": { "type": "boolean", "description": "Whether the person signing the waiver has opted in for marketing communications.", "example": true }, "is_customer_parent": { "type": "boolean", "description": "Indicating if the signature has any related minor records.", "example": false }, "dob": { "type": ["string", "null"], "example": "1991-01-05" }, "phone_number": { "type": ["string", "null"], "example": "+16468109900" }, "address_line": { "type": ["string", "null"], "example": "7824 15th Ave" }, "city": { "type": ["string", "null"], "example": "Brooklyn" }, "state_province": { "type": ["string", "null"], "example": "NY" }, "postcode": { "type": ["string", "null"], "example": "11228" }, "country": { "type": ["string", "null"], "example": "US" } }, "required": [ "email", "first_name", "last_name", "is_marketing_allowed", "is_customer_parent", "dob", "phone_number", "address_line", "city", "state_province", "postcode", "country" ], "additionalProperties": false }, "description": "A list of FareHarbor waivers signatures with details." }, "affiliate_metadata": { "type": "object", "properties": { "airbnb": { "$ref": "#/definitions/airbnb_metadata" } }, "description": "Metadata from affiliate sources." }, "airbnb_metadata": { "type": "object", "properties": { "activity_id": { "type": ["string", "null"], "description": "The Airbnb activity ID.", "example": "6137649" }, "offering_id": { "type": ["string", "null"], "description": "The Airbnb offering ID.", "example": "5495433" }, "channel_thread_id": { "type": ["string", "null"], "description": "The Airbnb channel thread ID.", "example": "2199079188" }, "guest_id": { "type": ["string", "null"], "description": "The Airbnb guest ID.", "example": "17780410" }, "host_id": { "type": ["string", "null"], "description": "The Airbnb host ID.", "example": "1234" }, "guest_profiles": { "type": ["array", "null"], "items": { "$ref": "#/definitions/airbnb_guest_profile" }, "description": "List of Airbnb guest profiles." } }, "description": "Metadata from Airbnb bookings." }, "airbnb_guest_profile": { "type": "object", "properties": { "direct_thread_id": { "type": ["string", "null"], "description": "The direct thread ID for the guest.", "example": "2164961599" }, "user_id": { "type": ["string", "null"], "description": "The Airbnb user ID.", "example": "17780410" } }, "description": "An Airbnb guest profile." } } } ``` ## Booking Optimized ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "booking": { "$ref": "#/definitions/booking" } }, "required": ["booking"], "additionalProperties": false, "definitions": { "availability": { "type": "object", "properties": { "pk": { "type": "number" }, "item": { "$ref": "#/definitions/item" }, "start_at": { "type": "string" }, "end_at": { "type": "string" } }, "required": [ "pk", "item", "start_at", "end_at" ], "additionalProperties": false }, "booking": { "type": "object", "properties": { "pk": { "type": "number" }, "uuid": { "type": "string" }, "availability": { "$ref": "#/definitions/availability" }, "company": { "$ref": "#/definitions/company" }, "affiliate_company": { "$ref": "#/definitions/affiliate_company" }, "contact": { "$ref": "#/definitions/contact" }, "customers": { "type": "array", "items": { "$ref": "#/definitions/customer" } }, "invoice_price": { "type": ["number", "null"] }, "invoice_price_display": { "type": ["string", "null"] }, "display_id": { "type": "string" }, "external_id": { "type": "string" }, "order": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "display_id": { "type": "string" } } } ] }, "status": { "type": "string", "enum": ["booked", "cancelled", "rebooked"] }, "rebooked_from": { "type": ["string", "null"] }, "rebooked_to": { "type": ["string", "null"] }, "confirmation_url": { "type": "string" }, "receipt_subtotal": { "type": ["number", "null"] }, "receipt_subtotal_display": { "type": ["string", "null"] }, "receipt_taxes": { "type": ["number", "null"] }, "receipt_taxes_display": { "type": ["string", "null"] }, "receipt_total": { "type": ["number", "null"] }, "receipt_total_display": { "type": ["string", "null"] }, "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "voucher_number": { "type": "string" }, "online_booking_references": { "type": "string" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } }, "note": { "type": "string" }, "note_safe_html": { "type": "string" }, "pickup": { "$ref": "#/definitions/pickup" }, "arrival": { "$ref": "#/definitions/arrival" }, "effective_cancellation_policy": { "$ref": "#/definitions/effective_cancellation_policy" }, "is_eligible_for_cancellation": { "type": "boolean" }, "agent": { "$ref": "#/definitions/agent" }, "desk": { "$ref": "#/definitions/desk" }, "dashboard_url": { "type": "string" }, "external_api_url": { "type": "string" }, "customer_count": { "type": "number" }, "is_subscribed_for_sms_updates": { "type": "boolean" }, "is_follow_up_email_disabled": { "type": "boolean" }, "is_reminder_email_disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "datetime" }, "source_type": { "type": "string", "enum": ["online", "direct", "pos", "reseller", "external-api", "kiosk", "imported", "unkown"], "example": "online" }, "booked_by": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } ] }, "affiliate_metadata": { "$ref": "#/definitions/affiliate_metadata" } }, "required": [ "pk", "uuid", "availability", "contact", "company", "affiliate_company", "customers", "invoice_price", "invoice_price_display", "display_id", "external_id", "order", "status", "rebooked_from", "rebooked_to", "confirmation_url", "voucher_number", "online_booking_references", "receipt_subtotal", "receipt_subtotal_display", "receipt_taxes", "receipt_taxes_display", "receipt_total", "receipt_total_display", "amount_paid", "amount_paid_display", "custom_field_values", "note", "note_safe_html", "pickup", "arrival", "effective_cancellation_policy", "is_eligible_for_cancellation", "agent", "desk", "dashboard_url", "customer_count", "is_subscribed_for_sms_updates", "is_follow_up_email_disabled", "is_reminder_email_disabled", "created_at", "source_type", "booked_by", "affiliate_metadata" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false }, "affiliate_company": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false } ] }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "phone_country": { "type": ["string", "null"] }, "normalized_phone": { "type": "string" }, "language": { "type": "string" }, "email": { "type": "string" }, "is_subscribed_for_email_updates": { "type": "boolean" } }, "required": ["name", "phone", "phone_country", "normalized_phone", "email", "is_subscribed_for_email_updates"], "additionalProperties": false }, "customer": { "type": "object", "properties": { "pk": { "type": "number" }, "checkin_url": { "type": "string" }, "checkin_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/definitions/checkin_status" } ] }, "invoice_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "total_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "customer_type_rate": { "$ref": "#/definitions/customer_type_rate" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } } }, "required": ["pk", "checkin_url", "customer_type_rate", "custom_field_values"], "additionalProperties": false }, "checkin_status": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["pk", "name", "type"], "additionalProperties": false }, "customer_type": { "type": "object", "properties": { "pk": { "type": "number" }, "singular": { "type": "string" }, "plural": { "type": "string" } }, "required": ["pk", "singular", "plural"], "additionalProperties": false }, "customer_prototype": { "type": "object", "properties": { "pk": { "type": "number" }, "display_name": { "type": "string" } }, "required": ["pk", "display_name"], "additionalProperties": false }, "customer_type_rate": { "type": "object", "properties": { "pk": { "type": "number" }, "customer_type": { "$ref": "#/definitions/customer_type" }, "customer_prototype": { "$ref": "#/definitions/customer_prototype" } }, "required": [ "pk", "customer_type", "customer_prototype" ], "additionalProperties": false }, "custom_field": { "type": "object", "properties": { "pk": { "type": "number" }, "type": { "type": "string", "enum": ["yes-no", "short", "long", "extended-option", "count", "multi-campaign", "date"] }, "is_required": { "type": "boolean" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "booking_notes": { "type": "string" }, "booking_notes_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" } }, "required": [ "pk", "type", "is_required", "description", "description_safe_html", "name", "booking_notes", "booking_notes_safe_html", "offset" ], "additionalProperties": false }, "custom_field_instance": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" } }, "required": ["pk", "custom_field"], "additionalProperties": false }, "custom_field_value": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" }, "name": { "type": "string" }, "value": { "type": "string", "maxLength": 2048 }, "display_value": { "type": "string", "maxLength": 2048 } }, "required": ["pk", "custom_field", "name", "value", "display_value"], "additionalProperties": false }, "item": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": ["pk", "name"], "additionalProperties": false }, "pickup": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "map_url": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "name", "description", "description_safe_html", "map_url", "display_text" ], "additionalProperties": false } ] }, "arrival": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "notes": { "type": "string" }, "notes_safe_html": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "notes", "notes_safe_html", "display_text" ], "additionalProperties": false } ] }, "effective_cancellation_policy": { "type": "object", "properties": { "type": { "type": "string" }, "cutoff": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "cutoff" ], "additionalProperties": false }, "agent": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "desk": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "waiver_signatures": { "type": "object", "properties": { "fareharbor": { "$ref": "#/definitions/fh_waiver_signatures" } }, "additionalProperties": false }, "fh_waiver_signatures": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johnsmith@example.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "is_marketing_allowed": { "type": "boolean", "description": "Whether the person signing the waiver has opted in for marketing communications.", "example": true }, "is_customer_parent": { "type": "boolean", "description": "Indicating if the signature has any related minor records.", "example": false }, "dob": { "type": ["string", "null"], "example": "1991-01-05" }, "phone_number": { "type": ["string", "null"], "example": "+16468109900" }, "address_line": { "type": ["string", "null"], "example": "7824 15th Ave" }, "city": { "type": ["string", "null"], "example": "Brooklyn" }, "state_province": { "type": ["string", "null"], "example": "NY" }, "postcode": { "type": ["string", "null"], "example": "11228" }, "country": { "type": ["string", "null"], "example": "US" } }, "required": [ "email", "first_name", "last_name", "is_marketing_allowed", "is_customer_parent", "dob", "phone_number", "address_line", "city", "state_province", "postcode", "country" ], "additionalProperties": false }, "description": "A list of FareHarbor waivers signatures with details." }, "affiliate_metadata": { "type": "object", "properties": { "airbnb": { "$ref": "#/definitions/airbnb_metadata" } }, "description": "Metadata from affiliate sources." }, "airbnb_metadata": { "type": "object", "properties": { "activity_id": { "type": ["string", "null"], "description": "The Airbnb activity ID.", "example": "6137649" }, "offering_id": { "type": ["string", "null"], "description": "The Airbnb offering ID.", "example": "5495433" }, "channel_thread_id": { "type": ["string", "null"], "description": "The Airbnb channel thread ID.", "example": "2199079188" }, "guest_id": { "type": ["string", "null"], "description": "The Airbnb guest ID.", "example": "17780410" }, "host_id": { "type": ["string", "null"], "description": "The Airbnb host ID.", "example": "1234" }, "guest_profiles": { "type": ["array", "null"], "items": { "$ref": "#/definitions/airbnb_guest_profile" }, "description": "List of Airbnb guest profiles." } }, "description": "Metadata from Airbnb bookings." }, "airbnb_guest_profile": { "type": "object", "properties": { "direct_thread_id": { "type": ["string", "null"], "description": "The direct thread ID for the guest.", "example": "2164961599" }, "user_id": { "type": ["string", "null"], "description": "The Airbnb user ID.", "example": "17780410" } }, "description": "An Airbnb guest profile." } } } ``` ## Booking Optimized with Payments ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "booking": { "$ref": "#/definitions/booking" } }, "required": ["booking"], "additionalProperties": false, "definitions": { "availability": { "type": "object", "properties": { "pk": { "type": "number" }, "item": { "$ref": "#/definitions/item" }, "start_at": { "type": "string" }, "end_at": { "type": "string" } }, "required": [ "pk", "item", "start_at", "end_at" ], "additionalProperties": false }, "booking": { "type": "object", "properties": { "pk": { "type": "number" }, "uuid": { "type": "string" }, "availability": { "$ref": "#/definitions/availability" }, "company": { "$ref": "#/definitions/company" }, "affiliate_company": { "$ref": "#/definitions/affiliate_company" }, "contact": { "$ref": "#/definitions/contact" }, "customers": { "type": "array", "items": { "$ref": "#/definitions/customer" } }, "invoice_price": { "type": ["number", "null"] }, "invoice_price_display": { "type": ["string", "null"] }, "display_id": { "type": "string" }, "external_id": { "type": "string" }, "order": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "display_id": { "type": "string" } } } ] }, "status": { "type": "string", "enum": ["booked", "cancelled", "rebooked"] }, "rebooked_from": { "type": ["string", "null"] }, "rebooked_to": { "type": ["string", "null"] }, "confirmation_url": { "type": "string" }, "receipt_subtotal": { "type": ["number", "null"] }, "receipt_subtotal_display": { "type": ["string", "null"] }, "receipt_taxes": { "type": ["number", "null"] }, "receipt_taxes_display": { "type": ["string", "null"] }, "receipt_total": { "type": ["number", "null"] }, "receipt_total_display": { "type": ["string", "null"] }, "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "voucher_number": { "type": "string" }, "online_booking_references": { "type": "string" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } }, "note": { "type": "string" }, "note_safe_html": { "type": "string" }, "pickup": { "$ref": "#/definitions/pickup" }, "arrival": { "$ref": "#/definitions/arrival" }, "effective_cancellation_policy": { "$ref": "#/definitions/effective_cancellation_policy" }, "is_eligible_for_cancellation": { "type": "boolean" }, "agent": { "$ref": "#/definitions/agent" }, "desk": { "$ref": "#/definitions/desk" }, "payments": { "type": "array", "items": { "$ref": "#/definitions/payment" } }, "dashboard_url": { "type": "string" }, "external_api_url": { "type": "string" }, "customer_count": { "type": "number" }, "is_subscribed_for_sms_updates": { "type": "boolean" }, "is_follow_up_email_disabled": { "type": "boolean" }, "is_reminder_email_disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "datetime" }, "source_type": { "type": "string", "enum": ["online", "direct", "pos", "reseller", "external-api", "kiosk", "imported", "unkown"], "example": "online" }, "booked_by": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } ] }, "affiliate_metadata": { "$ref": "#/definitions/affiliate_metadata" } }, "required": [ "pk", "uuid", "availability", "contact", "company", "affiliate_company", "customers", "invoice_price", "invoice_price_display", "display_id", "external_id", "order", "status", "rebooked_from", "rebooked_to", "confirmation_url", "voucher_number", "online_booking_references", "receipt_subtotal", "receipt_subtotal_display", "receipt_taxes", "receipt_taxes_display", "receipt_total", "receipt_total_display", "amount_paid", "amount_paid_display", "custom_field_values", "note", "note_safe_html", "pickup", "arrival", "effective_cancellation_policy", "is_eligible_for_cancellation", "agent", "desk", "payments", "dashboard_url", "customer_count", "is_subscribed_for_sms_updates", "is_follow_up_email_disabled", "is_reminder_email_disabled", "created_at", "source_type", "booked_by", "affiliate_metadata" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false }, "affiliate_company": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "shortname": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "shortname", "name", "currency" ], "additionalProperties": false } ] }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "phone_country": { "type": ["string", "null"] }, "normalized_phone": { "type": "string" }, "language": { "type": "string" }, "email": { "type": "string" }, "is_subscribed_for_email_updates": { "type": "boolean" } }, "required": ["name", "phone", "phone_country", "normalized_phone", "email", "is_subscribed_for_email_updates"], "additionalProperties": false }, "customer": { "type": "object", "properties": { "pk": { "type": "number" }, "checkin_url": { "type": "string" }, "checkin_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/definitions/checkin_status" } ] }, "invoice_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "total_cost": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "feeable": { "type": "number" }, "price": { "type": ["number", "null"] }, "tax": { "type": "number" }, "tax_by_type": { "type": "object" }, "taxable": { "type": "number" }, "total": { "type": "number" } } } ] }, "customer_type_rate": { "$ref": "#/definitions/customer_type_rate" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/custom_field_value" } } }, "required": ["pk", "checkin_url", "customer_type_rate", "custom_field_values"], "additionalProperties": false }, "checkin_status": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["pk", "name", "type"], "additionalProperties": false }, "customer_type": { "type": "object", "properties": { "pk": { "type": "number" }, "singular": { "type": "string" }, "plural": { "type": "string" } }, "required": ["pk", "singular", "plural"], "additionalProperties": false }, "customer_prototype": { "type": "object", "properties": { "pk": { "type": "number" }, "display_name": { "type": "string" } }, "required": ["pk", "display_name"], "additionalProperties": false }, "customer_type_rate": { "type": "object", "properties": { "pk": { "type": "number" }, "customer_type": { "$ref": "#/definitions/customer_type" }, "customer_prototype": { "$ref": "#/definitions/customer_prototype" } }, "required": [ "pk", "customer_type", "customer_prototype" ], "additionalProperties": false }, "custom_field": { "type": "object", "properties": { "pk": { "type": "number" }, "type": { "type": "string", "enum": ["yes-no", "short", "long", "extended-option", "count", "multi-campaign", "date"] }, "is_required": { "type": "boolean" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "booking_notes": { "type": "string" }, "booking_notes_safe_html": { "type": "string" }, "modifier_kind": { "type": "string" }, "modifier_type": { "type": "string" }, "offset": { "type": "number" }, "percentage": { "type": "number" }, "is_always_per_customer": { "type": "boolean" }, "is_taxable": { "type": "boolean" } }, "required": [ "pk", "type", "is_required", "description", "description_safe_html", "name", "booking_notes", "booking_notes_safe_html", "offset" ], "additionalProperties": false }, "custom_field_instance": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" } }, "required": ["pk", "custom_field"], "additionalProperties": false }, "custom_field_value": { "type": "object", "properties": { "pk": { "type": "number" }, "custom_field": { "$ref": "#/definitions/custom_field" }, "name": { "type": "string" }, "value": { "type": "string", "maxLength": 2048 }, "display_value": { "type": "string", "maxLength": 2048 } }, "required": ["pk", "custom_field", "name", "value", "display_value"], "additionalProperties": false }, "item": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": ["pk", "name"], "additionalProperties": false }, "pickup": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "description_safe_html": { "type": "string" }, "map_url": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "name", "description", "description_safe_html", "map_url", "display_text" ], "additionalProperties": false } ] }, "arrival": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "time": { "type": "string" }, "notes": { "type": "string" }, "notes_safe_html": { "type": "string" }, "display_text": { "type": "string" } }, "required": [ "time", "notes", "notes_safe_html", "display_text" ], "additionalProperties": false } ] }, "effective_cancellation_policy": { "type": "object", "properties": { "type": { "type": "string" }, "cutoff": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "cutoff" ], "additionalProperties": false }, "agent": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "desk": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" } }, "required": [ "pk", "name" ], "additionalProperties": false } ] }, "payment": { "type": "object", "properties": { "amount_paid": { "type": ["number", "null"] }, "amount_paid_display": { "type": ["string", "null"] }, "created_at": { "type": "string", "maxLength": 2048 }, "currency": { "type": "string", "maxLength": 3 }, "initial_amount_paid": { "type": ["number", "null"] }, "initial_amount_paid_display": { "type": ["string", "null"] }, "pk": { "type": "number" }, "refunds": { "type": "array", "items": { "$ref": "#/definitions/refund" } }, "type": { "type": "string", "maxLength": 2048 }, "in_store_payment_type": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string", "maxLength": 128 } }, "required": [ "pk", "name" ] } ] }, "status": { "type": "string", "maxLength": 2048 } }, "required": [ "amount_paid", "amount_paid_display", "created_at", "currency", "initial_amount_paid", "initial_amount_paid_display", "pk", "refunds", "type", "in_store_payment_type", "status" ], "additionalProperties": false }, "refund": { "type": "object", "properties": { "amount_refunded": { "type": ["number", "null"] }, "amount_refunded_display": { "type": ["string", "null"] }, "created_at": { "type": "string", "maxLength": 2048 }, "is_cancelled": { "type": "boolean" }, "pk": { "type": "number" } }, "required": ["amount_refunded", "amount_refunded_display", "created_at", "pk"], "additionalProperties": false }, "waiver_signatures": { "type": "object", "properties": { "fareharbor": { "$ref": "#/definitions/fh_waiver_signatures" } }, "additionalProperties": false }, "fh_waiver_signatures": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "johnsmith@example.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "is_marketing_allowed": { "type": "boolean", "description": "Whether the person signing the waiver has opted in for marketing communications.", "example": true }, "is_customer_parent": { "type": "boolean", "description": "Indicating if the signature has any related minor records.", "example": false }, "dob": { "type": ["string", "null"], "example": "1991-01-05" }, "phone_number": { "type": ["string", "null"], "example": "+16468109900" }, "address_line": { "type": ["string", "null"], "example": "7824 15th Ave" }, "city": { "type": ["string", "null"], "example": "Brooklyn" }, "state_province": { "type": ["string", "null"], "example": "NY" }, "postcode": { "type": ["string", "null"], "example": "11228" }, "country": { "type": ["string", "null"], "example": "US" } }, "required": [ "email", "first_name", "last_name", "is_marketing_allowed", "is_customer_parent", "dob", "phone_number", "address_line", "city", "state_province", "postcode", "country" ], "additionalProperties": false }, "description": "A list of FareHarbor waivers signatures with details." }, "affiliate_metadata": { "type": "object", "properties": { "airbnb": { "$ref": "#/definitions/airbnb_metadata" } }, "description": "Metadata from affiliate sources." }, "airbnb_metadata": { "type": "object", "properties": { "activity_id": { "type": ["string", "null"], "description": "The Airbnb activity ID.", "example": "6137649" }, "offering_id": { "type": ["string", "null"], "description": "The Airbnb offering ID.", "example": "5495433" }, "channel_thread_id": { "type": ["string", "null"], "description": "The Airbnb channel thread ID.", "example": "2199079188" }, "guest_id": { "type": ["string", "null"], "description": "The Airbnb guest ID.", "example": "17780410" }, "host_id": { "type": ["string", "null"], "description": "The Airbnb host ID.", "example": "1234" }, "guest_profiles": { "type": ["array", "null"], "items": { "$ref": "#/definitions/airbnb_guest_profile" }, "description": "List of Airbnb guest profiles." } }, "description": "Metadata from Airbnb bookings." }, "airbnb_guest_profile": { "type": "object", "properties": { "direct_thread_id": { "type": ["string", "null"], "description": "The direct thread ID for the guest.", "example": "2164961599" }, "user_id": { "type": ["string", "null"], "description": "The Airbnb user ID.", "example": "17780410" } }, "description": "An Airbnb guest profile." } } } ``` ## Item ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "item": { "$ref": "#/definitions/item" } }, "required": ["item"], "additionalProperties": false, "definitions": { "item": { "type": "object", "properties": { "pk": { "type": "number" }, "name": { "type": "string" }, "company": { "$ref": "#/definitions/company" }, "external_api_url": { "type": "string" }, "dashboard_url": { "type": "string" } }, "required": [ "pk", "name", "company", "external_api_url", "dashboard_url" ] }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "shortname": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "name", "shortname", "currency" ] } } } ``` ## Crew Member ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "crew_member": { "$ref": "#/definitions/crew_member" } }, "required": ["crew_member"], "additionalProperties": false, "definitions": { "crew_member": { "type": "object", "properties": { "pk": { "type": "number" }, "user": { "$ref": "#/definitions/user" }, "role": { "$ref": "#/definitions/role" }, "note": { "type": "string" }, "availability_id": { "type": "number" }, "status": { "type": "string" } }, "required": [ "pk", "user", "role", "note", "availability_id", "status" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "name": { "type": "string" }, "username": { "type": "string" } }, "required": ["name", "username"], "additionalProperties": false }, "role": { "type": "object", "properties": { "pk": { "type": "number" }, "short_name": { "type": "string" } }, "required": ["pk", "short_name"], "additionalProperties": false } } } ``` # FH Webhook Best Practices This section describes some best practices for integrating with FH using webhooks and APIs. ## Consider using Zapier, or a similar service. Before writing software to integrate with FareHarbor webhooks, look into using Zapier or something similar. In many cases, doing an integration this way will be quicker, easier, more reliable, and less expensive than doing it yourself with your own servers and custom software. In order to integrate with the FareHarbor webhooks and/or API directly, without using Zapier or the like, you will need time from experienced software engineers. If you do not have them on staff, you may need to contract them and manage them. This is not always easy. ## The data model ### The Booking UUID The most important field in the booking schema is the "uuid" field. IF YOU RECEIVE TWO WEBHOOKS WITH THE SAME UUID, THEY ARE TALKING ABOUT THE SAME BOOKING. This is the most important thing to understand about bookings. You will likely receive multiple webhooks for the same booking. For instance, you will receive one when it's created, and you may receive another if the contact information is updated, or if a customer checkin occurs. For any given uuid, the most recent webhook received will contain the most up-to-date data. You can always retrieve the most recent details for a booking using the Retrive Bookings endpoint, [Bookings](#tag/Bookings-Endpoints): GET /companies//bookings// ### The Customer PK Another important field is the "customers" field. This field contains a list of customers. Each customer will have its own "pk". The PK is a globally-unique identifier for the customer. The details of a booking may change, but as long as it is not rebooked, the customer PK will not change, and can be used as an ID within your system, directly or indirectly. If you receive a webhook from FareHarbor for a booking that is already recorded in your system, this new webhook may contain updated information. Using the PK, you can check each customer's data to see if any piece of that customer's data has changed--the contents of a custom field, for instance. When a rebooking occurs, customer PKs are reassigned. For most practical purposes, you can treat a rebooking event the same as cancellation of the old booking and creation of the new booking. Data associated with the old booking are no longer relevant. ## Retrieving All Existing Bookings Using the External API, it is possible to retrieve all existing bookings. In pseudocode, it looks like this: retrieve a list of companies via the [Companies endpoint](#tag/Company-Endpoints) for each company, retrieve a list of items via the [Items endpoint](#tag/Items-Endpoints) for each item, retrieve lists of availabilities via the [Availabilities endpoint](#tag/Availabilities-Endpoints) (use bookable_only=no) for each availability, retrieve a list of bookings via the [Availability Bookings endpoint](#tag/Bookings-Endpoints/operation/get-bookings) There is sample python code to retrieve all bookings [here](#tag/Examples/Retrieve-Bookings). # Webhook FAQs ## Question: Webhook return status I am implementing a webhook receiver on my server. What HTTP status should it return? ### Answer Your webhook receiver should always return a 200 status, to acknowledge that the payload was received and understood. If it does not return a 200 status, then FareHarbor may resend the webhook some number of times, and if there is still no 200, FareHarbor will interpret this to mean that your webhook receiver is misconfigured or malfunctioning in some way. If this happens too often, FareHarbor might deactivate your webhook. See [Failing Webhooks](#tag/Webhooks/Configuring-webhooks/Failing-webhooks) This is standard practice for webhooks. This is not REST. ## Question: 500s and 40x responses from webhooks I have FareHarbor webhooks configured. I am seeing things in my FareHarbor dashboard that indicate that the webhooks are failing with error status (500 or 400-something). The message says: Error: request unsuccessful: 500 Server Error: Internal Server Error for url: https://my.webhook.url/ (or something like that). What should I do? ### Answer First, it is important to understand that these HTTP status codes are generated by the RECEIVING server (i.e., your server, or whatever server is named in the "Webhook URL" configuration on your dashboard). These status codes are being returned TO the FareHarbor server, which is recording them and showing them to you on the booking page. A 500 response indicates that FareHarbor sent a webhook, but the receiving server experienced an unexpected fatal error--informally, it "crashed". To resolve this, contact the person who is responsible for your server, and ask them to look through the server logs around the time that webhook was sent. This should provide some clues about the problem. A 40x response indicates that the receiving server did not like the data for some reason. Maybe the authentication was improper, or some fields were missing that it was expecting, or the webhook URL was incorrect on the FareHarbor dashboard. If the server returns a 405 response ("Method Not Allowed"), it means that it was not prepared to handle a POST request. FareHarbor always uses POST for webhooks. Please check your server configuration and code and ensure that it is preapred to receive POSTs (and not just GETs, for instance). In either case (500 or a 40x), it is up to folks on your side to resolve the problem. It may require a reconfiguration or modification of your server software. Also, ensure that your server's SSL certificate has not expired, and that is valid for the URL in your webhook URL. It is unlikely that the problem lies with FareHarbor. As a general policy, FareHarbor does not make changes to the API and webhooks that would break existing partner implementations. In order to debug problems with webhooks, you may want to cause the webhook to be resent. See below for how to do that. ## Question: Missed webhook for specific booking I missed a webhook for a specific booking. Maybe the webhook was sent, but it received a 400 or 500 response. Or maybe it seems like the webhook was never sent. What can I do? ### Answer The easiest way to resend a webhook for a specific booking is to change something insignificant on the booking in question. Changing the booking note is often a good choice. The webhook should be resent shortly after any change to the booking. If the webhook received a 500 before and if it receives a 500 again, then your server software likely needs to be modified or reconfigured. Please talk to your technical staff. If the webhook receives a 40x, then check that the webhook URL is correct, and confirm that certificates, security keys, etc. are in place. ## Question: Missed bookings FareHarbor failed to send me webhooks for some bookings, rebookings, and/or cancellations, but I don't know which ones. What should I do? ### Answer FareHarbor tries very hard to send webhooks for new or changed bookings. If FareHarbor fails on the first attempt, it will retry repeatedly over some window of time. If the server RECEIVING the webhooks (your server) is down for a long time for some reason, there is a chance that the webhooks won't be delivered. In this case, the missing bookings can be retrieved using the Availability Bookings endpoint, which allows you to retieve a list of all bookings for a particular Availability. See [Availability bookings](#tag/Bookings-Endpoints/operation/get-bookings). If you need more details than are provided by this endpoint, then you can call the Retrieve Booking Endpoint to retrieve the full details for each booking. ## Question: Duplicate webhooks I receive each webhook TWICE, or more. ### Answer Is it possible that you have multiple api keys configured to send webhooks? Beyond that: A wide variety of events on the FareHarbor side trigger webhooks. Some examples include changes to contact details, check-ins, text message reminders sent, and so on. Many of these may not be relevant to your particular integration. Each webhook contains complete data about the booking. You may receive multiple identical or nearly ideantical webhooks for the same booking. This may happen occasionally or regularly. This is normal. Your software must be prepared to receive identical webhooks without malfunctioning. Keep reading to learn how to know how to handle this situation and stay in sync with the bookings that exist in the FareHarbor system. ## Question: Webhook security How can I guarantee that the webhook we receive is from FareHarbor, and not from someone else who somehow guessed the URL? ### Answer #### Choose a hard-to-guess path or query parameter You are free to use whatever path you like in the webhook address you provide to FareHarbor. For instance, if you use: https://mycompany.com/EE5746FDB4054852/fareharbor-webhook/ then it will be very hard to guess. Or if you prefer, you can use something like https://mycompany.com/fareharbor-webhook/?key=EE5746FDB4054852 and check that you receive the expected query parameter. #### Call the External API to verify booking data *NOTE: External API access is granted on a on a case by case basis. To request access please contact your Account Manager or [FareHarbor Support](https://fareharbor.com/help/).* Another security strategy: Whenever you receive a webhook, call the Retrieve Booking Endpoint of the External API to retrieve the booking data: [Retrieve booking endpoint](#tag/Bookings-Endpoints/operation/get-booking). Then use the retrieved data rather than the webhook payload data. This eliminates the potential negative impact of any "forged" webhook. So even if someone does ascertain your webhook URL, they will not be able to compromise your data integrity. #### Incoroprating authorization headers into the webhook FareHarbor does not provide a way to incorporate custom headers into the webhook that is sent. If you wish to use a shared secret to increase security, the secret can be included in the webhook URL itself, either as part of the path or as a query parameter (see [above](#tag/Webhooks/Webhook-FAQs/Question:-Webhook-security)). #### Using IP address-based ACLs or allowlists to validate the source of webhooks Because FareHarbor uses distributed cloud computing, our servers' IP addresses may change at any moment without notice. Therefore **we do not recommend that our partners use ACLs or allowlists for security**. ## Question: Integrating FareHarbor webhooks with third-party APIs We use a CRM that has a public API. Can FareHarbor integrate with that CRM? Or with other third-party public APIs? Is there some way that I can plug FareHarbor webhooks into other people's APIs? ### Answer The easiest way to plug FareHarbor webhooks into other people's APIs is using Zapier, or a similar service. Zapier, for instance, was created for exactly this purpose, and allows FareHarbor to connect to 5000+ other services: https://zapier.com/apps/fareharbor/integrations If the service you need (your CRM or whatever) is not on this list, that means that they do not work with Zapier. Consider contacting them and asking them to integrate with Zapier. See below for more about Zapier. ## Question: Online Booking Statuses What are online bookings statuses? ### Answer Online Booking Status: Each availability has an online booking status, which controls how it can be viewed and booked by online customers. In most cases, the status will be set to `auto`, which automatically prevents online customers from booking after a certain time cutoff, based on [item’s settings](https://help.fareharbor.com/dashboard/items/online-booking-settings/). The other statuses include `open`, `call`, `closed`, `cancelled`. These statuses are included in the **Bookings only** and **Booking + payments** webhooks. For a complete description of these statuses and their meaning, go to [https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/](https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/). - name: FAQ And Best Practices description: | ## Question: Slow `/availabilities/date-range/` endpoint The Availabilities Date Range endpoint takes too long to return, or times out and never returns. What should I do? ### Answer There are a couple of things you can do: 1. BE SURE YOU ARE USING THE MINIMAL AVAILABILITIES ENDPOINT. This is the one described in the documentation: [Availabilities Endpoint](#tag/Availabilities-Endpoints) `GET /companies//items//minimal/availabilities/date-range///` Make sure the endpoint path contains the word `minimal`. Other versions of this endpoint are much slower, and are no longer supported for new connections. 2. DECREASE THE DATE RANGE for which you are requesting availability data. We recommend the following guidelines: * For 90 days, pull in 7 day increments once per week. * For 30 days, pull in 7 day increments once per day. * For current day, pull every 2 hours. ## Question: How Do I Find Availabilities For A Certain Date? ### Answer To find availabilities for a certain date using the FareHarbor API, follow these steps: #### Step 1: Obtain API Credentials Ensure you have your API credentials (App key and User key) ready, as you will need them to authenticate your requests. #### Step 2: Identify the Item Before checking availability, you need to know the specific item (activity or service) for which you want to check availability. You can retrieve a list of items using the [`/items`](#tag/Items-Endpoints/operation/get-items) endpoint. #### Step 3: Make an API Request for Availability Use the [availabilities](#tag/Availabilities-Endpoints/operation/get-minimal-availabilities-by-date) endpoint to check availability for a specific item on a certain date. The request format is as follows: **Example API Request** ``` curl -X GET 'https://fareharbor.com/api/external/v1/companies/{company_id}/minimal/items/{item_id}/availabilities/date/{date}/' \ -H "X-FareHarbor-API-App: APP-KEY" \ -H "X-FareHarbor-API-User: USER-KEY" ``` Replace the following placeholders: * `{shortname}`: The ID of the company that offers the item. * `{item.pk}`: The ID of the item you are checking availability for. * `{date}`: The date you want to check availability for, formatted as `YYYY-MM-DD`. * `APP-KEY`: Your FareHarbor App key. * `USER-KEY`: Your FareHarbor User key. #### Step 4: Analyze the Response The response will contain availability information for the specified item on the given date. Here’s an example of what the response might look like: ``` { "availabilities": [ { "start_time": "2022-12-15T09:00:00Z", "end_time": "2022-12-15T11:00:00Z", }, { "start_time": "2022-12-15T13:00:00Z", "end_time": "2022-12-15T15:00:00Z", } ] } ``` This indicates the available time slots and the number of spots left for each time slot. #### Step 5: Handle Errors Make sure to handle any potential errors in your API request, such as invalid item IDs, company IDs, or dates. Check the response status codes to ensure the request was successful. ## Question: 403 from FareHarbor External API I am calling the FareHarbor External API. FareHarbor is responding with a "403 Forbidden". How can I fix this? ### Answer Double-check that you are using the right keys in your API call. ## Question: Cancelling rebooked bookings Say I create booking A, then I rebook it to booking B, then I want to cancel the booking. When cancelling via API, should I cancel booking A or booking B? ### Answer Cancelling either one via API will cause FareHarbor to cancel the booking. Regardless of which you cancel, booking A will wind up with `"status":"rebooked"` and booking B will wind up with `"status":"cancelled"`. So cancel whichever you like. In many cases, depending how your system is set up, the path of least confusion on your side may be to CANCEL THE MOST RECENT BOOKING. ## Question: Translations Can I use the FareHarbor External API to retrieve translated content? ### Answer Yes. You can retrieve translated content provided by the dashboard company in any language that is "active" in their dashboard, in the Translation Languages section. To retrieve a particular language, add a `language` query parameter to the API request: GET /companies//items/?language=es Doing this gives you company-provided translations. It does not translate field names etc., and it does not change currency formatting or provide other localization. ## Question: Online Booking Statuses What are online bookings statuses? ### Answer Online Booking Status: Each availability has an online booking status, which controls how it can be viewed and booked by online customers. In most cases, the status will be set to `auto`, which automatically prevents online customers from booking after a certain time cutoff, based on [item’s settings](https://help.fareharbor.com/dashboard/items/online-booking-settings/). The other statuses include `open`, `call`, `closed`, `cancelled`. These statuses are included in: * `GET /companies//availabilities//` * `GET /companies//items//minimal/availabilities/date//` * `GET /companies//items//minimal/availabilities/date-range///` For a complete description of these statuses and their meaning, go to [https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/](https://help.fareharbor.com/dashboard/availabilities/updating/online-booking-status/). ## Question: How do I implement bi-directional crew management with FareHarbor? ### Answer FareHarbor provides bi-directional crew management through API endpoints and webhooks: **1. Pushing data to FareHarbor:** Use API endpoints with your app and user keys to create, update, and manage crew member assignments. **2. Receiving data from FareHarbor:** Configure webhooks to receive real-time notifications when crew assignments change in the FareHarbor dashboard. ## Question: How do I manage crew members using the API? ### Answer Use these three main endpoints: **Crew Members Management:** * `POST /companies//availabilities//crew-members/` - Create assignment * `PUT /companies//availabilities//crew-members//` - Update assignment * `DELETE /companies//availabilities//crew-members//` - Delete assignment * `GET /companies//availabilities//crew-members/` - Get assignments **Users and Roles:** * `GET /companies//users/` - Get all company users * `GET /companies//roles/` - Get all available roles **Example:** ```bash curl -X POST 'https://fareharbor.com/api/external/v1/companies/hawaiianadventures/availabilities/12345/crew-members/' \ -H "X-FareHarbor-API-App: YOUR-APP-KEY" \ -H "X-FareHarbor-API-User: YOUR-USER-KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": 789, "role_id": 12, "note": "Experienced captain" }' ``` ## Question: How do I configure crew member webhooks? ### Answer * In the dashboard create or select a user under which the webhooks will be congifured: in the Users page, select a user and nevigate to the tab "Webhooks". * Click "Add Webhook". * Fill in the webhook name. * Select "Crew Members" schema. * Provide your webhook URL. After the webhook is created all the crew member updates: creating, updating, deletion will be sent to the provided URL. **Requirements:** * Your webhook URL must have a valid SSL certificate * Your endpoint must return a 200 HTTP status code **Webhook payload example:** ```json { "crew_member": { "pk": 789, "user": { "name": "John Smith", "username": "jsmith" }, "role": { "pk": 12, "short_name": "captain" }, "note": "Experienced captain", "availability_id": 1234, "status": "active" } } ``` Webhooks are triggered by crew member creations, modifications, disabling/enabling, and deletions. # FH API Integration Best Practices This section describes some best practices for integrating with FH using webhooks and APIs. **Notice on JSON Format Changes** Please be aware that the JSON formats and structures used in our API & Webhooks are subject to change. We continuously work to improve our API & Webhooks to meet the evolving needs of our users and to embrace technological advancements. As a result, modifications to the data formats, including additions or deprecations, can occur. **We strongly advise all users to design their applications in a manner that is capable of accommodating such changes.** This approach will ensure that your integration remains robust and functional, despite potential changes in data structures or schema. ## Consider using Zapier, or a similar service. Before writing software to integrate with FareHarbor webhooks, look into using Zapier or something similar. In many cases, doing an integration this way will be quicker, easier, more reliable, and less expensive than doing it yourself with your own servers and custom software. In order to integrate with the FareHarbor webhooks and/or API directly, without using Zapier or the like, you will need time from experienced software engineers. If you do not have them on staff, you may need to contract them and manage them. This is not always easy. ## The data model ### The Booking UUID The most important field in the booking schema is the "uuid" field. IF YOU RECEIVE TWO WEBHOOKS WITH THE SAME UUID, THEY ARE TALKING ABOUT THE SAME BOOKING. This is the most important thing to understand about bookings. You will likely receive multiple webhooks for the same booking. For instance, you will receive one when it's created, and you may receive another if the contact information is updated, or if a customer checkin occurs. For any given uuid, the most recent webhook received will contain the most up-to-date data. You can always retrieve the most recent details for a booking using the Retrieve Bookings endpoint, [Bookings Endpoint](#tag/Bookings-Endpoints): GET /companies//bookings// ### The Customer PK Another important field is the "customers" field. This field contains a list of customers. Each customer will have its own "pk". The PK is a globally-unique identifier for the customer. The details of a booking may change, but as long as it is not rebooked, the customer PK will not change, and can be used as an ID within your system, directly or indirectly. If you receive a webhook from FareHarbor for a booking that is already recorded in your system, this new webhook may contain updated information. Using the PK, you can check each customer's data to see if any piece of that customer's data has changed--the contents of a custom field, for instance. When a rebooking occurs, customer PKs are reassigned. For most practical purposes, you can treat a rebooking event the same as cancellation of the old booking and creation of the new booking. Data associated with the old booking are no longer relevant. ## Retrieving All Existing Bookings Using the External API, it is possible to retrieve all existing bookings. In pseudocode, it looks like this: retrieve a list of companies via the [Companies endpoint](#tag/Company-Endpoints) for each company, retrieve a list of items via the [Items endpoint](#tag/Items-Endpoints) for each item, retrieve lists of availabilities via the [Availabilities endpoint](#tag/Availabilities-Endpoints) (use bookable_only=no) for each availability, retrieve a list of bookings via the [Availability Bookings endpoint](#tag/Bookings-Endpoints/operation/get-bookings) There is sample python code to retrieve all bookings [here](#tag/Examples/Retrieve-Bookings) ## Collecting Phone Numbers We recommend that you collect customers' phone numbers, including country code, when creating bookings, to allow for communication between the operator and the customer. The phone numbers should be in the [E164 format](https://www.twilio.com/docs/glossary/what-e164) Example POST: /companies//availabilities//bookings/ Example Request: $ curl -X POST \ -H "X-FareHarbor-API-App: YOUR-APP-KEY" \ -H "X-FareHarbor-API-User: YOUR-USER-KEY" \ -d \ '{ "contact": { "name": "John Doe", "phone": "+1-415-789-4563", "phone_country": "US", "email": "johndoe@example.com" paths: /companies/\Z: get: summary: Companies operationId: get-companies deprecated: False tags: - Company Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' responses: '200': description: | Returns an array of `Company` objects. Returns a list of all companies for which you have permission to create bookings; note that this may include companies that have no bookable availabilities. content: application/json: schema: $ref: "#/components/schemas/COMPANIES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | The `/companies` endpoint lists every FareHarbor supplier that an API Partner can access and book through the API. The companies on this list are determined by which suppliers have requested the enablement of the API access for the given API Partner on their dashboard. When this request is successful, the API partner will receive a response from our system showing all the accessible suppliers alongside the respective company names, shortnames and the currency of their accounts. **Things to note:** * The value for the “shortname” will always be what is used in the subsequent endpoints in order to access a specific company’s information. * If (in the live environment) you do not see a supplier listed on this endpoint, there could be a few reasons why that is. It could be that the supplier has not requested your enablement yet. It could also be that you made the request using one currency user key when the supplier is on a different currency. Lastly, it may be possible that the supplier has been offboarded from FareHarbor and therefore no longer accessible. * Routine calls to this endpoint are recommended to refresh the most up to date list of available suppliers. If a company shortname is no longer available, that shortname can be removed from future /items/ and /availabilities/ requests to avoid ongoing errors. /companies//: get: summary: Company operationId: get-company deprecated: False tags: - Company Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: company-shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. responses: '200': description: | Returns a `Company` object (extended representation). content: application/json: schema: $ref: "#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | The `/company` endpoint allows the API Partner to specify one supplier company from the list in the `/companies` endpoint and view company-level information configured in the supplier’s FareHarbor general settings, such as company description, health and safety policy, company location, website URL, and more. **Things to Note:** * API Partners usually use this endpoint to import basic company details during the initial onboarding and to confirm that the company details on their side are accurate. * The location field shown here at the company-level is typically the supplier's primary address, but it is possible that different items sold by the supplier take place at other locations. These locations would be indicated on the /items endpoint. /companies//users/: get: summary: Company Users operationId: get-company-users deprecated: False tags: - Users Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/USERS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | /companies//checkin/: put: summary: Checkin Qr Code operationId: put-checkin-qr-code deprecated: False tags: - Checkin Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. responses: '200': description: | Returns a `Booking` object with the customers status updated to reflect that they are checked in. When "auto" check-in is used in the request, an HTTP 400 will be returned if the customer (or, in the case of whole booking checkin, any customer) is already checked in. content: application/json: schema: $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to check in a booking based on QR code. requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/CHECKIN_QR_CODE_REQUEST_JSON_SCHEMA" /companies//checkin-statuses/: get: summary: Checkin Statuses operationId: get-checkin-statuses deprecated: False tags: - Checkin Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: company-shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. responses: '200': description: | Returns an array of `CheckinStatus` objects for the `Company`. Note that checkin statuses are unique per company. content: application/json: schema: $ref: "#/components/schemas/CHECKIN_STATUSES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to pull a list of available checkin statuses by specifying it directly via pk instead of having to automatically select the checkin status. /companies//lodgings/: get: summary: Lodgings operationId: get-lodgings deprecated: False tags: - Lodging Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. responses: '200': description: | Returns an array of `Lodging` objects. content: application/json: schema: $ref: "#/components/schemas/LODGINGS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to check all of the lodging options available on a dashboard. /companies//availabilities//lodgings/: get: summary: Availability Lodgings operationId: get-availability-lodgings deprecated: False tags: - Availabilities Endpoints - Lodging Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The unique numerical ID of the requested `Availability` object, that is then used during the booking process. responses: '200': description: | Returns an array of `Lodging` objects that include availability specific data. The `is_pickup_available` property indicates whether a pickup is offered for the lodging (for the availability specified in the request URL). This value reflects the current state of the system and can change when updates are made. content: application/json: schema: $ref: "#/components/schemas/AVAILABILITY_LODGINGS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to check lodging options on a specific availability, including whether pick-up is available for each lodging option. /companies//agents/: get: summary: Agents operationId: get-agents deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: affiliate-shortname in: path required: True description: | The shortname of the affiliate company with which your user key is associated; agents are per-affiliate, not per company. responses: '200': description: | Returns an array of `Agent` objects. content: application/json: schema: $ref: "#/components/schemas/AGENTS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to fetch all agents from the indicated affiliate company. /companies//desks/: get: summary: Desks operationId: get-desks deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: affiliate-shortname in: path required: True description: | The shortname of the affiliate company with which your user key is associated; desks are per-affiliate, not per company. responses: '200': description: | Returns an array of `Desk` objects. content: application/json: schema: $ref: "#/components/schemas/DESKS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to fetch all desks from the indicated affiliate company. /companies//items/: get: summary: Items operationId: get-items deprecated: False tags: - Items Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string example: | [yes|no] name: require_future_availabilities in: query required: False description: | Only include items that have future availabilities - schema: type: string example: | [yes|no] name: detailed in: query required: False description: | Include additional item details - schema: type: string example: | [yes|no] name: optimized in: query required: False description: | Include only minimal item details. Only applies when `detailed=no`. responses: '200': description: | Returns a list of items as for which you have permission to create bookings; again, note that this may include items that have no bookable availabilities. Returns an array of `Item` objects. When `require_future_availabilities` = yes is specified, only `Item` objects with bookable future availabilities are returned. content: application/json: schema: $ref: "#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | The `/items` endpoint shows every bookable product (referred to as “items” in FareHarbor) on a specified supplier dashboard along with a summary of fields associated with each product. This endpoint includes product photos, locations, booking notes, and ticket options. **Things to note:** * API Partners use this endpoint to import product details and content so that they can build out the appropriate listing on their platform, taking an item’s specific PK (its unique ID) to connect it to the listing. * If an item is not displayed through this endpoint, it might mean that it has been discontinued, replaced by another item on the list, or made private or inactive by the supplier. * Routine calls to this endpoint are recommended to pull the most up to date list of items for an active supplier. If an item PK is no longer listed, it can be removed from future /availabilities/ requests to avoid ongoing errors for items that have been restricted. * Using the `optimized` query parameter, affiliates can retrieve just basic information like name, location, and tags for all the items offered by their partner companies; then using the [Item endpoint](#tag/Items-Endpoints/operation/get-item) they can get full information for only the items they're interested in. To get additional information such as `effective_cancellation_policy` in the response, add the query parameter `?detailed=yes` to the end of the URL. Note that `effective_booking_cutoff` is not included in item responses; use the [Availabilities endpoints](#tag/Availabilities-Endpoints) with `?detailed=yes` to retrieve the booking cutoff for each availability. /companies//items//: get: summary: Item operationId: get-item deprecated: False tags: - Items Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 1867 name: item.pk in: path required: True description: | The unique numerical ID of the bookable product (referred to as `item` in FareHarbor). - schema: type: string example: | [yes|no] name: detailed in: query required: False description: | Include additional item details responses: '200': description: | Returns a detailed `Item` object. content: application/json: schema: $ref: "#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | The `/item` endpoint shows a single bookable product (referred to as an [`Item`](#tag/Data-Types/Schemas/Item) in FareHarbor) on a specified supplier dashboard along with a summary of fields associated with each product. This endpoint includes product photos, locations, booking notes, and ticket options. To get additional information such as `effective_cancellation_policy` in the response, add the query parameter `?detailed=yes` to the end of the URL. Note that `effective_booking_cutoff` is not included in item responses; use the [Availabilities endpoints](#tag/Availabilities-Endpoints) with `?detailed=yes` to retrieve the booking cutoff for each availability. /companies//availabilities//: get: summary: Availability operationId: get-availability deprecated: False tags: - Availabilities Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The unique numerical ID of the requested `Availability` object, that is then used during the booking process. - schema: type: string example: | [yes|no] name: detailed in: query required: False description: | Include additional availability details responses: '200': description: | Returns an `Availability` object (extended representation). content: application/json: schema: $ref: "#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to pull information for a single availability within FareHarbor. To get additional information such as `effective_cancellation_policy` and `effective_booking_cutoff` in the response, add the query parameter `?detailed=yes` to the end of the URL. /companies//items//minimal/availabilities/date//: get: summary: Minimal Availabilities By Date operationId: get-minimal-availabilities-by-date deprecated: False tags: - Availabilities Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 1867 name: item.pk in: path required: True description: | The unique numerical ID of the bookable product (referred to as `item` in FareHarbor). - schema: type: string format: date example: | 2015-01-22 name: date in: path required: True description: | `date` should be in the format `YYYY-MM-DD` and is taken to be the in company's local time. - schema: type: string example: | [yes|no] name: detailed in: query required: False description: | Include additional availability details - schema: type: string example: | [yes|no] name: bookable_only in: query required: False description: | Include only availabilities that are bookable - schema: type: string example: | [yes|no] name: custom_fields_summary in: query required: False description: | Include summarized custom field metadata responses: '200': description: | Returns an array of `Availability` objects (minimal representation). Returns possibly-bookable availabilities for `date` (in the company's local time). Note that possibly-bookable availabilities do not include those for which customers are requested to "call to book". Excludes custom field information from the response. content: application/json: schema: $ref: "#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to fetch all bookable availabilities for a single item within a specified `date` (in the company's local time) in a simplified format (without custom field information and other fields). This variation can be useful for caching availabilities when extra fields are not needed, and it also performs with greater speed. To get additional information such as `effective_cancellation_policy` and `effective_booking_cutoff` in the response, add the query parameter `?detailed=yes` to the end of the URL. To get metadata information on the custom field instances in the response, add the query parameter `?custom_fields_summary=yes` at the end of the URL. /companies//items//minimal/availabilities/date-range///: get: summary: Minimal Availabilities By Date Range operationId: get-minimal-availabilities-by-date-range deprecated: False tags: - Availabilities Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 1867 name: item.pk in: path required: True description: | The unique numerical ID of the bookable product (referred to as `item` in FareHarbor). - schema: type: string format: date example: | 2015-01-22 name: start-date in: path required: True description: | Marks the start (inclusive) of the requested time period. `start-date` should be in the format YYYY-MM-DD and taken to be in the company's local time. - schema: type: string format: date example: | 2015-01-22 name: end-date in: path required: True description: | Marks the end (inclusive) of the requested time period. `end-date` should be in the format YYYY-MM-DD and taken to be in the company's local time. - schema: type: string example: | [yes|no] name: detailed in: query required: False description: | Include additional availability details - schema: type: string example: | [yes|no] name: bookable_only in: query required: False description: | Include only availabilities that are bookable - schema: type: string example: | [yes|no] name: custom_fields_summary in: query required: False description: | Include summarized custom field metadata responses: '200': description: | Returns an array of `Availability` objects (minimal representation). Returns possibly-bookable availabilities for the range `start-date` through `end-date` (in the company's local time). Note that possibly-bookable availabilities do not include those for which customers are requested to "call to book". Excludes custom field information from the response. content: application/json: schema: $ref: "#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to fetch all bookable availabilities for a single item within a specified `date` range (in the company's local time) in a simplified format (without custom field information and other fields). The largest date range that can be pulled in one single request is 7 days. This variation can be useful for caching availabilities when extra fields are not needed, and it also performs with greater speed. To get additional information such as `effective_cancellation_policy` and `effective_booking_cutoff` in the response, add the query parameter `?detailed=yes` to the end of the URL. To get metadata information on the custom field instances in the response, add the query parameter `?custom_fields_summary=yes` at the end of the URL. /companies//availabilities//bookings/: get: summary: Bookings operationId: get-bookings deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The unique numerical ID of the requested `Availability` object. This should come from whatever availability you select from the `/availability` endpoint. responses: '200': description: | Returns a list of simplified `Booking` objects. content: application/json: schema: $ref: "#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to fetch a list of all bookings (in simplified format) for an availability. post: summary: Bookings operationId: post-bookings deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The unique numerical ID of the requested `Availability` object. This should come from whatever availability you select from the `/availability` endpoint. responses: '200': description: | Returns the newly created `Booking` object. **Permissions affect the visibility of certain fields:** * The invoice_cost will be included if the permission `View invoice prices` is enabled. * The invoice_cost will be null if `View invoice prices` is disabled. * The total_cost will be included if the permission `View amounts` is enabled. * The total_cost will be null if `View amounts` is disabled. **invoice_cost** represents the invoice price of the customer type. **total_cost** represents the total cost of the customer type, including any priced custom fields. Note: `total_cost` reflects only priced custom fields explicitly provided in the request; priced defaults are not applied automatically. #### Priced custom fields (behavior change) When the POST payload omits `custom_field_values`, the API will not auto-create values for priced custom fields. Only unpriced custom fields may be defaulted. Priced custom fields apply only when explicitly sent. - Required fields: Required CFs remain required. If a required priced CF isn’t sent, the request fails with a validation error. - What is “priced”? Any CF whose selection changes price (e.g., priced yes/no, or an extended option with a surcharge/discount). - Unpriced CFs: Informational fields that do not change price. These may still be defaulted. Example (omit priced CF → no price change): ```json { "contact": { "name": "Jane", "email": "jane@example.com", "phone": "555-111-2222" }, "customers": [{ "customer_type_rate": 12345 }] } ``` Example (include priced CF → price applied): ```json { "contact": { "name": "Jane", "email": "jane@example.com", "phone": "555-111-2222" }, "customers": [ { "customer_type_rate": 12345, "custom_field_values": [ { "custom_field": 67890, "value": true } ] } ] } ``` content: application/json: schema: $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to create a new booking. To create a booking, the API Partner must assemble 1) the request URL for the availability being booked, and 2) the booking request payload, with all the details of the booking they want to create. When creating a booking, several properties about the availability and the booking request must hold or the booking will not be created: * **Availability open** - The vendor may close availabilities at any time, and availabilities are automatically closed at various times based on the company's criteria. * **Availability capacity** - There must be available capacity on the availability for all customers * **Customer type rate capacities** - For each booked customer type rate there must be available capacity for each customer of that customer type. * **Exclusivity** - If any customer type rate being booked is exclusive, then it must be the only customer type rate being booked. * **Correct Customer Type Rates** - Each customer type rate being booked must actually belong to the availability being booked. * **Orders enabled** - When creating an order, the vendor must have orders enabled in their FareHarbor dashboard. ### Transportation To request transportation for a booking, specify a `Lodging` pk for the `lodging` property when creating the booking as shown in the example. #### Pickup Information When a lodging is specified during booking creation and transportation is available for the lodging, the booking response will include a `pickup` property that provides pickup information as shown in the example. Note: if a lodging is specified and transportation is not available for the specified lodging (or any lodging), the `pickup` property will have a `null` value. #### Arrival Information Arrival information is intended for customers who are providing their own transportation. When a lodging is not provided during booking creation or transportation is not available for the specified lodging (or any lodging), arrival information may be provided. When arrival information is available, the booking response will include an `arrival` property that provides arrival information as shown in the example. Note: the `arrival` property will have a `null` value if pickup information is available. requestBody: description: | When creating bookings, use the customer type rate and custom field instance information contained in the availability to construct a request of the following form: content: application/json: schema: $ref: "#/components/schemas/BOOK_REQUEST_JSON_SCHEMA" /companies//availabilities//bookings/validate/: post: summary: Validate operationId: post-validate deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The unique numerical ID of the requested `Availability` object. This should come from whatever availability you select from the `/availability` endpoint. responses: '200': description: | The response provides an `is_bookable` field indicating whether the booking can be created. If "true", the booking is valid and bookable for that availability. The response will also include a pricing calculation for that booking. { "is_bookable": true, ... } When the booking can't be created, additional information regarding the error is provided: { "is_bookable":false, "code":"bookability-error", "error":"Unable to create booking: error details." } content: application/json: schema: $ref: "#/components/schemas/VALIDATE_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Checks bookability and provides booking level pricing information. Prior to creating the booking, you have the opportunity to confirm that your request is still valid and bookable with the availability and customer type details that you have selected. **Things to Note:** * If your booking process includes adding a selection to a cart before checking out, this endpoint is highly recommended as it can help to avoid errors at the checkout stage. For example, if you validate the booking as you view the cart, you can ensure that the request is still valid and bookable before collecting payment - and if it is no longer bookable you can give the customer the opportunity to change their selection before proceeding with payment. requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA" /companies//bookings//: get: summary: Booking operationId: get-booking deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID that was generated when you first created the booking. - schema: type: string example: | [yes|no] name: with_payments in: query required: False description: | Include payments details from the booking responses: '200': description: | Returns a `Booking` object. content: application/json: schema: oneOf: - $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" - $ref: "#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to retrieve the full record of a specific booking that you have made, you may do so by using the UUID that was generated when you first created the booking. delete: summary: Booking operationId: delete-booking deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID that was generated when you first created the booking. - schema: type: string example: | [yes|no] name: with_payments in: query required: False description: | Include payments details from the booking responses: '200': description: | Returns the `Booking` object with it's status updated to `cancelled`. content: application/json: schema: oneOf: - $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" - $ref: "#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to cancel the specified booking by issuing a `DELETE` request. **Things to Note:** * IMPORTANT - The ability to cancel a booking via API is controlled by cancellation policy settings in FareHarbor. You can read about cancellation expectations [here](#tag/Cancellation-Policies). * Regardless of cancellation policy settings, the FareHarbor API will allow cancellations within a 5 minute grace period after a booking is created. **Requirements:** * The booking must be cancelled at least 48 hours prior to start time (availability start_at property) to receive 100% refund. * Any affiliate-collected payments for the booking must be fully refunded. * Cancellations are allowed up until the start time. However, if the booking is cancelled less than 48 hours prior to start time, there is no refund. * The requesting user must have permission to cancel bookings (granted on a per-company basis). /companies//bookings//note/: put: summary: Update Booking Note operationId: put-update-booking-note deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID that was generated when you first created the booking. responses: '200': description: | Returns the `Booking` object, with the note field updated. content: application/json: schema: $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to update the booking note by issuing a `PUT` request with the new note; to clear the booking note, pass "". requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/BOOKING_NOTE_REQUEST_JSON_SCHEMA" /companies//bookings//customer-custom-field-values//: put: summary: Update Customer Custom Field Value operationId: put-update-customer-custom-field-value deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID of the Booking. - schema: type: integer example: | 12345 name: custom_field_value.pk in: path required: True description: | The id of the customer custom field value. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/CUSTOMER_CUSTOM_FIELD_VALUE_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/CUSTOMER_CUSTOM_FIELD_VALUE_REQUEST_JSON_SCHEMA" /companies//bookings//resource-uses//: patch: summary: Update Resource Use operationId: patch-update-resource-use deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID that was generated when you first created the booking. - schema: type: integer example: | 12345 name: resource_use.pk in: path required: True description: | The id of the existing resource use to update. responses: '200': description: | Returns the `Booking` object, including `resource_uses`, with the replacement resource use. The returned resource use may have a new `pk`; clients should use the returned `resource_uses` values for later updates. content: application/json: schema: $ref: "#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to replace an existing resource use on a booking by issuing a `PATCH` request with the new `resource_pk`. requestBody: description: | To update a resource use, provide the `pk` of the resource that should be assigned to that resource use. content: application/json: schema: $ref: "#/components/schemas/RESOURCE_USE_REQUEST_JSON_SCHEMA" /companies//bookings//checkin/: put: summary: Checkin Booking operationId: put-checkin-booking deprecated: False tags: - Checkin Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. - schema: type: string format: uuid example: | d75102be-9732-4523-90a8-c698eff2b983 name: Booking.uuid in: path required: True description: | The UUID that was generated when you first created the booking. responses: '200': description: | Returns a `Booking` object with the customers status updated to reflect that they are checked in. content: application/json: schema: $ref: "#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Used to check in a booking based on the booking UUID. requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/CHECKIN_BOOKING_REQUEST_JSON_SCHEMA" /companies//minimal/bookings-by-create-date//: get: summary: Bookings By Create Date operationId: get-bookings-by-create-date deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: string format: date example: | 2015-01-22 name: date in: path required: True description: | `date` should be in the format `YYYY-MM-DD`. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/VERY_MINIMAL_BOOKINGS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | This will allow partners to retrieve bookings by create date (in UTC). In the case of an outage where the booking webhook fails this can be used to recover bookings. /bookings/resend-confirmation-email/: post: summary: Resend Confirmation Email operationId: post-resend-confirmation-email deprecated: False tags: - Bookings Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' responses: '200': description: | Returns the same generic acknowledgement whether zero or many bookings match. content: application/json: schema: $ref: "#/components/schemas/RESEND_CONFIRMATION_EMAIL_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | Queues confirmation email resends for all non-cancelled bookings whose contact email and availability start date match the request. The search spans all bookings and is not limited by the bookings accessible to the supplied keys. The response never reveals whether any bookings matched. Confirmation emails are sent only to the address already stored on each matching booking. **Rate Limits:** In addition to the general [rate limits](#tag/Getting-Started/Rate-Limits), this endpoint allows 5 requests per minute per app key and user key pair, and 1 request per 5 minutes for the same email address and app key. Exceeding either endpoint-specific limit returns a `429` response. requestBody: description: | Provide the customer's email address and an inclusive activity date range of no more than 31 days. content: application/json: schema: $ref: "#/components/schemas/RESEND_CONFIRMATION_EMAIL_REQUEST_JSON_SCHEMA" /companies//availabilities//crew-members/: get: summary: Crew Members operationId: get-crew-members deprecated: False tags: - Crew Members Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The id of the Availability. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/CREW_MEMBERS_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | post: summary: Crew Members operationId: post-crew-members deprecated: False tags: - Crew Members Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The id of the Availability. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/CREATE_CREW_MEMBER_REQUEST_JSON_SCHEMA" /companies//availabilities//crew-members/(?P\d+)/: patch: summary: Crew Member operationId: patch-crew-member deprecated: False tags: - Crew Members Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The id of the Availability. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | requestBody: description: | content: application/json: schema: $ref: "#/components/schemas/UPDATE_CREW_MEMBER_REQUEST_JSON_SCHEMA" delete: summary: Crew Member operationId: delete-crew-member deprecated: False tags: - Crew Members Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. - schema: type: integer example: | 4787 name: availability.pk in: path required: True description: | The id of the Availability. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | /companies//roles/: get: summary: Roles operationId: get-roles deprecated: False tags: - Roles Endpoints parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' - schema: type: string example: | hawaiianadventures name: shortname in: path required: True description: | The shortname of the company. responses: '200': description: | content: application/json: schema: $ref: "#/components/schemas/ROLES_RESPONSE_JSON_SCHEMA" '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | /ping/\Z: get: summary: Ping operationId: get-ping deprecated: False parameters: - $ref: '#/components/parameters/X-FareHarbor-API-App' - $ref: '#/components/parameters/X-FareHarbor-API-User' responses: '200': description: | content: application/json: schema: '400': $ref: "#/components/responses/BadRequest" '403': $ref: "#/components/responses/Forbidden" '404': $ref: "#/components/responses/NotFound" '429': $ref: "#/components/responses/TooManyRequests" '504': $ref: "#/components/responses/GatewayTimeout" description: | components: securitySchemes: {} parameters: X-FareHarbor-API-App: name: X-FareHarbor-API-App in: header required: true schema: type: string description: APP-KEY (Please log in to see your key) example: APP-KEY X-FareHarbor-API-User: name: X-FareHarbor-API-User in: header required: true schema: type: string description: USER-KEY (Please log in to see your key) example: USER-KEY responses: BadRequest: description: "Bad Request (see [Error Codes](#tag/Error-Codes))" content: application/json: schema: $ref: "#/components/schemas/Error400" Forbidden: description: "Forbidden (see [Error Codes](#tag/Error-Codes))" content: application/json: schema: $ref: "#/components/schemas/Error403" NotFound: description: "The specified resource was not found (see [Error Codes](#tag/Error-Codes))" content: application/json: schema: $ref: "#/components/schemas/Error404" TooManyRequests: description: "Too Many Requests (see [Rate Limits](#tag/Getting-Started/Rate-Limits))" content: application/json: schema: $ref: "#/components/schemas/Error" GatewayTimeout: description: "[Gateway Timeout](#tag/Getting-Started/Timeouts)" schemas: UPDATE_CREW_MEMBER_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for updating an existing crew member assignment on an availability. properties: note: description: Optional note providing additional context, instructions, or information about the crew member's assignment. example: 'Updated: Now responsible for safety briefing and equipment check' type: string role: description: Optional short name of the role to assign to the crew member. Must match an existing role short_name for the company. Pass null to remove the role assignment. example: captain type: - string - 'null' title: Update Crew Member Request type: object CHECKIN_QR_CODE_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false properties: checkin_status: oneOf: - description: the string 'auto' indicates that checkin status should be automatically determined. The string 'unchanged' will leave the checkin status unchanged. Other string values may be supported in the future. When a checkin status pk is provided, the associated checkin status will be used. When null is provided, the checkin status will be reset. Defaults to 'auto' if the property is not provided. example: auto type: string - type: number - type: 'null' is_whole_booking: description: Whether whole booking checkin is desired. If true, the checkin status for all customers associated with the booking will be updated. If false, the checkin status for the customer associated with the QR code (customer checkin URL) will be updated. Defaults to false if the property is not provided. type: boolean qr_code: description: the customer's QR code data. example: https://fhchk.co/abc format: uri type: string required: - qr_code - is_whole_booking type: object CREATE_CREW_MEMBER_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for creating a crew member assignment on an availability. properties: note: description: Optional note providing additional context, instructions, or information about the crew member's assignment. example: Responsible for safety briefing and equipment check type: string role: description: Optional short name of the role to assign to the crew member. Must match an existing role short_name for the company. example: captain type: string username: description: Username of the user to add as a crew member. Must be a valid username within the system. example: jsmith type: string required: - username title: Create Crew Member Request type: object CREATE_LINE_ITEM_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for creating a line item on a booking. properties: description: description: Description of the line item. example: Processing fee type: string discount_code_pk: description: Optional discount code ID to apply to this line item. example: 1 type: integer is_private: default: false description: If true, do not show this line item to the customer. type: boolean is_taxable: default: false description: Whether the line item is taxable. type: boolean offset: description: Amount in the smallest currency unit (e.g. cents). Use positive for fees, negative for discounts (e.g. 1000 for $10.00, -500 for $5.00 discount). example: 1000 type: integer required: - description - offset title: Create Line Item Request type: object RESEND_CONFIRMATION_EMAIL_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for queueing confirmation email resends by customer email and activity date range. properties: date_from: description: Inclusive activity start date in YYYY-MM-DD format. example: '2026-08-01' type: string date_to: description: Inclusive activity end date in YYYY-MM-DD format. The range cannot exceed 31 days. example: '2026-08-31' type: string email: description: Customer contact email matched case-insensitively. example: customer@example.com format: email type: string required: - email - date_from - date_to title: Resend Confirmation Email Request type: object RESOURCE_USE_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for updating an existing resource use on a booking. properties: resource_pk: description: The pk of the resource to assign to the resource use. example: 12345 type: integer required: - resource_pk title: Update Resource Use Request type: object CUSTOMER_CUSTOM_FIELD_VALUE_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: JSON body for updating an existing customer custom field value on a booking. properties: value: description: The new value for the customer custom field value. example: '10:01' type: - string - number - integer - boolean - 'null' required: - value title: Update Customer Custom Field Value Request type: object CHECKIN_BOOKING_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false properties: checkin_status: oneOf: - description: the string 'auto' indicates that checkin status should be automatically determined. The string 'unchanged' will leave the checkin status unchanged. Other string values may be supported in the future. When a checkin status pk is provided, the associated checkin status will be used. When null is provided, the checkin status will be reset. Defaults to 'auto' if the property is not provided. example: auto type: string - type: number - type: 'null' customer: oneOf: - description: when a customer pk is specified, the associated customer will be checked in. When null is specified, all customers associated with the booking will be checked in. Defaults to null if the property is not provided. example: 2481 type: number - type: 'null' type: object BOOKING_NOTE_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# properties: note: example: This is a *note*. type: string required: - note type: object VALIDATE_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string name: description: The name of the head of the party. example: Surfer Dude type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string required: - email - name - phone type: object custom_field_value: properties: custom_field: description: A valid Custom Field pk. example: 4502 format: int32 type: number value: description: A string up to 2048 characters. If the custom field is of type yes-no, 'true' or 'false' must be specified. If the custom field is of type extended-option, an extended option pk must be specified. example: 'false' maxLength: 2048 type: string type: object custom_field_values: items: $ref: '#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA/definitions/custom_field_value' type: array customer: additionalProperties: false properties: customer_type_rate: description: The customer type rate's unique ID. example: 978 format: int32 type: number required: - customer_type_rate type: object customers: items: $ref: '#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA/definitions/customer' type: array properties: contact: $ref: '#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA/definitions/contact' custom_field_values: $ref: '#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA/definitions/custom_field_values' customers: $ref: '#/components/schemas/VALIDATE_REQUEST_JSON_SCHEMA/definitions/customers' external_id: example: '' type: string note: example: Optional booking note. type: string voucher_number: example: V-35791209 type: string required: - contact - customers type: object BOOK_REQUEST_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: custom_field_value: additionalProperties: false properties: custom_field: description: A valid Custom Field pk. example: 4502 format: int32 type: number value: oneOf: - description: A string up to 2048 characters. example: 'false' maxLength: 2048 type: string - description: If the custom field is of type yes-no, 'true' or 'false' must be specified example: false type: boolean - description: If the custom field is of type extended-option, an extended option pk must be specified. type: number required: - custom_field - value type: object customer: additionalProperties: false properties: custom_field_values: items: $ref: '#/components/schemas/BOOK_REQUEST_JSON_SCHEMA/definitions/custom_field_value' type: array customer_type_rate: description: The customer type rate's unique ID. example: 978 format: int32 type: number required: - customer_type_rate type: object properties: agent: description: The agent's unique ID. example: 2314 format: int32 type: number agent_name: description: The agent's name. example: Eddie maxLength: 128 type: string amount_paid: description: 'The payment amount collected by the affiliate user. The amount must be an integer number of the smallest negotiable unit of money in the company''s currency. In the case of USD, this means USD cents. So, for instance, 1425 means $14.25 USD. Note: Partial payments are disallowed for rebookings.' oneOf: - description: ' When amount_paid is 0, no payment will be created. When amount_paid is lower than the booking total, a partial payment will be created. Note that amount_paid cannot exceed the booking total.' example: 1425 type: number - description: When amount_paid is null, a full payment will be created. type: 'null' contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string name: description: The name of the head of the party. example: Surfer Dude type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string required: - email - name - phone type: object custom_field_values: items: $ref: '#/components/schemas/BOOK_REQUEST_JSON_SCHEMA/definitions/custom_field_value' type: array customers: items: $ref: '#/components/schemas/BOOK_REQUEST_JSON_SCHEMA/definitions/customer' minItems: 1 type: array desk: description: The desk's unique ID. example: 2314 format: int32 type: number desk_name: description: The desk's name. example: Windward Side maxLength: 128 type: string external_id: example: '' maxLength: 128 type: string lodging: description: The lodging's unique ID. example: 2314 format: int32 type: number note: example: '' maxLength: 10000 type: string orderize_booking: example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid maxLength: 36 type: string rebooking: description: See [Rebooking](#tag/Rebooking) example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid maxLength: 36 type: string voucher_number: description: The external booking reference number. example: V-35791209 maxLength: 128 type: string required: - contact - customers type: object BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object affiliate_company: oneOf: - additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The affiliate companies name. example: Affiliate Company type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: affiliate_company type: string required: - shortname - name - currency type: object - type: 'null' affiliate_metadata: description: Metadata from affiliate sources. properties: airbnb: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/airbnb_metadata' type: object affiliation: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' required: - affiliate_company type: object agent: oneOf: - additionalProperties: false properties: name: description: The agent's name. example: Eddie type: string pk: description: The agent's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - type: 'null' airbnb_guest_profile: description: An Airbnb guest profile. properties: direct_thread_id: description: The direct thread ID for the guest. example: '2164961599' type: - string - 'null' user_id: description: The Airbnb user ID. example: '17780410' type: - string - 'null' type: object airbnb_metadata: description: Metadata from Airbnb bookings. properties: activity_id: description: The Airbnb activity ID. example: '6137649' type: - string - 'null' channel_thread_id: description: The Airbnb channel thread ID. example: '2199079188' type: - string - 'null' guest_id: description: The Airbnb guest ID. example: '17780410' type: - string - 'null' guest_profiles: description: List of Airbnb guest profiles. items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/airbnb_guest_profile' type: - array - 'null' host_id: description: The Airbnb host ID. example: '1234' type: - string - 'null' offering_id: description: The Airbnb offering ID. example: '5495433' type: - string - 'null' type: object arrival: oneOf: - additionalProperties: false properties: display_text: example: Please arrive by 11:45 pm type: string notes: format: markdown type: string notes_safe_html: format: markdown type: string time: description: The arrival time (set in the company's local time); the customer must provide their own transporation and arrive at the activity location by this time. example: 2024-04-11T23:45:00-1000 format: datetime type: string required: - time - notes - notes_safe_html - display_text type: object - type: 'null' availability: additionalProperties: false properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_type_rates: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's headline. example: Epic Jet Ski Tour type: string item: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/item' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - headline - item - customer_type_rates - custom_field_instances type: object booking: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' affiliate_metadata: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/affiliate_metadata' agent: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/agent' amount_paid: oneOf: - type: number - type: 'null' amount_paid_display: oneOf: - example: '0.0' type: string - type: 'null' arrival: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/arrival' availability: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/availability' description: The availability to which this booking corresponds. booked_by: oneOf: - type: 'null' - additionalProperties: false properties: name: type: string required: - name type: object company: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/company' confirmation_url: description: The booking's confirmation page URL. format: uri type: string contact: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/contact' description: Contact information for this booking. created_at: description: The date and time at which the booking was created (set in utc time). example: 2024-06-20T17:14:33+0000 format: datetime type: string custom_field_values: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_count: description: The number of customers on this booking. example: 1 type: number customers: description: A list of customers on this booking. items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/customer' type: array dashboard_url: description: The booking's dashboard URL. example: https://fareharbor.com/hawaiianadventures/dashboard/?overlay=/contacts/7/bookings/d75102be-9732-4523-90a8-c698eff2b983/ format: uri type: string desk: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/desk' display_id: example: '#6876876' type: string effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' external_id: description: An additional identifier if necessary. maxLength: 128 type: string generated_codes: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/generated_code' type: array invoice_price: oneOf: - description: The invoice price of this booking. Assuming that the user of the API is a reseller this will be the amount that the user of the API owes the vendor on this booking, if the vendor has opted to set up that information; otherwise it will be null. type: number - type: 'null' invoice_price_display: oneOf: - type: string - type: 'null' is_eligible_for_cancellation: example: true type: boolean is_follow_up_email_disabled: type: boolean is_reminder_email_disabled: type: boolean is_subscribed_for_sms_updates: description: Whether or not the contact would like the booking company to send them SMS updates about this booking. Note that the value of this field does not reflect whether or not the user has sent a STOP request to FareHarbor. If the user sends a STOP request to an External API client, that API client should respect that request. example: false type: boolean line_items: description: Line items on the booking. items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/line_item' type: array lodging: oneOf: - additionalProperties: false properties: name: description: The lodging's name. example: Eddie type: string pk: description: The lodging's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' note: example: '' format: markdown type: string note_safe_html: example: '' format: markdown type: string online_booking_references: example: '' type: string order: description: When there is no order associated with the booking, order will be null. oneOf: - properties: display_id: description: A unique identifier for the order example: ABTT type: string type: object - description: '' type: 'null' payments: description: Payment information for the booking, only visible through webhooks or with the with_payments=yes query string. If there is no query string, then the payments won't show. items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/payment' type: array pickup: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/pickup' pk: description: The booking's unique ID. example: 6876876 format: int32 type: number rebooked_from: example: null oneOf: - type: string - type: 'null' rebooked_to: example: null oneOf: - type: string - type: 'null' receipt_subtotal: oneOf: - example: 36000 type: number - type: 'null' receipt_subtotal_display: oneOf: - example: '360.00' type: string - type: 'null' receipt_taxes: oneOf: - example: 2776 type: number - type: 'null' receipt_taxes_display: oneOf: - example: '27.76' type: string - type: 'null' receipt_total: oneOf: - example: 38776 type: number - type: 'null' receipt_total_display: oneOf: - example: '387.76' type: string - type: 'null' related_bookings: properties: related_order: properties: bookings: description: Booking UUIDs related to the order example: - d75102be-9732-4523-90a8-c698eff2b983 - a99e711d-2c70-48ce-87ff-0818942c3489 items: type: string type: array id: description: Order ID example: ABTT type: string type: object type: object source_type: enum: - online - direct - pos - reseller - external-api - kiosk - imported - unkown example: online type: string status: enum: - booked - cancelled - rebooked example: booked type: string uuid: description: The booking's universally unique identifier; used to access the booking via the API. example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid type: string voucher_number: example: '' type: string waiver_signatures: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/waiver_signatures' required: - pk - uuid - availability - contact - company - affiliate_company - customers - invoice_price - invoice_price_display - display_id - external_id - order - status - rebooked_from - rebooked_to - confirmation_url - voucher_number - online_booking_references - receipt_subtotal - receipt_subtotal_display - receipt_taxes - receipt_taxes_display - receipt_total - receipt_total_display - amount_paid - amount_paid_display - custom_field_values - note - note_safe_html - pickup - arrival - effective_cancellation_policy - is_eligible_for_cancellation - agent - desk - payments - dashboard_url - customer_count - is_subscribed_for_sms_updates - is_follow_up_email_disabled - is_reminder_email_disabled - created_at - source_type - booked_by - generated_codes - waiver_signatures - line_items - lodging - related_bookings type: object campaign: additionalProperties: false properties: created_at: description: The date and time the campaign was created at (set in utc time). example: 2023-08-18T00:30:00-0600 format: datetime type: string is_archived: example: false type: boolean name: example: August Discounts type: string prefix: example: FH type: string summary: type: string required: - created_at - is_archived type: object checkin_status: additionalProperties: false properties: name: description: The checkin status' name. example: checked in type: string pk: example: 10 format: int32 type: number type: type: string required: - pk - name - type type: object company: additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency type: object contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string is_subscribed_for_email_updates: description: Whether or not the contact would like email updates. example: false type: boolean language: description: The contact language. example: en-us type: string member: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/member' - type: 'null' name: description: The name of the head of the party. example: Surfer Dude type: string normalized_phone: description: The party's contact phone number. This will have a plus sign, the country code, and no extra characters such as commas or dashes. example: '+14432221100' type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string phone_country: description: The contact phone's country code. example: US type: - string - 'null' required: - name - phone - phone_country - normalized_phone - email - is_subscribed_for_email_updates type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field: additionalProperties: false properties: booking_notes: description: Notes for the customer specific to the custom field. example: '' format: markdown type: string booking_notes_safe_html: description: Notes for the customer specific to the custom field. format: markdown type: string count_max: description: The maximum amount possible for a count type custom field. example: 300 type: number count_min: description: The minimum amount possible for a count type custom field. example: 0 type: number description: description: The custom field's description. example: Do you need additional safety equipment? format: markdown type: string description_safe_html: description: The custom field's description. example:

Do you need additional safety equipment?

format: markdown type: string extended_options: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/extended_option' type: array is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_required: description: Indicates whether the custom field requires a value. example: false type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Safety Equipment type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number tags: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/tag' type: array title: type: string total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number type: description: The custom field's type. enum: - yes-no - short - long - extended-option - count - multi-campaign - code-generator - date example: yes-no type: string required: - pk - type - is_required - description - description_safe_html - name - booking_notes - booking_notes_safe_html - offset - total - total_including_tax type: object custom_field_instance: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field' pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object custom_field_value: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field' display_value: example: 'false' maxLength: 2048 type: string name: example: Name type: string pk: description: A valid Custom Field pk. example: 4502 format: int32 type: number total_cost: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/total_cost' value: oneOf: - description: A string up to 2048 characters. example: 'false' maxLength: 2048 type: string - description: If the custom field is of type yes-no, 'true' or 'false' must be specified example: false type: boolean - description: If the custom field is of type extended-option, an extended option pk must be specified. type: number required: - pk - custom_field - name - value - display_value - total_cost type: object customer: additionalProperties: false properties: checkin_status: description: The customer's checkin status. When there is no checkin status associated with the customer, checkin_status will be null. oneOf: - $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/checkin_status' - type: 'null' checkin_url: description: A short URL that can be rendered as a QR code for check-in purposes (the QR code should be 'type 4' with 'error correction H'). example: https://fhchk.co/abc format: uri type: string custom_field_values: description: A list of custom field values for the customer. items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_type_rate: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' description: The customer type rate to which this customer corresponds. invoice_cost: description: The invoice_cost will be included only if the permission View invoice prices is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - type: 'null' pk: example: 28 format: int32 type: number seat_assigned: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/seat_assigned' total_cost: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/total_cost' required: - pk - checkin_url - customer_type_rate - custom_field_values type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - example: 64 type: number - type: 'null' minimum_age: oneOf: - example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adults type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_prototype: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - total - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype type: object desk: oneOf: - additionalProperties: false properties: name: description: The desk's name. example: Windward Side type: string pk: description: The desk's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - type: 'null' effective_cancellation_policy: additionalProperties: false properties: cutoff: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types (set in the company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object extended_option: additionalProperties: false properties: description: description: The extended option's description. example: Need a helmet? format: markdown type: string description_safe_html: description: The extended option's description. example:

Need a helmet?

format: markdown type: string is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The extended option's name. example: Helmet type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The extended option's unique ID. example: 105 format: int32 type: number total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number required: - pk - name - description - description_safe_html - modifier_kind - modifier_type - offset - percentage - is_always_per_customer - is_taxable - total - total_including_tax type: object fh_waiver_signatures: description: A list of FareHarbor waivers signatures with details. items: properties: address_line: example: 7824 15th Ave type: - string - 'null' city: example: Brooklyn type: - string - 'null' country: example: US type: - string - 'null' dob: example: '1991-01-05' type: - string - 'null' email: example: johnsmith@example.com format: email type: string first_name: example: John type: string is_customer_parent: description: Indicating if the signature has any related minor records. example: false type: boolean is_marketing_allowed: description: Whether the person signing the waiver has opted in for marketing communications. example: true type: boolean last_name: example: Smith type: string phone_number: example: '+16468109900' type: - string - 'null' postcode: example: '11228' type: - string - 'null' state_province: example: NY type: - string - 'null' required: - email - first_name - last_name - is_marketing_allowed - is_customer_parent - dob - phone_number - address_line - city - state_province - postcode - country type: object type: array generated_code: additionalProperties: false properties: affiliation: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/affiliation' - type: 'null' code: description: The generated code. type: string generating_campaign: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/generating_campaign' maximum_uses: example: 10 type: number use_count: example: 1 type: number required: - affiliation - code - generating_campaign - maximum_uses - use_count type: object generating_campaign: additionalProperties: false properties: campaign: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/campaign' custom_field: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/custom_field' instructions: type: string is_per_customer: example: false type: boolean is_use_existing_codes: example: false type: boolean maximum_uses: example: 10 type: number required: - campaign - custom_field - instructions - is_per_customer - is_use_existing_codes - maximum_uses type: object item: additionalProperties: false properties: headline: description: The item's headline. example: Epic Jet Ski Tour type: string name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' required: - pk - name - headline - primary_location type: object line_item: additionalProperties: false properties: description: description: Description of the line item. type: string discount_code: oneOf: - description: The discount code applied to the line item. type: string - type: 'null' is_private: description: Whether the line item is hidden from the customer. type: boolean is_taxable: description: Whether the line item is taxable. type: boolean offset: description: Amount in the smallest currency unit (e.g. cents). type: number pk: description: The line item unique identifier. format: int32 type: number required: - pk - description - offset - is_taxable - is_private - discount_code type: object member: additionalProperties: false properties: code: description: The member's ID. example: WV8K8CG type: string created_at: description: The date and time the member was created (set in utc time). example: 2023-08-18T00:30:00-0600 format: datetime type: string membership_ranges: items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/membership_range' type: array modified_at: description: The date and time the member was last modified (set in utc time). example: 2023-08-18T00:30:00-0600 format: datetime type: string note: type: string pk: description: The members's unique ID. example: 874 format: int32 type: number required: - pk - code - created_at - modified_at - note - membership_ranges type: object membership: additionalProperties: false properties: duration: description: The duration of the membershi[p. example: 1 format: int32 type: number duration_type: enum: - days - weeks - months - years example: years type: string note: type: string pk: description: The membership's unique ID. example: 17 format: int32 type: number plural: type: string short_name: description: The membership's short name. type: string singular: type: string required: - pk - short_name - singular - plural - note - duration - duration_type type: object membership_range: additionalProperties: false properties: end_at: description: The end date of this membership range. example: '2025-08-06T00:00:00' format: datetime type: string is_cancelled: example: false type: boolean is_deferred_start: example: false type: boolean membership: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/membership' pk: description: The membership range's unique ID. example: 965 format: int32 type: number start_at: description: The start date of this membership range. example: '2024-08-06T00:00:00' format: datetime type: string utc_end_at: description: The end date of this membership range in utc. example: 2025-08-06T07:00:00+0000 format: datetime type: string utc_start_at: description: The start date of this membership range in utc. example: 2024-08-06T07:00:00+0000 format: datetime type: string required: - pk - start_at - utc_start_at - end_at - utc_end_at - is_cancelled - is_deferred_start - membership type: object payment: additionalProperties: false properties: amount_paid: oneOf: - description: The total amount that has been paid for the booking. example: 40000 type: number - type: 'null' amount_paid_display: oneOf: - description: The amount paid when the booking was first created. example: '400.00' type: string - type: 'null' created_at: description: When the payment has been paid for the booking (set in the company's local time). example: 2022-03-23T11:36:36-0700 format: datetime maxLength: 2048 type: string currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd maxLength: 3 type: string in_store_payment_note: maxLength: 128 type: - string - 'null' in_store_payment_type: oneOf: - properties: name: maxLength: 128 type: string note_label: maxLength: 128 type: string pk: type: number required: - pk - name - note_label type: object - type: 'null' initial_amount_paid: oneOf: - example: 40000 type: number - type: 'null' initial_amount_paid_display: oneOf: - example: '400.00' type: string - type: 'null' pk: example: 236495 format: int32 type: number refunds: description: Refund detail of a booking (if there is a refund). items: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/refund' type: array status: description: Status of the payment for the booking. enum: - initialed - pending - succeeded - failed example: succeeded maxLength: 2048 type: string type: description: What was used to pay for the booking. enum: - card - in-store - affiliate - stored-value-card - ideal - sofort - paypal - bancontact example: card maxLength: 2048 type: string required: - amount_paid - amount_paid_display - created_at - currency - initial_amount_paid - initial_amount_paid_display - pk - refunds - type - in_store_payment_type - in_store_payment_note - status type: object pickup: oneOf: - additionalProperties: false properties: description: type: string description_safe_html: type: string display_text: type: string map_url: format: uri type: string name: type: string time: format: time type: string required: - time - name - description - description_safe_html - map_url - display_text type: object - type: 'null' primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object refund: additionalProperties: false properties: amount_refunded: oneOf: - type: number - type: 'null' amount_refunded_display: oneOf: - type: string - type: 'null' created_at: maxLength: 2048 type: string is_cancelled: type: boolean pk: type: number required: - amount_refunded - amount_refunded_display - created_at - pk type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object seat_assigned: oneOf: - additionalProperties: false properties: name: example: Seat A type: string pk: description: The seat's unique ID. example: 84460 format: int32 type: number seat_group: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/seat_group' seat_map: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/seat_map' seat_zone: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/seat_zone' required: - pk - name - seat_map - seat_zone - seat_group type: object - description: '' type: 'null' seat_group: additionalProperties: false properties: name: example: Ungrouped type: string pk: description: The seat group's unique ID. example: 10096 format: int32 type: number required: - pk - name type: object seat_map: additionalProperties: false properties: name: example: Seat Map A type: string pk: description: The seat map's unique ID. example: 1577 format: int32 type: number required: - pk - name type: object seat_zone: additionalProperties: false properties: name: example: Default Zone type: string pk: description: The seat zone's unique ID. example: 5550 format: int32 type: number required: - pk - name type: object smartwaiver_signatures: description: A list of Smartwaiver signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string required: - email - name - is_age_verified - dob_at type: object type: array tag: additionalProperties: false properties: name: description: The tag's display name. example: Outdoor adventure type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: outdoor type: string required: - name type: object total_cost: description: The total_cost will be included only if the permission View amounts is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - type: 'null' user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object waiver_signatures: properties: fareharbor: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/fh_waiver_signatures' smartwaiver: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/smartwaiver_signatures' wherewolf: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/wherewolf_waiver_signatures' type: object wherewolf_waiver_signatures: description: A list of Wherewolf waivers signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string wherewolf_participant_status: oneOf: - enum: - Checked In - Active - Finalised - Deleted - Ineligible - Started - Loaded - Blank - Incomplete - No-Show example: Checked In type: string - description: '' type: 'null' required: - email - name - is_age_verified - dob_at - wherewolf_participant_status type: object type: array properties: booking: $ref: '#/components/schemas/BOOKING_WITH_PAYMENTS_RESPONSE_JSON_SCHEMA/definitions/booking' required: - booking type: object VERY_MINIMAL_BOOKINGS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: booking: additionalProperties: false properties: company: $ref: '#/components/schemas/VERY_MINIMAL_BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/company' pk: description: The booking's unique ID. example: 6876876 format: int32 type: number status: enum: - booked - cancelled - rebooked example: booked type: string uuid: description: The booking's universally unique identifier; used to access the booking via the API. example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid type: string required: - pk type: object bookings: items: $ref: '#/components/schemas/VERY_MINIMAL_BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/booking' type: array company: additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency type: object properties: bookings: $ref: '#/components/schemas/VERY_MINIMAL_BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/bookings' required: - bookings type: object CUSTOMER_CUSTOM_FIELD_VALUE_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: custom_field_value: additionalProperties: false properties: custom_field: type: object display_value: example: '10:01' maxLength: 2048 type: string name: example: Time In type: string pk: description: A valid Customer Custom Field Value pk. example: 4502 format: int32 type: number total_cost: type: - object - 'null' value: description: A string up to 2048 characters. If the custom field is of type yes-no, 'true' or 'false' must be specified. If the custom field is of type extended-option, an extended option pk must be specified. example: '10:01' maxLength: 2048 type: string required: - pk - custom_field - name - value - display_value - total_cost type: object properties: custom_field_value: $ref: '#/components/schemas/CUSTOMER_CUSTOM_FIELD_VALUE_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' required: - custom_field_value title: Update Customer Custom Field Value Response type: object AGENTS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: agent: additionalProperties: false properties: name: description: The agent's name. example: Eddie type: string pk: description: The agent's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object properties: agents: items: $ref: '#/components/schemas/AGENTS_RESPONSE_JSON_SCHEMA/definitions/agent' type: array required: - agents type: object CREW_MEMBER_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: crew_member: additionalProperties: false description: A user assigned to work on a specific availability. properties: note: description: A text note providing additional context about the crew member's assignment. example: Responsible for safety briefing and equipment check type: string pk: description: The crew member's unique identifier. example: 12345 format: int32 type: number role: $ref: '#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA/definitions/role' description: The role assigned to the crew member, if any. user: $ref: '#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA/definitions/user' description: The user assigned as a crew member. required: - pk - user type: object role: additionalProperties: false description: A specific position or responsibility that can be assigned to crew members. properties: pk: description: The role's unique identifier. example: 1 format: int32 type: number short_name: description: The role's short name or title. example: captain type: string required: - pk - short_name type: - object - 'null' user: additionalProperties: false description: A person who can be assigned as a crew member. properties: name: description: The user's full name. example: John Smith type: string username: description: The user's unique username. example: jsmith type: string required: - name - username type: object description: Response containing a single crew member assignment. properties: crew_member: $ref: '#/components/schemas/CREW_MEMBER_RESPONSE_JSON_SCHEMA/definitions/crew_member' description: The crew member assignment details. required: - crew_member title: Crew Member Response type: object ITEMS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - example: 64 type: number - type: 'null' minimum_age: oneOf: - example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object faq_item: additionalProperties: false properties: answer: description: FAQ answer. example: Absolutely, the more the merrier! type: string question: description: FAQ question. example: Can I bring a friend? type: string required: - question - answer type: object guided_language: additionalProperties: false properties: language_code: description: IETF BCP 47 language tag for the guided commentary. example: en type: string type: description: The delivery format of the guided commentary. enum: - in_person - recorded_audio example: in_person type: string required: - type - language_code type: object image: additionalProperties: false properties: gallery: description: The image's gallery name. example: carousel type: string image_cdn_url: description: A URL to the item's primary image. example: https://d1a2dkr8rai8e2.cloudfront.net/api/file/rvybRyLWTgyV5w4xg42p/ format: uri type: string pk: description: The image's unique ID. example: 687 format: int32 type: number required: - pk - gallery - image_cdn_url type: object item: properties: cancellation_policy: description: The item's cancellation policy. example: A full refund will be issued if notice is given at least 24 hours before start time. format: markdown type: string cancellation_policy_safe_html: description: The item's cancellation policy. example:

A full refund will be issued if notice is given at least 24 hours before start time.

format: markdown type: string customer_prototypes: description: An array of CustomerPrototype objects associated with the item. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' type: array description: description: The item's description. example: We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel. format: markdown type: string description_bullets: description: An array containing plain-text descriptive bullet points for the item. items: example: Located just 5 minutes from Waikiki. type: string type: array description_safe_html: description: The item's description. example:

We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel.

format: markdown type: string description_text: description: The item's plain-text description. example: We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel. type: string effective_cancellation_policy: additionalProperties: false properties: cutoff_hours_before: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types. example: 24 type: number - type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff_hours_before type: object headline: description: The item's headline. example: Epic Jet Ski Tour type: string health_and_safety_policy: description: The item's health and safety policy. It includes details and procedures related to specific activities for the item like the precautions being taken, equipment to bring, and any additional special rules. example: Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat. format: markdown type: string health_and_safety_policy_safe_html: description: The item's health and safety policy. It includes details and procedures related to specific activities for the item like the precautions being taken, equipment to bring, and any additional special rules. example:

Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat.

format: markdown type: string image_cdn_url: description: A URL to the item's primary image. example: https://d1a2dkr8rai8e2.cloudfront.net/api/file/rvybRyLWTgyV5w4xg42p/ format: uri type: string images: items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/image' type: array is_pickup_ever_available: description: Indicates whether the item is configured to provide pickups. example: true type: boolean location: type: string locations: items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/location' type: array name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' ratings: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/ratings' structured_description: oneOf: - $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/structured_description' - type: 'null' tags: items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/tag' type: array tax_percentage: type: number required: - pk - name - tax_percentage - headline - booking_notes - booking_notes_safe_html - description - description_safe_html - description_text - description_bullets - cancellation_policy - cancellation_policy_safe_html - location - locations - primary_location - image_cdn_url - images - customer_prototypes - is_pickup_ever_available - health_and_safety_policy - health_and_safety_policy_safe_html type: object location: additionalProperties: false properties: address: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: 90 type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: 0 type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. enum: - pre - primary - start - end example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object ratings: properties: google_reviews: oneOf: - properties: cached_at: format: date-time type: string rating: type: number user_ratings_total: type: integer required: - cached_at - user_ratings_total - rating type: object - type: 'null' tripadvisor: oneOf: - properties: cached_at: format: date-time type: string geo_location_name: type: string num_reviews: type: integer ranking: type: integer ranking_out_of: type: integer ranking_string: type: string rating: type: number rating_image_url: type: string required: - cached_at - num_reviews - rating - rating_image_url - ranking - ranking_out_of - ranking_string - geo_location_name type: object - type: 'null' required: - google_reviews - tripadvisor type: object structured_description: additionalProperties: false properties: accessibility: description: Accessibility options that are available. example: Stroller and wheelchair accessible. type: - string - 'null' cancellation_summary: description: Summary of the cancellation policy. example: A full refund will be issued if notice is given at least 24 hours before start time. type: - string - 'null' check_in_details: description: Where and how to check-in. example: Check in at the desk and scan QR code format: markdown type: - string - 'null' description: description: Description of the item and what customers can expect. example: White water rafting followed by a picnic with included food and drinks. format: markdown type: string disclaimers: description: Limitations or potential events in which the operator is not responsible. example: We cannot be held responsible if you get attacked by a bear. format: markdown type: - string - 'null' duration: description: Freeform text describing the duration. example: 2 hours type: - string - 'null' extras: description: Any equipment, add-ons or services that can be purchased. example: '

The following can be purchased:

  • Hats
  • Wetsuit rentals
' format: markdown type: - string - 'null' faq_items: description: Answers to customers frequently asked questions. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/faq_item' type: array faqs: description: Answers to customers frequently asked questions. example: 'Q: Can I bring a friend? A: Absolutely, the more the merrier!' format: markdown type: - string - 'null' group_size: description: Freeform text describing group size constraints. example: Maximum 20 adults type: - string - 'null' guided_languages: description: A list of guided language options available for the activity. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/guided_language' type: array highlights: description: What makes this activitiy special. example: Nature hike includes five different lookout spots with panoramoic views that are perfect for capturing memories with a photo. format: markdown type: - string - 'null' itinerary: description: Detailed agenda of what the customer can expect. example: '
  1. Safety lesson
  2. White water rafting
  3. Lunch break
  4. Nature hike
' format: markdown type: - string - 'null' max_age: description: Maximum age restriction. example: 65 type: - number - 'null' meeting_point: description: Freeform text describing address, city or landkmark of where to meet. example: 123 Fake Street, Fakertown CA in front of the statue. type: - string - 'null' min_age: description: Minimum age restriction. example: 5 type: - number - 'null' pricing: description: Overview of prices and options offered. example: '

Adult $20
Child $10
Children under 5 Free

' format: markdown type: - string - 'null' restrictions: description: Any restrictions that cannot be accommodated. example: Must be at least 48in tall. format: markdown type: - string - 'null' short_description: description: A concise summary describing the activity. example: White water rafting. type: - string - 'null' special_requirements: description: Any requirements that should be known before booking. example: Children under the age of 16 must be accompanied by an adult. format: markdown type: - string - 'null' what_is_included: description: What is included in the price of the activity. example: '
  • Water
  • Snacks
' format: markdown type: - string - 'null' what_is_included_items: description: List of items that are included in the price of the activity. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/what_is_included_item' type: array what_is_not_included: description: What is not included in the price of the activity. example: '
  • Towels
  • Wetsuit rentals
' format: markdown type: - string - 'null' what_is_not_included_items: description: List of items that are not included in the price of the activity. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/what_is_not_included_item' type: array what_to_bring: description: Any items the customer should bring. example: '
  • Swimsuit
  • Towel
' format: markdown type: - string - 'null' what_to_bring_items: description: List of items that the customer should bring. items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/what_to_bring_item' type: array type: object tag: additionalProperties: false properties: name: description: The tag's display name. example: Jet ski Tour type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: jet-ski-tour type: string required: - name type: object what_is_included_item: additionalProperties: false properties: value: description: Included item text. example: Water type: string required: - value type: object what_is_not_included_item: additionalProperties: false properties: value: description: Not included item text. example: Towels type: string required: - value type: object what_to_bring_item: additionalProperties: false properties: value: description: What to bring item text. example: Swimsuit type: string required: - value type: object properties: items: items: $ref: '#/components/schemas/ITEMS_RESPONSE_JSON_SCHEMA/definitions/item' type: array required: - items type: object MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: availability: properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance_summary' type: array customer_type_rates: items: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_booking_cutoff: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/effective_booking_cutoff' effective_cancellation_policy: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's public headline. Only included when `detailed=yes`. example: Epic Jet Ski Tour type: string maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - customer_type_rates type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field_instance_summary: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field_summary' pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object custom_field_summary: additionalProperties: false properties: is_priced: description: Indicates whether the custom field has pricing configured. example: false type: boolean is_required: description: Indicates whether the custom field requires a value. example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Weight type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number total: description: The absolute price of a single custom field of this type when modifier_kind is offset. May be 0 for percentage pricing until applied to a base amount. example: 20000 type: number type: description: The custom field's type. example: short type: string required: - pk - name - type - is_required - is_priced - modifier_kind - modifier_type - offset - percentage - total type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - description: The maximum age for this customer type (inclusive). example: 64 type: number - type: 'null' minimum_age: oneOf: - description: The minimum age for this customer type (inclusive). example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adults type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural - note type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance_summary' type: array customer_prototype: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number required: - pk - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype type: object cutoff_time: oneOf: - description: The cutoff time (in company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - type: 'null' effective_booking_cutoff: additionalProperties: false properties: cutoff: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/cutoff_time' required: - cutoff type: object effective_cancellation_policy: additionalProperties: false properties: cutoff: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/cutoff_time' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object properties: availabilities: items: $ref: '#/components/schemas/MINIMAL_AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/availability' type: array required: - availabilities type: object ROLES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: role: additionalProperties: false description: A specific position or responsibility that can be assigned to crew members. properties: pk: description: The role's unique identifier. example: 1 format: int32 type: number short_name: description: The role's short name or title used for identification and assignment. example: captain type: string required: - pk - short_name type: object description: Response containing the list of roles available for a company. properties: roles: description: List of roles available for assignment to crew members. items: $ref: '#/components/schemas/ROLES_RESPONSE_JSON_SCHEMA/definitions/role' type: array required: - roles title: Roles Response type: object COMPANY_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object company: additionalProperties: false properties: about: description: About page content for the company. example: Hawaiian Adventures offers several water activities that you are sure to enjoy. format: markdown type: string about_safe_html: description: About page content for the company. example:

Hawaiian Adventures offers several water activities that you are sure to enjoy.

format: markdown type: string address: $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/address' description: The company's physical address. affiliated_since: description: "If the API user\u2019s company is an affiliate, then we will\ \ see a timestamp of when the relationship started (set in utc time)." example: 2020-06-17T15:44:03+0000 format: datetime oneOf: - description: "If the API user\u2019s company is an affiliate, then we\ \ will see a timestamp of when the relationship started (set in utc\ \ time)." example: 2020-06-17T15:44:03+0000 format: datetime type: string - type: 'null' billing_address: $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/address' description: The company's billing address. booking_notes: description: General notes for booking customers. example: 'Weather conditions will be evaluated at the time of check-in. -If using a voucher, please bring the voucher with you.' format: markdown type: string booking_notes_safe_html: description: General notes for booking customers. example: '

Weather conditions will be evaluated at the time of check-in. -If using a voucher, please bring the voucher with you.

' format: markdown type: string contact_email: description: The company's contact email. example: info@hawaiianadventures.com type: string contact_phone: description: The company's contact phone. example: +1-808-555-1234 type: string currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string facebook_url: description: The company's Facebook address. example: https://facebook.com/url format: uri type: string faq: description: FAQ page content for the company. example: '# What should I bring? We suggest that you bring a swimming suit, a towel, and sunscreen.' format: markdown type: string faq_safe_html: description: FAQ page content for the company. example: '

What should I bring?

We suggest that you bring a swimming suit, sunscreen, and a towel.

' format: markdown type: string health_and_safety_policy: description: The company's health and safety policy. This is supplemental to the item level health_and_safety_policy field, and is only displayed on the FareHarbor Dashboard if the specific item does not have a value for health_and_safety_policy set. example: "Your health is our top priority, and we have put special measures\ \ in place to keep all guests safe both during and after your activity.\n\ \n* Stringent Cleaning \u2013 We've increased the frequency of disinfecting\ \ surfaces and high touch areas.\n* Social Distancing \u2013 Guests are\ \ required to stay 6 feet apart.\n* Wellness Checks \u2013 Employees receive\ \ daily wellness checks to ensure they are healthy and symptom-free." format: markdown type: string health_and_safety_policy_safe_html: description: The company's health and safety policy. This is supplemental to the item level health_and_safety_policy field, and is only displayed on the FareHarbor Dashboard if the specific item does not have a value for health_and_safety_policy set. example: "

Your health is our top priority, and we have put special measures\ \ in place to keep all guests safe both during and after your activity.

\n\
    \n
  • Stringent Cleaning \u2013 We've increased the frequency of disinfecting\ \ surfaces and high touch areas.
    • \n
  • Social Distancing \u2013 Guests\ \ are required to stay 6 feet apart.
    • \n
  • Wellness Checks \u2013\ \ Employees receive daily wellness checks to ensure they are healthy and\ \ symptom-free.
    • \n
" format: markdown type: string instagram_url: description: The company's Instagram address. example: https://instagram.com/url format: uri type: string intro: description: Homepage content for the company. example: We offer the best water activities on Oahu format: markdown type: string intro_safe_html: description: Homepage content for the company. example:

We offer the best water activities on Oahu

format: markdown type: string name: description: The company's name. example: Hawaiian Adventures type: string open_hours: description: Represents the company's general opening and closing times. Used for general company information or for context for all-day availabilities, but should not be used in place of specific availability start and end times. oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours' description: Represents the company's general opening and closing times. Used for general company information or for context for all-day availabilities, but should not be used in place of specific availability start and end times. - type: 'null' pinterest_url: description: The company's Pinterest address. example: https://pintrest.com/url format: uri type: string primary_location: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/location' - type: 'null' primary_location_heading: example: 1 Ma'alaea way, Wailuku, HI, 95656 type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string summary: description: A short tagline or summary for the company. example: Water activities 365 days a year type: string timezone: description: The company's local timezone. example: America/Los_Angeles type: string tripadvisor_url: description: The company's Trip Advisor address. example: https://tripadvisor.com/url format: uri type: string twitter_url: description: The company's Twitter address. example: https://twitter.com/url format: uri type: string url: description: The company's website address. example: https://company-url.com format: uri type: string yelp_url: description: The company's Yelp address. example: https://yelp.com/url format: uri type: string youtube_url: description: The company's Youtube address. example: https://youtube.com/url format: uri type: string required: - shortname - name - url - facebook_url - instagram_url - tripadvisor_url - twitter_url - yelp_url - youtube_url - pinterest_url - currency - summary - about - about_safe_html - booking_notes - booking_notes_safe_html - faq - faq_safe_html - intro - intro_safe_html - address - billing_address - primary_location - primary_location_heading - health_and_safety_policy - health_and_safety_policy_safe_html - open_hours - affiliated_since - timezone - contact_email - contact_phone type: object location: additionalProperties: false properties: address: $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: 90 type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: 0 type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object open_hours: additionalProperties: false properties: friday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' monday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' saturday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' sunday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' thursday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' tuesday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' wednesday: oneOf: - $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/open_hours_weekday' - type: 'null' required: - sunday - monday - tuesday - wednesday - thursday - friday - saturday type: object open_hours_weekday: additionalProperties: false properties: close_time: example: '17:00' format: time type: string open_time: example: '10:00' format: time type: string required: - open_time - close_time type: object properties: company: $ref: '#/components/schemas/COMPANY_RESPONSE_JSON_SCHEMA/definitions/company' required: - company type: object DESKS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: desk: additionalProperties: false properties: name: description: The desk's name. example: Windward Side type: string pk: description: The desk's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object properties: desks: items: $ref: '#/components/schemas/DESKS_RESPONSE_JSON_SCHEMA/definitions/desk' type: array required: - desks type: object RESEND_CONFIRMATION_EMAIL_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false description: Generic response returned whether or not any bookings matched. properties: message: description: Generic acknowledgement that does not reveal whether bookings matched. example: Any matching confirmation emails have been queued for delivery. type: string required: - message title: Resend Confirmation Email Response type: object CHECKIN_STATUSES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: checkin-status: additionalProperties: false description: The customer's checkin status. When there is no checkin status associated with the customer, checkin_status will be null. properties: name: description: The checkin status' name. example: checked in type: string pk: example: 10 format: int32 type: number type: example: checked-in type: string required: - pk - name - type type: object properties: checkin_statuses: items: $ref: '#/components/schemas/CHECKIN_STATUSES_RESPONSE_JSON_SCHEMA/definitions/checkin-status' type: array required: - checkin_statuses type: object BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object affiliate_company: oneOf: - additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The affiliate companies name. example: Affiliate Company type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: affiliate_company type: string required: - shortname - name - currency type: object - description: '' type: 'null' affiliate_metadata: description: Metadata from affiliate sources. properties: airbnb: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/airbnb_metadata' type: object affiliation: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' required: - affiliate_company type: object agent: oneOf: - additionalProperties: false properties: name: description: The agent's name. example: Eddie type: string pk: description: The agent's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' airbnb_guest_profile: description: An Airbnb guest profile. properties: direct_thread_id: description: The direct thread ID for the guest. example: '2164961599' type: - string - 'null' user_id: description: The Airbnb user ID. example: '17780410' type: - string - 'null' type: object airbnb_metadata: description: Metadata from Airbnb bookings. properties: activity_id: description: The Airbnb activity ID. example: '6137649' type: - string - 'null' channel_thread_id: description: The Airbnb channel thread ID. example: '2199079188' type: - string - 'null' guest_id: description: The Airbnb guest ID. example: '17780410' type: - string - 'null' guest_profiles: description: List of Airbnb guest profiles. items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/airbnb_guest_profile' type: - array - 'null' host_id: description: The Airbnb host ID. example: '1234' type: - string - 'null' offering_id: description: The Airbnb offering ID. example: '5495433' type: - string - 'null' type: object arrival: oneOf: - additionalProperties: false properties: display_text: description: A formatted string that can be shown to customers. example: Please arrive by 12:15 pm type: string notes: description: Notes from the activity company regarding arrival (e.g. check-in location details, driving directions); may not be provided. example: 'Check-in Time is at 12:15 for your 12:45 Zipline adventure time. Our check-in locations is at our KapohoKine Adventures Store: 224 Kamehameha Ave Suite 106 Hilo, HI 96720' format: markdown type: string notes_safe_html: example: 'Check-in Time is at 12:15 for your 12:45 Zipline adventure time. Our check-in locations is at our KapohoKine Adventures Store: 224 Kamehameha Ave Suite 106 Hilo, HI 96720' format: markdown type: string time: description: The arrival time (set in the company's local time); the customer must provide their own transporation and arrive at the activity location by this time. example: 2024-04-11T13:15:00-1000 format: datetime type: string required: - time - notes - notes_safe_html - display_text type: object - description: '' type: 'null' availability: additionalProperties: false properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_type_rates: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's headline. example: Epic Jet Ski Tour type: string item: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/item' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - headline - item - customer_type_rates - custom_field_instances type: object booking: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' affiliate_metadata: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/affiliate_metadata' agent: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/agent' amount_paid: oneOf: - type: number - type: 'null' amount_paid_display: oneOf: - example: '0.0' type: string - type: 'null' arrival: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/arrival' availability: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/availability' description: The availability to which this booking corresponds. booked_by: oneOf: - type: 'null' - additionalProperties: false properties: name: type: string required: - name type: object company: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/company' confirmation_url: description: The booking's confirmation page URL. format: uri type: string contact: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/contact' description: Contact information for this booking. created_at: description: The date and time at which the booking was created (set in utc time). example: 2024-06-20T17:14:33+0000 format: datetime type: string custom_field_values: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_count: description: The number of customers on this booking. example: 1 type: number customers: description: A list of customers on this booking. items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/customer' type: array dashboard_url: description: The booking's dashboard URL. example: https://fareharbor.com/hawaiianadventures/dashboard/?overlay=/contacts/7/bookings/d75102be-9732-4523-90a8-c698eff2b983/ format: uri type: string desk: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/desk' display_id: example: '#6876876' type: string effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' external_id: description: An additional identifier if necessary. maxLength: 128 type: string generated_codes: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/generated_code' type: array invoice_price: oneOf: - description: The invoice price of this booking. Assuming that the user of the API is a reseller this will be the amount that the user of the API owes the vendor on this booking, if the vendor has opted to set up that information; otherwise it will be null. type: number - type: 'null' invoice_price_display: oneOf: - type: string - type: 'null' is_eligible_for_cancellation: example: true type: boolean is_follow_up_email_disabled: type: boolean is_reminder_email_disabled: type: boolean is_subscribed_for_sms_updates: description: Whether or not the contact would like the booking company to send them SMS updates about this booking. Note that the value of this field does not reflect whether or not the user has sent a STOP request to FareHarbor. If the user sends a STOP request to an External API client, that API client should respect that request. example: false type: boolean line_items: description: Line items on the booking. items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/line_item' type: array lodging: oneOf: - additionalProperties: false properties: name: description: The lodging's name. example: Eddie type: string pk: description: The lodging's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' note: example: '' format: markdown type: string note_safe_html: example: '' format: markdown type: string online_booking_references: example: '' type: string order: description: When there is no order associated with the booking, order will be null. oneOf: - properties: display_id: description: A unique identifier for the order example: ABTT type: string type: object - description: '' type: 'null' pickup: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/pickup' pk: description: The booking's unique ID. example: 6876876 format: int32 type: number rebooked_from: oneOf: - description: See [Rebooking](#tag/Rebooking) example: d75102be-9732-4523-90a8-c698eff2b983 type: string - type: 'null' rebooked_to: oneOf: - description: See [Rebooking](#tag/Rebooking) example: 10414711-3d20-4f4d-8ab3-eeaea26c2be3 type: string - type: 'null' receipt_subtotal: oneOf: - example: 36000 type: number - type: 'null' receipt_subtotal_display: oneOf: - example: '360.00' type: string - type: 'null' receipt_taxes: oneOf: - example: 2776 type: number - type: 'null' receipt_taxes_display: oneOf: - example: '27.76' type: string - type: 'null' receipt_total: oneOf: - example: 38776 type: number - type: 'null' receipt_total_display: oneOf: - example: '387.76' type: string - type: 'null' related_bookings: properties: related_order: properties: bookings: description: Booking UUIDs related to the order example: - d75102be-9732-4523-90a8-c698eff2b983 - a99e711d-2c70-48ce-87ff-0818942c3489 items: type: string type: array id: description: Order ID example: ABTT type: string type: object type: object resource_uses: description: Resource uses (e.g. vehicle assignments) for this booking. items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/resource_use' type: array source_type: enum: - online - direct - pos - reseller - external-api - kiosk - imported - unkown example: online type: string status: enum: - booked - cancelled - rebooked example: booked type: string uuid: description: The booking's universally unique identifier; used to access the booking via the API. example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid type: string voucher_number: example: '' type: string waiver_signatures: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/waiver_signatures' required: - pk - uuid - availability - contact - company - affiliate_company - customers - invoice_price - invoice_price_display - display_id - external_id - order - status - rebooked_from - rebooked_to - confirmation_url - voucher_number - online_booking_references - receipt_subtotal - receipt_subtotal_display - receipt_taxes - receipt_taxes_display - receipt_total - receipt_total_display - amount_paid - amount_paid_display - custom_field_values - note - note_safe_html - pickup - arrival - effective_cancellation_policy - is_eligible_for_cancellation - agent - desk - dashboard_url - customer_count - is_subscribed_for_sms_updates - is_follow_up_email_disabled - is_reminder_email_disabled - created_at - source_type - booked_by - generated_codes - waiver_signatures - line_items - lodging - related_bookings - resource_uses type: object campaign: additionalProperties: false properties: created_at: description: The date and time the campaign was created at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string is_archived: example: false type: boolean name: example: August Discounts type: string prefix: example: FH type: string summary: type: string required: - created_at - is_archived type: object checkin_status: additionalProperties: false properties: name: description: The checkin status' name. example: checked in type: string pk: example: 10 format: int32 type: number type: type: string required: - pk - name - type type: object company: additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency type: object contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string is_subscribed_for_email_updates: description: Whether or not the contact would like email updates. example: false type: boolean language: description: The contact language. example: en-us type: string member: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/member' - type: 'null' name: description: The name of the head of the party. example: Surfer Dude type: string normalized_phone: description: The party's contact phone number. This will have a plus sign, the country code, and no extra characters such as commas or dashes. example: '+14432221100' type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string phone_country: oneOf: - description: The contact phone's country code. example: US type: string - type: 'null' required: - name - phone - phone_country - normalized_phone - email - is_subscribed_for_email_updates type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field: additionalProperties: false properties: booking_notes: description: General notes for booking customers. example: Weather conditions will be evaluated at the time of check-in.\n\n-If using a voucher, please bring the voucher with you. format: markdown type: string booking_notes_safe_html: description: Notes for the customer specific to the custom field. format: markdown type: string count_max: description: The maximum amount possible for a count type custom field. example: 300 type: number count_min: description: The minimum amount possible for a count type custom field. example: 0 type: number description: description: The custom field's description. example: Do you need additional safety equipment? format: markdown type: string description_safe_html: description: The custom field's description. example:

Do you need additional safety equipment?

format: markdown type: string extended_options: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/extended_option' type: array is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_required: description: Indicates whether the custom field requires a value. example: false type: boolean is_taxable: description: Whether the cost of this option should affect the taxable total of a booking. example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Safety Equipment type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number tags: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/tag' type: array title: type: string total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number type: description: The custom field's type. enum: - yes-no - short - long - extended-option - count - multi-campaign - code-generator - date example: yes-no type: string required: - pk - type - is_required - description - description_safe_html - name - booking_notes - booking_notes_safe_html - offset - total - total_including_tax type: object custom_field_instance: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field' pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object custom_field_value: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field' display_value: example: 'false' maxLength: 2048 type: string name: example: Name type: string pk: description: A valid Custom Field pk. example: 4502 format: int32 type: number total_cost: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/total_cost' value: description: A string up to 2048 characters. If the custom field is of type yes-no, 'true' or 'false' must be specified. If the custom field is of type extended-option, an extended option pk must be specified. example: 'false' maxLength: 2048 type: string required: - pk - custom_field - name - value - display_value - total_cost type: object customer: additionalProperties: false properties: checkin_status: description: The customer's checkin status. When there is no checkin status associated with the customer, checkin_status will be null. oneOf: - $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/checkin_status' - description: '' type: 'null' checkin_url: description: A short URL that can be rendered as a QR code for check-in purposes (the QR code should be 'type 4' with 'error correction H'). example: https://fhchk.co/abc format: uri type: string custom_field_values: description: A list of custom field values for the customer. items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_type_rate: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' description: The customer type rate to which this customer corresponds. invoice_cost: description: The invoice_cost will be included only if the permission View invoice prices is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - description: '' type: 'null' pk: example: 28 format: int32 type: number resource_use_pks: description: The unique IDs of the resource uses linked to this customer, sorted by resource use ID. items: format: int32 type: number type: array seat_assigned: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/seat_assigned' total_cost: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/total_cost' required: - pk - checkin_url - customer_type_rate - custom_field_values type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - example: 64 type: number - type: 'null' minimum_age: oneOf: - example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adults type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_prototype: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - total - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype type: object desk: oneOf: - additionalProperties: false properties: name: description: The desk's name. example: Windward Side type: string pk: description: The desk's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' effective_cancellation_policy: additionalProperties: false properties: cutoff: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types (set in the company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - description: '' type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object extended_option: additionalProperties: false properties: description: description: The extended option's description. example: Need a helmet? format: markdown type: string description_safe_html: description: The extended option's description. example:

Need a helmet?

format: markdown type: string is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The extended option's name. example: Helmet type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The extended option's unique ID. example: 105 format: int32 type: number total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number required: - pk - name - description - description_safe_html - modifier_kind - modifier_type - offset - percentage - is_always_per_customer - is_taxable - total - total_including_tax type: object fh_waiver_signatures: description: A list of FareHarbor waivers signatures with details. items: properties: address_line: example: 7824 15th Ave type: - string - 'null' city: example: Brooklyn type: - string - 'null' country: example: US type: - string - 'null' dob: example: '1991-01-05' type: - string - 'null' email: example: johnsmith@example.com format: email type: string first_name: example: John type: string is_customer_parent: description: Indicating if the signature has any related minor records. example: false type: boolean is_marketing_allowed: description: Whether the person signing the waiver has opted in for marketing communications. example: true type: boolean last_name: example: Smith type: string phone_number: example: '+16468109900' type: - string - 'null' postcode: example: '11228' type: - string - 'null' state_province: example: NY type: - string - 'null' required: - email - first_name - last_name - is_marketing_allowed - is_customer_parent - dob - phone_number - address_line - city - state_province - postcode - country type: object type: array generated_code: additionalProperties: false properties: affiliation: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/affiliation' - type: 'null' code: description: The generated code. type: string generating_campaign: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/generating_campaign' maximum_uses: example: 10 type: number use_count: example: 1 type: number required: - affiliation - code - generating_campaign - maximum_uses - use_count type: object generating_campaign: additionalProperties: false properties: campaign: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/campaign' custom_field: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/custom_field' instructions: type: string is_per_customer: example: false type: boolean is_use_existing_codes: example: false type: boolean maximum_uses: example: 10 type: number required: - campaign - custom_field - instructions - is_per_customer - is_use_existing_codes - maximum_uses type: object item: additionalProperties: false properties: headline: description: The item's headline. example: Epic Jet Ski Tour type: string name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' required: - pk - name - headline - primary_location type: object line_item: additionalProperties: false properties: description: description: Description of the line item. type: string discount_code: oneOf: - description: The discount code applied to the line item. type: string - type: 'null' is_private: description: Whether the line item is hidden from the customer. type: boolean is_taxable: description: Whether the line item is taxable. type: boolean offset: description: Amount in the smallest currency unit (e.g. cents). type: number pk: description: The line item unique identifier. format: int32 type: number required: - pk - description - offset - is_taxable - is_private - discount_code type: object member: additionalProperties: false properties: code: description: The member's ID. example: WV8K8CG type: string created_at: description: The date and time the member was created at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string membership_ranges: items: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/membership_range' type: array modified_at: description: The date and time the member was last modified at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string note: type: string pk: description: The members's unique ID. example: 874 format: int32 type: number required: - pk - code - created_at - modified_at - note - membership_ranges type: object membership: additionalProperties: false properties: duration: description: The duration of the membershi[p. example: 1 format: int32 type: number duration_type: enum: - days - weeks - months - years example: years type: string note: type: string pk: description: The membership's unique ID. example: 17 format: int32 type: number plural: type: string short_name: description: The membership's short name. type: string singular: type: string required: - pk - short_name - singular - plural - note - duration - duration_type type: object membership_range: additionalProperties: false properties: end_at: description: The end date of this membership range. example: '2025-08-06T00:00:00' format: datetime type: string is_cancelled: example: false type: boolean is_deferred_start: example: false type: boolean membership: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/membership' pk: description: The membership range's unique ID. example: 965 format: int32 type: number start_at: description: The start date of this membership range. example: '2024-08-06T00:00:00' format: datetime type: string utc_end_at: description: The end date of this membership range in utc. example: 2025-08-06T07:00:00+0000 format: datetime type: string utc_start_at: description: The start date of this membership range in utc. example: 2024-08-06T07:00:00+0000 format: datetime type: string required: - pk - start_at - utc_start_at - end_at - utc_end_at - is_cancelled - is_deferred_start - membership type: object pickup: description: If a lodging is specified and transportation is not available for the specified lodging (or any lodging), the pickup property will have a null value. oneOf: - additionalProperties: false properties: description: description: Pickup instructions from the activity company; may not be provided. example: Please meet us at the front entrance of your hotel and allow a 15 minute window for your driver to arrive. format: markdown type: string description_safe_html: description: Pickup instructions from the activity company; may not be provided. example: Please meet us at the front entrance of your hotel and allow a 15 minute window for your driver to arrive. format: markdown type: string display_text: description: A formatted string that can be shown to customers. example: We'll pick you up at 10:30am from Wyndham Royal Garden type: string map_url: description: A URL to a map showing the pickup location; may not be provided. example: https://goo.gl/maps/6QiYT format: uri type: string name: description: The name of the pickup location. example: Wyndham Royal Garden type: string time: description: The pickup time; the customer must arrive at the pickup location by this time. example: 2016-08-01T10:30:00-1000 format: time type: string required: - time - name - description - description_safe_html - map_url - display_text type: object - description: '' type: 'null' primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object resource_for_use: additionalProperties: false properties: name: description: The resource's name. type: string pk: description: The resource's unique ID. format: int32 type: number short_name: description: The resource's short name. type: string required: - pk - name - short_name type: object resource_use: additionalProperties: false properties: customer_pk: description: The unique ID of the customer this resource use belongs to, or null for booking-level resource uses. format: int32 type: - number - 'null' end_at: description: The resource use end time. format: datetime type: string pk: description: The resource use's unique ID. format: int32 type: number resource: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/resource_for_use' start_at: description: The resource use start time. format: datetime type: string use_count: description: The amount of resource consumed. type: number required: - pk - resource - use_count - start_at - end_at type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object seat_assigned: oneOf: - additionalProperties: false properties: name: example: Seat A type: string pk: description: The seat's unique ID. example: 84460 format: int32 type: number seat_group: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/seat_group' seat_map: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/seat_map' seat_zone: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/seat_zone' required: - pk - name - seat_map - seat_zone - seat_group type: object - description: '' type: 'null' seat_group: additionalProperties: false properties: name: example: Ungrouped type: string pk: description: The seat group's unique ID. example: 10096 format: int32 type: number required: - pk - name type: object seat_map: additionalProperties: false properties: name: example: Seat Map A type: string pk: description: The seat map's unique ID. example: 1577 format: int32 type: number required: - pk - name type: object seat_zone: additionalProperties: false properties: name: example: Default Zone type: string pk: description: The seat zone's unique ID. example: 5550 format: int32 type: number required: - pk - name type: object smartwaiver_signatures: description: A list of Smartwaiver signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string required: - email - name - is_age_verified - dob_at type: object type: array tag: additionalProperties: false properties: name: description: The tag's display name. example: Outdoor adventure type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: outdoor type: string required: - name type: object total_cost: description: The total_cost will be included only if the permission View amounts is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - description: '' type: 'null' user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object waiver_signatures: properties: fareharbor: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/fh_waiver_signatures' smartwaiver: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/smartwaiver_signatures' wherewolf: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/wherewolf_waiver_signatures' type: object wherewolf_waiver_signatures: description: A list of Wherewolf waivers signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string wherewolf_participant_status: oneOf: - enum: - Checked In - Active - Finalised - Deleted - Ineligible - Started - Loaded - Blank - Incomplete - No-Show example: Checked In type: string - description: '' type: 'null' required: - email - name - is_age_verified - dob_at - wherewolf_participant_status type: object type: array properties: booking: $ref: '#/components/schemas/BOOKING_WITH_RESOURCE_USES_RESPONSE_JSON_SCHEMA/definitions/booking' required: - booking type: object CREW_MEMBERS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: crew_member: additionalProperties: false description: A user assigned to work on a specific availability. properties: note: description: A text note providing additional context about the crew member's assignment. example: Responsible for safety briefing and equipment check type: string pk: description: The crew member's unique identifier. example: 12345 format: int32 type: number role: $ref: '#/components/schemas/CREW_MEMBERS_RESPONSE_JSON_SCHEMA/definitions/role' description: The role assigned to the crew member, if any. user: $ref: '#/components/schemas/CREW_MEMBERS_RESPONSE_JSON_SCHEMA/definitions/user' description: The user assigned as a crew member. required: - pk - note - user type: object role: additionalProperties: false description: A specific position or responsibility that can be assigned to crew members. properties: pk: description: The role's unique identifier. example: 1 format: int32 type: number short_name: description: The role's short name or title. example: captain type: string required: - pk - short_name type: - object - 'null' user: additionalProperties: false description: A person who can be assigned as a crew member. properties: name: description: The user's full name. example: John Smith type: string username: description: The user's unique username. example: jsmith type: string required: - name - username type: object description: Response containing a list of crew members assigned to an availability. properties: crew_members: description: List of crew members assigned to the availability. items: $ref: '#/components/schemas/CREW_MEMBERS_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array required: - crew_members title: Crew Members Response type: object COMPANIES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object company: additionalProperties: false properties: affiliated_since: description: "If the API user\u2019s company is an affiliate, then we will\ \ see a timestamp of when the relationship started (set in utc time)." example: 2020-06-17T15:44:03+0000 format: datetime oneOf: - description: "If the API user\u2019s company is an affiliate, then we\ \ will see a timestamp of when the relationship started (set in utc\ \ time)." example: 2020-06-17T15:44:03+0000 format: datetime type: string - type: 'null' contact_email: description: The company's contact email. example: info@hawaiianadventures.com type: string contact_phone: description: The company's contact phone. example: +1-808-555-1234 type: string currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string primary_location: oneOf: - $ref: '#/components/schemas/COMPANIES_RESPONSE_JSON_SCHEMA/definitions/location' - type: 'null' shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency - affiliated_since - primary_location - contact_email - contact_phone type: object location: additionalProperties: false properties: address: $ref: '#/components/schemas/COMPANIES_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: 90 type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: 0 type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object properties: companies: items: $ref: '#/components/schemas/COMPANIES_RESPONSE_JSON_SCHEMA/definitions/company' type: array required: - companies type: object USERS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: user: additionalProperties: false description: A user created in the Fareharbor Dashboard properties: name: description: The user's full name as it appears in the system. example: John Smith type: string username: description: The user's unique username within the system. example: jsmith type: string required: - username - name type: object description: Response containing a list of all distinct users created in the FareHarbor Dashboard. properties: users: description: List of all company users. items: $ref: '#/components/schemas/USERS_RESPONSE_JSON_SCHEMA/definitions/user' type: array required: - users title: Users Response type: object AVAILABILITY_LODGINGS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: lodging: additionalProperties: false properties: is_pickup_available: description: Indicates whether a pickup is offered for the lodging (for the availability specified in the request URL). This value reflects the current state of the system and can change when updates are made. example: true type: boolean name: description: The lodging's name. example: Wyndham Royal Garden type: string pickup_time: description: The preferred pickup time (set in the company's local time). example: 2024-10-08T09:00:00-0400 format: datetime type: - string - 'null' pk: description: The lodging's unique ID. example: 2314 format: int32 type: number preferred_pickup: $ref: '#/components/schemas/AVAILABILITY_LODGINGS_RESPONSE_JSON_SCHEMA/definitions/preferred_pickup' required: - pk - name - is_pickup_available type: object preferred_pickup: additionalProperties: false properties: latitude: description: The preferred pickup location's latitude. example: '-157.85' type: - number - 'null' longitude: description: The preferred pickup location's longitude. example: '21.30' type: - number - 'null' map_url: description: The google maps link of the preferred pickup location example: https://goo.gl/maps/qW2THBcd5Pj8Ga8w6 format: uri type: string name: description: The name of the preferred pickup location example: Frankton Bus Shelter type: string required: - name - map_url - longitude - latitude type: object properties: lodgings: items: $ref: '#/components/schemas/AVAILABILITY_LODGINGS_RESPONSE_JSON_SCHEMA/definitions/lodging' type: array required: - lodgings type: object BOOKINGS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: affiliate_company: oneOf: - additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The affiliate companies name. example: Affiliate Company type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: affiliate_company type: string required: - shortname - name - currency type: object - description: '' type: 'null' booking: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' booked_by: oneOf: - type: 'null' - additionalProperties: false properties: name: type: string required: - name type: object company: $ref: '#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/company' contact: $ref: '#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/contact' description: Contact information for this booking. created_at: description: The date and time at which the booking was created (set in utc time). example: 2024-06-20T17:14:33+0000 format: datetime type: string dashboard_url: description: The booking's dashboard URL. example: https://fareharbor.com/hawaiianadventures/dashboard/?overlay=/contacts/7/bookings/d75102be-9732-4523-90a8-c698eff2b983/ format: uri type: string display_id: example: '#6876876' type: string external_id: description: An additional identifier if necessary. maxLength: 128 type: string order: description: When there is no order associated with the booking, order will be null. oneOf: - properties: display_id: type: string type: object - description: '' type: 'null' pk: description: The booking's unique ID. example: 6876876 format: int32 type: number rebooked_from: oneOf: - type: string - type: 'null' rebooked_to: oneOf: - type: string - type: 'null' source_type: enum: - online - direct - pos - reseller - external-api - kiosk - imported - unkown example: online type: string status: enum: - booked - cancelled - rebooked example: booked type: string uuid: description: The booking's universally unique identifier; used to access the booking via the API. example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid type: string required: - pk - uuid - company - affiliate_company - display_id - external_id - status - rebooked_from - rebooked_to - dashboard_url - created_at - source_type - booked_by type: object bookings: items: $ref: '#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/booking' type: array company: additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency type: object contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string is_subscribed_for_email_updates: description: Whether or not the contact would like email updates. example: false type: boolean language: description: The contact language. example: en-us type: string name: description: The name of the head of the party. example: Surfer Dude type: string normalized_phone: description: The party's contact phone number. This will have a plus sign, the country code, and no extra characters such as commas or dashes. example: '+14432221100' type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string phone_country: oneOf: - description: The contact phone's country code. example: US type: string - type: 'null' required: - language - name - email - is_subscribed_for_email_updates - phone - phone_country - normalized_phone type: object properties: bookings: $ref: '#/components/schemas/BOOKINGS_RESPONSE_JSON_SCHEMA/definitions/bookings' required: - bookings type: object LODGINGS_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: lodging: additionalProperties: false properties: address: description: The lodging's address. example: 440 Olohana St Honolulu, HI 96815 type: string is_self_lodging: description: Whether the lodging is a customer provided, non-hotel lodging (e.g. private residence). example: false type: boolean name: description: The lodging's name. example: Wyndham Royal Garden type: string phone: description: The lodging's phone number. example: (808) 943-0202 type: string pk: description: The lodging's unique ID. example: 2314 format: int32 type: number url: description: The lodging's URL. example: https://www.extraholidays.com/honolulu-hawaii/royal-garden-at-waikiki.aspx format: uri type: string required: - pk - name - phone - address - url - is_self_lodging type: object properties: lodgings: items: $ref: '#/components/schemas/LODGINGS_RESPONSE_JSON_SCHEMA/definitions/lodging' type: array required: - lodgings type: object AVAILABILITY_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object availability: properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_type_rates: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_booking_cutoff: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/effective_booking_cutoff' effective_cancellation_policy: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's headline. example: Epic Jet Ski Tour type: string item: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/item' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - headline - item - customer_type_rates - custom_field_instances type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field: additionalProperties: false properties: booking_notes: description: Notes for the customer specific to the custom field. example: '' format: markdown type: string booking_notes_safe_html: description: Notes for the customer specific to the custom field. format: markdown type: string count_max: description: The maximum amount possible for a count type custom field. example: 300 type: number count_min: description: The minimum amount possible for a count type custom field. example: 0 type: number description: description: The custom field's description. example: Do you need additional safety equipment? format: markdown type: string description_safe_html: description: The custom field's description. example:

Do you need additional safety equipment?

format: markdown type: string extended_options: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/extended_option' type: array is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_required: description: Indicates whether the custom field requires a value. example: false type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Safety Equipment type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number tags: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/tag' type: array title: type: string total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number type: description: The custom field's type. enum: - yes-no - short - long - extended-option - count example: extended-option type: string required: - pk - type - is_required - description - description_safe_html - name - booking_notes - booking_notes_safe_html - offset - total - total_including_tax type: object custom_field_instance: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/custom_field' description: The custom field associated with the custom field instance. pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - description: The maximum age for this customer type (inclusive). example: 64 type: number - type: 'null' minimum_age: oneOf: - description: The minimum age for this customer type (inclusive). example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adults type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural - note type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_prototype: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - total - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype - custom_field_instances type: object cutoff_time: oneOf: - description: The cutoff time (in company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - type: 'null' effective_booking_cutoff: additionalProperties: false properties: cutoff: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/cutoff_time' required: - cutoff type: object effective_cancellation_policy: additionalProperties: false properties: cutoff: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/cutoff_time' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object extended_option: additionalProperties: false properties: description: description: The extended option's description. example: Need a helmet? format: markdown type: string description_safe_html: description: The extended option's description. example:

Need a helmet?

format: markdown type: string is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The extended option's name. example: Helmet type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The extended option's unique ID. example: 105 format: int32 type: number total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number required: - pk - name - description - description_safe_html - modifier_kind - modifier_type - offset - percentage - is_always_per_customer - is_taxable - total - total_including_tax type: object item: additionalProperties: false properties: headline: description: The item's headline. example: Epic Jet Ski Tour type: string name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' required: - pk - name - headline - primary_location type: object primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object tag: additionalProperties: false properties: name: description: The tag's display name. example: Outdoor adventure type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: outdoor type: string required: - name type: object user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object properties: availability: $ref: '#/components/schemas/AVAILABILITY_RESPONSE_JSON_SCHEMA/definitions/availability' required: - availability type: object BOOKING_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object affiliate_company: oneOf: - additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The affiliate companies name. example: Affiliate Company type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: affiliate_company type: string required: - shortname - name - currency type: object - description: '' type: 'null' affiliate_metadata: description: Metadata from affiliate sources. properties: airbnb: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/airbnb_metadata' type: object affiliation: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' required: - affiliate_company type: object agent: oneOf: - additionalProperties: false properties: name: description: The agent's name. example: Eddie type: string pk: description: The agent's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' airbnb_guest_profile: description: An Airbnb guest profile. properties: direct_thread_id: description: The direct thread ID for the guest. example: '2164961599' type: - string - 'null' user_id: description: The Airbnb user ID. example: '17780410' type: - string - 'null' type: object airbnb_metadata: description: Metadata from Airbnb bookings. properties: activity_id: description: The Airbnb activity ID. example: '6137649' type: - string - 'null' channel_thread_id: description: The Airbnb channel thread ID. example: '2199079188' type: - string - 'null' guest_id: description: The Airbnb guest ID. example: '17780410' type: - string - 'null' guest_profiles: description: List of Airbnb guest profiles. items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/airbnb_guest_profile' type: - array - 'null' host_id: description: The Airbnb host ID. example: '1234' type: - string - 'null' offering_id: description: The Airbnb offering ID. example: '5495433' type: - string - 'null' type: object arrival: oneOf: - additionalProperties: false properties: display_text: description: A formatted string that can be shown to customers. example: Please arrive by 12:15 pm type: string notes: description: Notes from the activity company regarding arrival (e.g. check-in location details, driving directions); may not be provided. example: 'Check-in Time is at 12:15 for your 12:45 Zipline adventure time. Our check-in locations is at our KapohoKine Adventures Store: 224 Kamehameha Ave Suite 106 Hilo, HI 96720' format: markdown type: string notes_safe_html: example: 'Check-in Time is at 12:15 for your 12:45 Zipline adventure time. Our check-in locations is at our KapohoKine Adventures Store: 224 Kamehameha Ave Suite 106 Hilo, HI 96720' format: markdown type: string time: description: The arrival time (set in the company's local time); the customer must provide their own transporation and arrive at the activity location by this time. example: 2024-04-11T13:15:00-1000 format: datetime type: string required: - time - notes - notes_safe_html - display_text type: object - description: '' type: 'null' availability: additionalProperties: false properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_type_rates: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's headline. example: Epic Jet Ski Tour type: string item: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/item' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - headline - item - customer_type_rates - custom_field_instances type: object booking: additionalProperties: false properties: affiliate_company: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/affiliate_company' affiliate_metadata: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/affiliate_metadata' agent: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/agent' amount_paid: oneOf: - type: number - type: 'null' amount_paid_display: oneOf: - example: '0.0' type: string - type: 'null' arrival: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/arrival' availability: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/availability' description: The availability to which this booking corresponds. booked_by: oneOf: - type: 'null' - additionalProperties: false properties: name: type: string required: - name type: object company: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/company' confirmation_url: description: The booking's confirmation page URL. format: uri type: string contact: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/contact' description: Contact information for this booking. created_at: description: The date and time at which the booking was created (set in utc time). example: 2024-06-20T17:14:33+0000 format: datetime type: string custom_field_values: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_count: description: The number of customers on this booking. example: 1 type: number customers: description: A list of customers on this booking. items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/customer' type: array dashboard_url: description: The booking's dashboard URL. example: https://fareharbor.com/hawaiianadventures/dashboard/?overlay=/contacts/7/bookings/d75102be-9732-4523-90a8-c698eff2b983/ format: uri type: string desk: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/desk' display_id: example: '#6876876' type: string effective_cancellation_policy: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' external_id: description: An additional identifier if necessary. maxLength: 128 type: string generated_codes: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/generated_code' type: array invoice_price: oneOf: - description: The invoice price of this booking. Assuming that the user of the API is a reseller this will be the amount that the user of the API owes the vendor on this booking, if the vendor has opted to set up that information; otherwise it will be null. type: number - type: 'null' invoice_price_display: oneOf: - type: string - type: 'null' is_eligible_for_cancellation: example: true type: boolean is_follow_up_email_disabled: type: boolean is_reminder_email_disabled: type: boolean is_subscribed_for_sms_updates: description: Whether or not the contact would like the booking company to send them SMS updates about this booking. Note that the value of this field does not reflect whether or not the user has sent a STOP request to FareHarbor. If the user sends a STOP request to an External API client, that API client should respect that request. example: false type: boolean line_items: description: Line items on the booking. items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/line_item' type: array lodging: oneOf: - additionalProperties: false properties: name: description: The lodging's name. example: Eddie type: string pk: description: The lodging's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' note: example: '' format: markdown type: string note_safe_html: example: '' format: markdown type: string online_booking_references: example: '' type: string order: description: When there is no order associated with the booking, order will be null. oneOf: - properties: display_id: description: A unique identifier for the order example: ABTT type: string type: object - description: '' type: 'null' pickup: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/pickup' pk: description: The booking's unique ID. example: 6876876 format: int32 type: number rebooked_from: oneOf: - description: See [Rebooking](#tag/Rebooking) example: d75102be-9732-4523-90a8-c698eff2b983 type: string - type: 'null' rebooked_to: oneOf: - description: See [Rebooking](#tag/Rebooking) example: 10414711-3d20-4f4d-8ab3-eeaea26c2be3 type: string - type: 'null' receipt_subtotal: oneOf: - example: 36000 type: number - type: 'null' receipt_subtotal_display: oneOf: - example: '360.00' type: string - type: 'null' receipt_taxes: oneOf: - example: 2776 type: number - type: 'null' receipt_taxes_display: oneOf: - example: '27.76' type: string - type: 'null' receipt_total: oneOf: - example: 38776 type: number - type: 'null' receipt_total_display: oneOf: - example: '387.76' type: string - type: 'null' related_bookings: properties: related_order: properties: bookings: description: Booking UUIDs related to the order example: - d75102be-9732-4523-90a8-c698eff2b983 - a99e711d-2c70-48ce-87ff-0818942c3489 items: type: string type: array id: description: Order ID example: ABTT type: string type: object type: object source_type: enum: - online - direct - pos - reseller - external-api - kiosk - imported - unkown example: online type: string status: enum: - booked - cancelled - rebooked example: booked type: string uuid: description: The booking's universally unique identifier; used to access the booking via the API. example: d75102be-9732-4523-90a8-c698eff2b983 format: uuid type: string voucher_number: example: '' type: string waiver_signatures: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/waiver_signatures' required: - pk - uuid - availability - contact - company - affiliate_company - customers - invoice_price - invoice_price_display - display_id - external_id - order - status - rebooked_from - rebooked_to - confirmation_url - voucher_number - online_booking_references - receipt_subtotal - receipt_subtotal_display - receipt_taxes - receipt_taxes_display - receipt_total - receipt_total_display - amount_paid - amount_paid_display - custom_field_values - note - note_safe_html - pickup - arrival - effective_cancellation_policy - is_eligible_for_cancellation - agent - desk - dashboard_url - customer_count - is_subscribed_for_sms_updates - is_follow_up_email_disabled - is_reminder_email_disabled - created_at - source_type - booked_by - generated_codes - waiver_signatures - line_items - lodging - related_bookings type: object campaign: additionalProperties: false properties: created_at: description: The date and time the campaign was created at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string is_archived: example: false type: boolean name: example: August Discounts type: string prefix: example: FH type: string summary: type: string required: - created_at - is_archived type: object checkin_status: additionalProperties: false properties: name: description: The checkin status' name. example: checked in type: string pk: example: 10 format: int32 type: number type: type: string required: - pk - name - type type: object company: additionalProperties: false properties: currency: description: The company's currency. enum: - aed - aud - bgn - brl - cad - chf - czk - dkk - eur - gbp - hkd - huf - mxn - nok - nzd - pln - ron - sek - sgd - usd example: usd type: string name: description: The company's name. example: Hawaiian Adventures type: string shortname: description: A unique FareHarbor name assigned to each company when their Dashboard is created, used to access the company's specific information. example: hawaiianadventures type: string required: - shortname - name - currency type: object contact: additionalProperties: false properties: email: description: The contact email for the party. example: surfer@dude.com format: email type: string is_subscribed_for_email_updates: description: Whether or not the contact would like email updates. example: false type: boolean language: description: The contact language. example: en-us type: string member: oneOf: - $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/member' - type: 'null' name: description: The name of the head of the party. example: Surfer Dude type: string normalized_phone: description: The party's contact phone number. This will have a plus sign, the country code, and no extra characters such as commas or dashes. example: '+14432221100' type: string phone: description: The contact phone number for the party. example: +1-443-222-1100 type: string phone_country: oneOf: - description: The contact phone's country code. example: US type: string - type: 'null' required: - name - phone - phone_country - normalized_phone - email - is_subscribed_for_email_updates type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field: additionalProperties: false properties: booking_notes: description: General notes for booking customers. example: Weather conditions will be evaluated at the time of check-in.\n\n-If using a voucher, please bring the voucher with you. format: markdown type: string booking_notes_safe_html: description: Notes for the customer specific to the custom field. format: markdown type: string count_max: description: The maximum amount possible for a count type custom field. example: 300 type: number count_min: description: The minimum amount possible for a count type custom field. example: 0 type: number description: description: The custom field's description. example: Do you need additional safety equipment? format: markdown type: string description_safe_html: description: The custom field's description. example:

Do you need additional safety equipment?

format: markdown type: string extended_options: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/extended_option' type: array is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_required: description: Indicates whether the custom field requires a value. example: false type: boolean is_taxable: description: Whether the cost of this option should affect the taxable total of a booking. example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Safety Equipment type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number tags: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/tag' type: array title: type: string total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number type: description: The custom field's type. enum: - yes-no - short - long - extended-option - count - multi-campaign - code-generator - date example: yes-no type: string required: - pk - type - is_required - description - description_safe_html - name - booking_notes - booking_notes_safe_html - offset - total - total_including_tax type: object custom_field_instance: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field' pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object custom_field_value: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field' display_value: example: 'false' maxLength: 2048 type: string name: example: Name type: string pk: description: A valid Custom Field pk. example: 4502 format: int32 type: number total_cost: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/total_cost' value: description: A string up to 2048 characters. If the custom field is of type yes-no, 'true' or 'false' must be specified. If the custom field is of type extended-option, an extended option pk must be specified. example: 'false' maxLength: 2048 type: string required: - pk - custom_field - name - value - display_value - total_cost type: object customer: additionalProperties: false properties: checkin_status: description: The customer's checkin status. When there is no checkin status associated with the customer, checkin_status will be null. oneOf: - $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/checkin_status' - description: '' type: 'null' checkin_url: description: A short URL that can be rendered as a QR code for check-in purposes (the QR code should be 'type 4' with 'error correction H'). example: https://fhchk.co/abc format: uri type: string custom_field_values: description: A list of custom field values for the customer. items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field_value' type: array customer_type_rate: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' description: The customer type rate to which this customer corresponds. invoice_cost: description: The invoice_cost will be included only if the permission View invoice prices is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - description: '' type: 'null' pk: example: 28 format: int32 type: number seat_assigned: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/seat_assigned' total_cost: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/total_cost' required: - pk - checkin_url - customer_type_rate - custom_field_values type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - example: 64 type: number - type: 'null' minimum_age: oneOf: - example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adults type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_prototype: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - total - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype type: object desk: oneOf: - additionalProperties: false properties: name: description: The desk's name. example: Windward Side type: string pk: description: The desk's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' effective_cancellation_policy: additionalProperties: false properties: cutoff: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types (set in the company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - description: '' type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object extended_option: additionalProperties: false properties: description: description: The extended option's description. example: Need a helmet? format: markdown type: string description_safe_html: description: The extended option's description. example:

Need a helmet?

format: markdown type: string is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The extended option's name. example: Helmet type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The extended option's unique ID. example: 105 format: int32 type: number total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number required: - pk - name - description - description_safe_html - modifier_kind - modifier_type - offset - percentage - is_always_per_customer - is_taxable - total - total_including_tax type: object fh_waiver_signatures: description: A list of FareHarbor waivers signatures with details. items: properties: address_line: example: 7824 15th Ave type: - string - 'null' city: example: Brooklyn type: - string - 'null' country: example: US type: - string - 'null' dob: example: '1991-01-05' type: - string - 'null' email: example: johnsmith@example.com format: email type: string first_name: example: John type: string is_customer_parent: description: Indicating if the signature has any related minor records. example: false type: boolean is_marketing_allowed: description: Whether the person signing the waiver has opted in for marketing communications. example: true type: boolean last_name: example: Smith type: string phone_number: example: '+16468109900' type: - string - 'null' postcode: example: '11228' type: - string - 'null' state_province: example: NY type: - string - 'null' required: - email - first_name - last_name - is_marketing_allowed - is_customer_parent - dob - phone_number - address_line - city - state_province - postcode - country type: object type: array generated_code: additionalProperties: false properties: affiliation: oneOf: - $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/affiliation' - type: 'null' code: description: The generated code. type: string generating_campaign: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/generating_campaign' maximum_uses: example: 10 type: number use_count: example: 1 type: number required: - affiliation - code - generating_campaign - maximum_uses - use_count type: object generating_campaign: additionalProperties: false properties: campaign: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/campaign' custom_field: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/custom_field' instructions: type: string is_per_customer: example: false type: boolean is_use_existing_codes: example: false type: boolean maximum_uses: example: 10 type: number required: - campaign - custom_field - instructions - is_per_customer - is_use_existing_codes - maximum_uses type: object item: additionalProperties: false properties: headline: description: The item's headline. example: Epic Jet Ski Tour type: string name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' required: - pk - name - headline - primary_location type: object line_item: additionalProperties: false properties: description: description: Description of the line item. type: string discount_code: oneOf: - description: The discount code applied to the line item. type: string - type: 'null' is_private: description: Whether the line item is hidden from the customer. type: boolean is_taxable: description: Whether the line item is taxable. type: boolean offset: description: Amount in the smallest currency unit (e.g. cents). type: number pk: description: The line item unique identifier. format: int32 type: number required: - pk - description - offset - is_taxable - is_private - discount_code type: object member: additionalProperties: false properties: code: description: The member's ID. example: WV8K8CG type: string created_at: description: The date and time the member was created at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string membership_ranges: items: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/membership_range' type: array modified_at: description: The date and time the member was last modified at (set in utc time). example: 2023-08-18T00:30:00+0000 format: datetime type: string note: type: string pk: description: The members's unique ID. example: 874 format: int32 type: number required: - pk - code - created_at - modified_at - note - membership_ranges type: object membership: additionalProperties: false properties: duration: description: The duration of the membershi[p. example: 1 format: int32 type: number duration_type: enum: - days - weeks - months - years example: years type: string note: type: string pk: description: The membership's unique ID. example: 17 format: int32 type: number plural: type: string short_name: description: The membership's short name. type: string singular: type: string required: - pk - short_name - singular - plural - note - duration - duration_type type: object membership_range: additionalProperties: false properties: end_at: description: The end date of this membership range. example: '2025-08-06T00:00:00' format: datetime type: string is_cancelled: example: false type: boolean is_deferred_start: example: false type: boolean membership: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/membership' pk: description: The membership range's unique ID. example: 965 format: int32 type: number start_at: description: The start date of this membership range. example: '2024-08-06T00:00:00' format: datetime type: string utc_end_at: description: The end date of this membership range in utc. example: 2025-08-06T07:00:00+0000 format: datetime type: string utc_start_at: description: The start date of this membership range in utc. example: 2024-08-06T07:00:00+0000 format: datetime type: string required: - pk - start_at - utc_start_at - end_at - utc_end_at - is_cancelled - is_deferred_start - membership type: object pickup: description: If a lodging is specified and transportation is not available for the specified lodging (or any lodging), the pickup property will have a null value. oneOf: - additionalProperties: false properties: description: description: Pickup instructions from the activity company; may not be provided. example: Please meet us at the front entrance of your hotel and allow a 15 minute window for your driver to arrive. format: markdown type: string description_safe_html: description: Pickup instructions from the activity company; may not be provided. example: Please meet us at the front entrance of your hotel and allow a 15 minute window for your driver to arrive. format: markdown type: string display_text: description: A formatted string that can be shown to customers. example: We'll pick you up at 10:30am from Wyndham Royal Garden type: string map_url: description: A URL to a map showing the pickup location; may not be provided. example: https://goo.gl/maps/6QiYT format: uri type: string name: description: The name of the pickup location. example: Wyndham Royal Garden type: string time: description: The pickup time; the customer must arrive at the pickup location by this time. example: 2016-08-01T10:30:00-1000 format: time type: string required: - time - name - description - description_safe_html - map_url - display_text type: object - description: '' type: 'null' primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object seat_assigned: oneOf: - additionalProperties: false properties: name: example: Seat A type: string pk: description: The seat's unique ID. example: 84460 format: int32 type: number seat_group: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/seat_group' seat_map: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/seat_map' seat_zone: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/seat_zone' required: - pk - name - seat_map - seat_zone - seat_group type: object - description: '' type: 'null' seat_group: additionalProperties: false properties: name: example: Ungrouped type: string pk: description: The seat group's unique ID. example: 10096 format: int32 type: number required: - pk - name type: object seat_map: additionalProperties: false properties: name: example: Seat Map A type: string pk: description: The seat map's unique ID. example: 1577 format: int32 type: number required: - pk - name type: object seat_zone: additionalProperties: false properties: name: example: Default Zone type: string pk: description: The seat zone's unique ID. example: 5550 format: int32 type: number required: - pk - name type: object smartwaiver_signatures: description: A list of Smartwaiver signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string required: - email - name - is_age_verified - dob_at type: object type: array tag: additionalProperties: false properties: name: description: The tag's display name. example: Outdoor adventure type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: outdoor type: string required: - name type: object total_cost: description: The total_cost will be included only if the permission View amounts is enabled, otherwise it will be null. oneOf: - properties: feeable: description: The portion of the price the is subject to fees. example: 20000 type: number price: oneOf: - description: The line item price. example: 20000 type: number - type: 'null' tax: description: The tax price. type: number tax_by_type: description: A breakdown of taxes by tax type. type: object taxable: description: The portion of the price that is subject to taxes. type: number total: description: The total cost after taxes and fees. example: 20000 type: number type: object - description: '' type: 'null' user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object waiver_signatures: properties: fareharbor: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/fh_waiver_signatures' smartwaiver: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/smartwaiver_signatures' wherewolf: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/wherewolf_waiver_signatures' type: object wherewolf_waiver_signatures: description: A list of Wherewolf waivers signatures with details. items: properties: dob_at: example: '1991-07-08' type: string email: example: johnsmith@example.com format: email type: string is_age_verified: description: Whether the person's age that is signing the waiver is verified. example: true type: boolean name: example: John Smith type: string wherewolf_participant_status: oneOf: - enum: - Checked In - Active - Finalised - Deleted - Ineligible - Started - Loaded - Blank - Incomplete - No-Show example: Checked In type: string - description: '' type: 'null' required: - email - name - is_age_verified - dob_at - wherewolf_participant_status type: object type: array properties: booking: $ref: '#/components/schemas/BOOKING_RESPONSE_JSON_SCHEMA/definitions/booking' required: - booking type: object VALIDATE_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: agent: oneOf: - additionalProperties: false properties: name: description: The agent's name. example: Eddie type: string pk: description: The agent's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' desk: oneOf: - additionalProperties: false properties: name: description: The desk's name. example: Windward Side type: string pk: description: The desk's unique ID. example: 2314 format: int32 type: number required: - pk - name type: object - description: '' type: 'null' pickup: oneOf: - additionalProperties: false properties: description: type: string description_safe_html: type: string display_text: type: string map_url: format: uri type: string name: type: string time: format: datetime type: string required: - time - name - description - description_safe_html - map_url - display_text type: object - type: 'null' properties: agent: $ref: '#/components/schemas/VALIDATE_RESPONSE_JSON_SCHEMA/definitions/agent' code: example: '' type: string desk: $ref: '#/components/schemas/VALIDATE_RESPONSE_JSON_SCHEMA/definitions/desk' error: example: '' type: string invoice_price: description: The invoice price of this booking. Assuming that the user of the API is a reseller this will be the amount that the user of the API owes the vendor on this booking, if the vendor has opted to set up that information; otherwise it will be null. type: number is_bookable: example: true type: boolean pickup: $ref: '#/components/schemas/VALIDATE_RESPONSE_JSON_SCHEMA/definitions/pickup' receipt_subtotal: example: 36000 type: number receipt_taxes: example: 2776 type: number receipt_total: example: 38776 type: number required: - is_bookable type: object ITEM_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - example: 64 type: number - type: 'null' minimum_age: oneOf: - example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object faq_item: additionalProperties: false properties: answer: description: FAQ answer. example: Absolutely, the more the merrier! type: string question: description: FAQ question. example: Can I bring a friend? type: string required: - question - answer type: object guided_language: additionalProperties: false properties: language_code: description: IETF BCP 47 language tag for the guided commentary. example: en type: string type: description: The delivery format of the guided commentary. enum: - in_person - recorded_audio example: in_person type: string required: - type - language_code type: object image: additionalProperties: false properties: gallery: description: The image's gallery name. example: carousel type: string image_cdn_url: description: A URL to the item's primary image. example: https://d1a2dkr8rai8e2.cloudfront.net/api/file/rvybRyLWTgyV5w4xg42p/ format: uri type: string pk: description: The image's unique ID. example: 687 format: int32 type: number required: - pk - gallery - image_cdn_url type: object item: properties: cancellation_policy: description: The item's cancellation policy. example: A full refund will be issued if notice is given at least 24 hours before start time. format: markdown type: string cancellation_policy_safe_html: description: The item's cancellation policy. example:

A full refund will be issued if notice is given at least 24 hours before start time.

format: markdown type: string customer_prototypes: description: An array of CustomerPrototype objects associated with the item. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' type: array description: description: The item's description. example: We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel. format: markdown type: string description_bullets: description: An array containing plain-text descriptive bullet points for the item. items: example: Located just 5 minutes from Waikiki. type: string type: array description_safe_html: description: The item's description. example:

We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel.

format: markdown type: string description_text: description: The item's plain-text description. example: We are conveniently located just 5 minutes from Waikiki and will arrange for pickup/dropoff at or near your hotel. type: string effective_cancellation_policy: additionalProperties: false properties: cutoff_hours_before: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types. example: 24 type: number - type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff_hours_before type: object headline: description: The item's headline. example: Epic Jet Ski Tour type: string health_and_safety_policy: description: The item's health and safety policy. It includes details and procedures related to specific activities for the item like the precautions being taken, equipment to bring, and any additional special rules. example: Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat. format: markdown type: string health_and_safety_policy_safe_html: description: The item's health and safety policy. It includes details and procedures related to specific activities for the item like the precautions being taken, equipment to bring, and any additional special rules. example:

Every lifejacket and seat is thoroughly disinfected both before and after each tour. Hand sanitizer is available to all guests prior to boarding, during the tour, and after debarking the boat.

format: markdown type: string image_cdn_url: description: A URL to the item's primary image. example: https://d1a2dkr8rai8e2.cloudfront.net/api/file/rvybRyLWTgyV5w4xg42p/ format: uri type: string images: items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/image' type: array is_pickup_ever_available: description: Indicates whether the item is configured to provide pickups. example: true type: boolean location: type: string locations: items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/location' type: array name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' ratings: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/ratings' structured_description: oneOf: - $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/structured_description' - type: 'null' tags: items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/tag' type: array tax_percentage: type: number required: - pk - name - tax_percentage - headline - booking_notes - booking_notes_safe_html - description - description_safe_html - description_text - description_bullets - cancellation_policy - cancellation_policy_safe_html - location - locations - primary_location - image_cdn_url - images - customer_prototypes - is_pickup_ever_available - health_and_safety_policy - health_and_safety_policy_safe_html type: object location: additionalProperties: false properties: address: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: 90 type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: 0 type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object ratings: properties: google_reviews: oneOf: - properties: cached_at: format: date-time type: string rating: type: number user_ratings_total: type: integer required: - cached_at - user_ratings_total - rating type: object - type: 'null' tripadvisor: oneOf: - properties: cached_at: format: date-time type: string geo_location_name: type: string num_reviews: type: integer ranking: type: integer ranking_out_of: type: integer ranking_string: type: string rating: type: number rating_image_url: type: string required: - cached_at - num_reviews - rating - rating_image_url - ranking - ranking_out_of - ranking_string - geo_location_name type: object - type: 'null' required: - google_reviews - tripadvisor type: object structured_description: additionalProperties: false properties: accessibility: description: Accessibility options that are available. example: Stroller and wheelchair accessible. type: - string - 'null' cancellation_summary: description: Summary of the cancellation policy. example: A full refund will be issued if notice is given at least 24 hours before start time. type: - string - 'null' check_in_details: description: Where and how to check-in. example: Check in at the desk and scan QR code format: markdown type: - string - 'null' description: description: Description of the item and what customers can expect. example: White water rafting followed by a picnic with included food and drinks. format: markdown type: string disclaimers: description: Limitations or potential events in which the operator is not responsible. example: We cannot be held responsible if you get attacked by a bear. format: markdown type: - string - 'null' duration: description: Freeform text describing the duration. example: 2 hours type: - string - 'null' extras: description: Any equipment, add-ons or services that can be purchased. example: '

The following can be purchased:

  • Hats
  • Wetsuit rentals
' format: markdown type: - string - 'null' faq_items: description: Answers to customers frequently asked questions. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/faq_item' type: array faqs: description: Answers to customers frequently asked questions. example: 'Q: Can I bring a friend? A: Absolutely, the more the merrier!' format: markdown type: - string - 'null' group_size: description: Freeform text describing group size constraints. example: Maximum 20 adults type: - string - 'null' guided_languages: description: A list of guided language options available for the activity. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/guided_language' type: array highlights: description: What makes this activitiy special. example: Nature hike includes five different lookout spots with panoramoic views that are perfect for capturing memories with a photo. format: markdown type: - string - 'null' itinerary: description: Detailed agenda of what the customer can expect. example: '
  1. Safety lesson
  2. White water rafting
  3. Lunch break
  4. Nature hike
' format: markdown type: - string - 'null' max_age: description: Maximum age restriction. example: 65 type: - number - 'null' meeting_point: description: Freeform text describing address, city or landkmark of where to meet. example: 123 Fake Street, Fakertown CA in front of the statue. type: - string - 'null' min_age: description: Minimum age restriction. example: 5 type: - number - 'null' pricing: description: Overview of prices and options offered. example: '

Adult $20
Child $10
Children under 5 Free

' format: markdown type: - string - 'null' restrictions: description: Any restrictions that cannot be accommodated. example: Must be at least 48in tall. format: markdown type: - string - 'null' short_description: description: A concise summary describing the activity. example: White water rafting. type: - string - 'null' special_requirements: description: Any requirements that should be known before booking. example: Children under the age of 16 must be accompanied by an adult. format: markdown type: - string - 'null' what_is_included: description: What is included in the price of the activity. example: '
  • Water
  • Snacks
' format: markdown type: - string - 'null' what_is_included_items: description: List of items that are included in the price of the activity. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/what_is_included_item' type: array what_is_not_included: description: What is not included in the price of the activity. example: '
  • Towels
  • Wetsuit rentals
' format: markdown type: - string - 'null' what_is_not_included_items: description: List of items that are not included in the price of the activity. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/what_is_not_included_item' type: array what_to_bring: description: Any items the customer should bring. example: '
  • Swimsuit
  • Towel
' format: markdown type: - string - 'null' what_to_bring_items: description: List of items that the customer should bring. items: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/what_to_bring_item' type: array type: object tag: additionalProperties: false properties: name: description: The tag's display name. example: Jet ski Tour type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: jet-ski-tour type: string required: - name type: object what_is_included_item: additionalProperties: false properties: value: description: Included item text. example: Water type: string required: - value type: object what_is_not_included_item: additionalProperties: false properties: value: description: Not included item text. example: Towels type: string required: - value type: object what_to_bring_item: additionalProperties: false properties: value: description: What to bring item text. example: Swimsuit type: string required: - value type: object properties: item: $ref: '#/components/schemas/ITEM_RESPONSE_JSON_SCHEMA/definitions/item' required: - item type: object LINE_ITEM_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: line_item: additionalProperties: false properties: description: description: Description of the line item. type: string discount_code: oneOf: - description: The discount code applied to the line item. type: string - type: 'null' is_private: description: Whether the line item is hidden from the customer. type: boolean is_taxable: description: Whether the line item is taxable. type: boolean offset: description: Amount in the smallest currency unit (e.g. cents). type: number pk: description: The line item unique identifier. format: int32 type: number required: - pk - description - offset - is_taxable - is_private - discount_code type: object description: Response containing the created line item (pk, description, amount, is_taxable, is_private, discount_code). properties: line_item: $ref: '#/components/schemas/LINE_ITEM_RESPONSE_JSON_SCHEMA/definitions/line_item' description: The created line item. required: - line_item title: Line Item Response type: object AVAILABILITIES_RESPONSE_JSON_SCHEMA: $schema: http://json-schema.org/draft-04/schema# additionalProperties: false definitions: address: additionalProperties: false properties: city: example: Honolulu type: string country: example: US type: string postal_code: example: '96821' type: string province: example: HI type: string street: example: 123 Wailupe Cir type: string required: - city - country - postal_code - province - street type: object availability: properties: capacity: description: The overall maximum number of customers that can currently book this availability; this number will change over time as other customers book. example: 3 type: number crew_members: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/crew_member' type: array custom_field_instances: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_type_rates: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_type_rate' type: array effective_cancellation_policy: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/effective_cancellation_policy' end_at: description: The availability's end time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T03:30:00-0600 format: datetime type: string headline: description: The availability's headline. example: Epic Jet Ski Tour type: string item: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/item' maximum_party_size: oneOf: - example: 1 type: number - type: 'null' minimum_party_size: oneOf: - example: 1 type: number - type: 'null' online_booking_status: description: The availability's status. enum: - auto - open - call - closed - cancelled example: auto type: string pk: description: The availabilities's unique ID. example: 50291151 format: int32 type: number start_at: description: The availability's start time (set in the company's local time); note that this time can be arbitrarily long or short, and that start_at can equal end_at for 'point' availabilities. example: 2023-08-18T00:30:00-0600 format: datetime type: string required: - pk - start_at - end_at - capacity - minimum_party_size - maximum_party_size - online_booking_status - headline - item - customer_type_rates - custom_field_instances type: object crew_member: additionalProperties: false properties: note: description: A note on the crew member. type: string pk: description: The crew member's unique ID. format: int32 type: number role: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/role' description: The role of the crew member. user: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/user' description: The crew member user. required: - pk - note - user type: object custom_field: additionalProperties: false properties: booking_notes: description: Notes for the customer specific to the custom field. example: '' format: markdown type: string booking_notes_safe_html: description: Notes for the customer specific to the custom field. format: markdown type: string count_max: description: The maximum amount possible for a count type custom field. example: 300 type: number count_min: description: The minimum amount possible for a count type custom field. example: 0 type: number description: description: The custom field's description. example: Do you need additional safety equipment? format: markdown type: string description_safe_html: description: The custom field's description. example:

Do you need additional safety equipment?

format: markdown type: string extended_options: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/extended_option' type: array is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_required: description: Indicates whether the custom field requires a value. example: false type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The name of the custom field. example: Safety Equipment type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The custom field's unique ID. example: 4502 format: int32 type: number tags: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/tag' type: array title: type: string total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number type: description: The custom field's type. enum: - yes-no - short - long - extended-option - count example: extended-option type: string required: - pk - type - is_required - description - description_safe_html - name - booking_notes - booking_notes_safe_html - offset - total - total_including_tax type: object custom_field_instance: additionalProperties: false properties: custom_field: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field' description: The custom field associated with the custom field instance. pk: description: The custom field instance's unique ID. example: 2681 format: int32 type: number required: - pk - custom_field type: object customer_prototype: additionalProperties: false properties: display_name: description: The customer prototype's display name. example: Adult type: string maximum_age: oneOf: - description: The maximum age for this customer type (inclusive). example: 64 type: number - type: 'null' minimum_age: oneOf: - description: The minimum age for this customer type (inclusive). example: 18 type: number - type: 'null' note: type: string pk: description: The customer prototype's unique ID. example: 2522 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - display_name - note - minimum_age - maximum_age - total type: object customer_type: additionalProperties: false properties: note: description: A brief note about this customer type that can be displayed to end users. example: At least 18 years old. type: string pk: description: The customer type's unique ID. example: 589 format: int32 type: number plural: description: The plural form of the name of this customer type. example: Adult type: string singular: description: The singular form of the name of this customer type. example: Adult type: string required: - pk - singular - plural - note type: object customer_type_rate: additionalProperties: false properties: capacity: oneOf: - description: The maximum number of customers of this type that can currently book this availability; this number will change over time as other customers book. example: 10 type: number - type: 'null' custom_field_instances: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/custom_field_instance' type: array customer_prototype: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_prototype' customer_type: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/customer_type' maximum_party_size: oneOf: - type: number - type: 'null' minimum_party_size: oneOf: - type: number - type: 'null' pk: description: The customer type rate's unique ID. example: 978 format: int32 type: number total: description: The price of a single customer of this type. example: 20000 type: number total_including_tax: description: The price of a single customer of this type plus applicable taxes. example: 21550 type: number required: - pk - total - capacity - minimum_party_size - maximum_party_size - customer_type - customer_prototype - custom_field_instances type: object effective_cancellation_policy: additionalProperties: false properties: cutoff: oneOf: - description: The number of hours for the hours-before-start and hours-before-midnight types (set in the company's local time). example: 2024-04-16T00:00:00-1000 format: datetime type: string - type: 'null' type: description: The cancellation policy's type enum: - hours-before-start - hours-before-midnight - always - never example: hours-before-start type: string required: - type - cutoff type: object extended_option: additionalProperties: false properties: description: description: The extended option's description. example: Need a helmet? format: markdown type: string description_safe_html: description: The extended option's description. example:

Need a helmet?

format: markdown type: string is_always_per_customer: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean is_taxable: description: Whether pricing should be applied to each customer (when the customer field is at the booking level). example: true type: boolean modifier_kind: description: Determines whether an offset or percentage is used when the total is adjusted or set. enum: - percentage - offset example: percentage type: string modifier_type: description: Determines whether the total is adjusted or set. enum: - adjust - set - none example: adjust type: string name: description: The extended option's name. example: Helmet type: string offset: description: 'When modifier_type is adjust: a positive or negative amount value. When modifier_type is set: a positive amount value. Only applicable when modifier_kind is offset.' type: number percentage: description: 'When modifier_type is adjust: a number between -100 and 100 inclusive. When modifier_type is set: a number between 0 and 100 inclusive. Only applicable when modifier_kind is percentage.' example: 35 type: number pk: description: The extended option's unique ID. example: 105 format: int32 type: number total: description: The price of a single custom field of this type. example: 20000 type: number total_including_tax: description: The price of a single custom field of this type plus applicable taxes. example: 21550 type: number required: - pk - name - description - description_safe_html - modifier_kind - modifier_type - offset - percentage - is_always_per_customer - is_taxable - total - total_including_tax type: object item: additionalProperties: false properties: headline: description: The item's headline. example: Epic Jet Ski Tour type: string name: description: The item's name. example: Jet Ski Tour type: string pk: description: The items's unique ID. example: 1867 format: int32 type: number primary_location: oneOf: - $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/primary_location' - type: 'null' required: - pk - name - headline - primary_location type: object primary_location: additionalProperties: false properties: address: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/address' description: The location's physical address. google_place_id: description: The location's Google Place ID. example: ChIJYZ4srGUSAHwRT1Da4amp3x format: uuid type: string latitude: description: The location's latitude. oneOf: - example: '-157.85' type: number - type: 'null' longitude: description: The location's longitude. oneOf: - example: '21.30' type: number - type: 'null' note: description: A brief note about this location that can be displayed to end users. example: Next to the blue fence. format: markdown type: string note_safe_html: description: A brief note about this location that can be displayed to end users. example:

Next to the blue fence.

format: markdown type: string pk: description: The location's unique ID. example: 234234 format: int32 type: number tripadvisor_url: description: The location's TripAdvisor URL. example: https://www.tripadvisor.com/Attraction_Review-g60982-d184886-Reviews-Epic_Jet_Ski_Tour-Honolulu_Oahu_Hawaii.html format: uri type: string type: description: The location's type. example: primary type: string required: - pk - type - note - note_safe_html - address - longitude - latitude - google_place_id - tripadvisor_url type: object role: additionalProperties: false properties: pk: description: The role's unique ID. format: int32 type: number short_name: description: The roles's short name. type: string required: - pk - short_name type: object tag: additionalProperties: false properties: name: description: The tag's display name. example: Outdoor adventure type: string shortname: description: The tag's short name. The short name is unique per company and is limited to lowercase letters (a-z), digits (0-9), and the dash character. example: outdoor type: string required: - name type: object user: additionalProperties: false properties: name: description: The name of the user. type: string username: description: The username of the user. type: string required: - name - username type: object properties: availabilities: items: $ref: '#/components/schemas/AVAILABILITIES_RESPONSE_JSON_SCHEMA/definitions/availability' type: array required: - availabilities type: object # Schema for error response body Error: type: object properties: code: type: string message: type: string required: - code - message Error400: allOf: - $ref: "#/components/schemas/Error" - type: object properties: code: $ref: "#/components/schemas/Codes400" Error403: allOf: - $ref: "#/components/schemas/Error" - type: object properties: code: $ref: "#/components/schemas/Codes403" Error404: allOf: - $ref: "#/components/schemas/Error" - type: object properties: code: $ref: "#/components/schemas/Codes404" Codes400: type: string enum: [availability-date-range-invalid, book-data-parse-error, book-data-validation-error, bookability-error, booking-cancellation-error, booking-creation-error, booking-custom-field-value-creation-error, booking-custom-field-values-invalid, booking-note-error, contact-error, content-type-invalid-error, customer-custom-field-value-creation-error, customer-custom-field-value-update-error, customer-custom-field-values-invalid, customer-type-rates-invalid, invalid-checkin-already-checked-in, invalid-checkin-customer, invalid-checkin-status-error, invalid-qr-code-error, key-missing, lodging-pk-invalid, no-default-checkin-status-error, orderize-booking-uuid-invalid-error, payment-error, rebooking-uuid-invalid-error, resource-bookability-error, voucher-number-invalid, voucher-number-not-specified] Codes403: type: string enum: [app-invalid, app-key-invalid, invalid-checkin-permissions-error, orderize-booking-uuid-invalid-error, user-key-invalid] Codes404: type: string enum: [availability-pk-invalid, booking-uuid-invalid, company-shortname-invald, customer-custom-field-value-pk-invalid, item-pk-invalid]