Bridgify Merchant API – reference

Bridgify - Go to main page

Bridgify Attraction API — Merchant User’s Guide (Attraction Booking)

Version: V1.13
Confidential: This document contains confidential information. Do not distribute.

Overview

This document describes the overall flow when integrating with Bridgify using the Bridgify Attraction API to book attractions.

The Bridgify Attraction API provides features for:

  1. Searching for attractions
  2. Retrieving attraction information (including availability)
  3. Booking attractions

The booking flow implements purchases for one attraction at a time, where a single attraction is placed in a shopping cart and then purchased.

Attraction API

  • Authentication & Search docs: Attraction API (including authentication)
  • API Type: REST style HTTP API

Base URLs

  • Production: https://api.bridgify.io
  • Development: https://api.dev.bridgify.io

Examples in this document use production URLs. If you are using the dev environment, adjust the base URL accordingly.

API Modes

  • Merchant mode – Payment processing is done by the client (money goes to the client). The client is responsible for cancellations, refunds, and support.

Authentication

  • OAuth 2.0 (see the Attraction API documentation for details)

Rate Limits

  • Bridgify API has rate limits in place to prevent overuse.

Booking Overview — Using the Booking API

This section explains how to use the Booking API directly to purchase attractions. The booking flow can vary based on the data provider and attraction type. Examples of variations:

  1. Some attractions require selecting a pickup point before selecting a date.
  2. Some attractions have open tickets (no date selection required).
  3. Some attractions require a date but not a time.
  4. Some may require additional traveler information (passport, phone, email, etc.).
  5. Some may require seat selection.
  6. Each attraction has its own list of ticket types and constraints (e.g., adult required for child tickets).

To handle these variations, call required-fields for the cart item and follow the returned sequence.

High-level Flow

  1. create-cart
  2. add-item-to-cart
  3. required-fields
  4. Iterate through the listed endpoints in the returned order:
    • pickups
    • seats-map
    • shipment-method
    • options
    • languages
    • dates
    • timeslots
    • tickets
    • optional-extras
    • customer-info
  5. save-in-the-cart (and coupon if applicable)
  6. create-order
  7. get-orders to retrieve vouchers
  8. get-orders .../cancellation to check or perform cancellations

Order matters: If you call an earlier required field again, it resets data for all subsequent steps.

Step-by-Step

1) Create a Cart

A cart manages the booking process. All booking operations require a cart_uuid.

Request

POST https://api.bridgify.io/attractions/booking/cart/

Response

{
  "cart_uuid": "f3e8b0fc-c351-468e-a85c-837b457d2cf9",
  "short_uuid": "22024070314493931212"
}
  • cart_uuid — Pass to subsequent endpoints.
  • short_uuid — Will be the order_uuid returned to the customer.

2) Add an Item to the Cart

Adds an attraction to the cart and returns a cart_item_uuid.

Note: Currently cart functionality is not fully implemented. To finalize an order properly only one cart_item should be added. In the future, multiple items will be supported.

Request

POST https://api.bridgify.io/attractions/booking/cart/items/

Body

{
  "cart_uuid": "f3e8b0fc-c351-468e-a85c-837b457d2cf9",
  "attraction_uuid": "f80f3ab9-8d1f-45a0-a3a2-f8503591dd87"
}

Response

{ "cart_item_uuid": "911d1684-a61d-470c-985c-3b652f7ddadf" }

3) Update a Cart Item

Replace the current attraction in a cart item.

Request

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}

Body

{ "attraction_uuid": "f80f3ab9-8d1f-45a0-a3a2-f8503591dd87" }

4) Delete a Cart Item

Remove a cart item from the cart.

Request

DELETE https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}

5) Required Fields

Returns the list of endpoints (and order) required to complete the booking for the current cart item.

Important: Calling an earlier field again resets the data for all following endpoints.

Request

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/required-fields/

Response

{
  "required_booking_fields": ["dates", "timeslots", "tickets", "customer-info"]
}

6) Iterate Through the Required Endpoints

6.1) Pickups

A pickup point is a meeting place where a traveler can be picked up. The response can be:

  • A list of pickup points (+ optional pickup times), or
  • A list of pickup options (e.g., Meet at departure point, Hotel, Airport, Contact supplier later) that influences the subsequent customer-info.

Get Available Pickups

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/pickups/

Response (example: list of points)

{
  "available_pickups": [
    {
      "uuid": "60379a3e-3305-4a32-bbb4-c7f90b70a4db",
      "type": "PICKUP",
      "name": "Break Sokos Hotel Levi",
      "latitude": 67.805595,
      "longitude": 24.807596
    }
  ]
}

Response (example: points with times)

{
  "available_pickups": [
    {
      "pickup_point_id": "15500669235",
      "pickup_point_description": "Meet at the Wyndham Apollo hotel.",
      "pickup_point_location": "LOCATION_ID_123",
      "pickup_point_times": ["10:00", "09:30"]
    }
  ]
}

Response (example: options)

{
  "available_pickups": [
    { "uuid": "MEET_AT_DEPARTURE_POINT", "name": "I will meet at the departure point" },
    { "uuid": "HOTEL", "name": "Hotel" },
    { "uuid": "CONTACT_SUPPLIER_LATER", "name": "I will contact the supplier later" },
    { "uuid": "AIRPORT", "name": "Airport" }
  ]
}

Select a Pickup

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/pickups/

Bodies (examples)

{ "pickup": "60379a3e-3305-4a32-bbb4-c7f90b70a4db" }

{ "pickup": { "pickup_point_id": "15500669235", "pickup_point_times": ["09:30"] } }

{ "pickup": "CONTACT_SUPPLIER_LATER" }

6.2) Seats Map

Returns a URL to a JPG image of the seating map (for theater/sports).

Request

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/seats-map/

6.3) Shipment Method

Returns methods used to ship tickets (for scenarios without e-tickets or where shipment incurs a fee).

Get Methods

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/shipment-method/

Example

{
  "available_shipment_methods": [
    { "shipment_id": "1006", "area_id": "1006", "shipment_name": "E-Ticket", "merchant_price": 0.0 }
  ]
}

Select Method

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/shipment-method/

Body

{ "shipment-method": "1006" }

6.4) Options

Returns available options for the event. If required, this typically appears early because options affect subsequent fields.

  • Prices here are informational and returned in USD (e.g., “price_from”).
  • Final price is determined at the tickets step.
  • Some suppliers have flexible pricing depending on the ticket quantities ("flexible_price": true → show disclaimer).

Get Options

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/options/

Example (truncated)

{
  "options": [
    {
      "option_id": "TG1",
      "title": "Car+Guide",
      "description": "Tour Includes: AC car and Tour Guide. Entrance fee and meal not included.",
      "currency": "USD",
      "merchant_price": 6.2,
      "retail_price": 10.23,
      "supplier_discount": 0.0,
      "flexible_price": true
    }
  ]
}

Select Option

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/options/

Body

{ "option_id": "TG1" }

6.5) Languages

Returns available languages (codes or full names with service type).

Time slots can depend on the selected language.

Get Languages

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/languages/

Examples

{ "available_languages": ["es", "en"] }

{ "available_languages": ["Spanish - Guide", "English - Guide"] }

Select Language

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/languages/

Bodies

{ "language": "es" }

{ "language": "English - Guide" }

6.6) Dates

Returns a list of available dates (typically within the next 6 months).

These dates come from real-time availability checks and are more authoritative than the generic availability endpoints.

Get Dates

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/dates/

Example

{ "available_dates": ["2024-01-23", "2024-01-24", "2024-01-25", "2024-01-26", "2024-01-27"] }

Select Date

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/dates/

Body

{ "date": "2024-01-27" }

6.7) Timeslots

Returns a list of available timeslots (or time intervals) for the selected date and other parameters.

Get Timeslots

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/timeslots/

Examples

{ "available_timeslots": ["08:30", "10:30", "12:30"] }

{ "available_timeslots": ["08:30 - 10:30", "12:30 – 14:30"] }

Select Timeslot

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/timeslots/

Bodies

{ "timeslot": "10:30" }

{ "timeslot": "08:30 - 10:30" }

6.8) Tickets

Returns available ticket types for the selected parameters and purchase restrictions. The response includes:

  • restriction — Constraints such as:

    1. max_ticket_types — Max distinct ticket types in one order
    2. adult_required — Adult ticket required to purchase child ticket
    3. overall_max_tickets — Max total tickets in one order
    4. {product_id}_minimum_required — Minimum tickets for a specific type
    5. {product_id}_max_tickets — Max per specific ticket type
    6. flexible_price — Price depends on quantities → show disclaimer

  • ticket_types — Ticket type details. Depending on supplier:

    • Price may be returned on GET or only after PATCH.
    • Per ticket type fields may include: merchant_price, retail_price, supplier_discount, currency, available_selling_quantities, type.

Get Ticket Types

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/tickets/

Example (with prices)

{
  "restriction": { "overall_max_tickets": 5, "adult_required": true },
  "ticket_types": [
    {
      "product_id": "155041",
      "name": "Adult",
      "holder_type": "ADULT",
      "merchant_price": 51.23,
      "retail_price": 55.0,
      "supplier_discount": 0.0,
      "currency": "USD",
      "available_selling_quantities": [1,2,3,4,5],
      "type": "musement-realtime"
    }
  ]
}

Example (prices after PATCH)

{
  "restriction": { "overall_max_tickets": 5, "adult_required": true, "ADULT_minimum_required": 1 },
  "ticket_types": [
    {
      "product_id": "ADULT",
      "name": "ADULT (age 11 - 99)",
      "holder_type": "MOBILE_ONLY",
      "currency": "USD",
      "available_selling_quantities": [1,2,3,4,5],
      "type": "PER_PERSON"
    }
  ]
}

Select Tickets

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/tickets/

Bodies

{ "tickets": [ { "product_id": "155041", "quantity": 2 }, { "product_id": "155042", "quantity": 2 } ] }

{ "tickets": [ { "product_id": "ADULT", "quantity": 1 } ] }

Price Response (example)

{
  "ticket_prices": [
    { "product_id": "ADULT", "quantity": 1, "merchant_price": 102, "retail_price": 120.41, "supplier_discount": 0, "currency": "USD" },
    { "product_id": "TOTAL", "merchant_price": 102, "retail_price": 120.41, "supplier_discount": 0, "currency": "USD" }
  ]
}

6.9) Optional Extras

Returns a list of extra services (e.g., food, drinks, booklets).

Get Extras

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/optional-extras/

Example

{
  "restriction": { "overall_max_tickets": 5 },
  "optional_extras": [
    {
      "id": "448",
      "title": "food",
      "option_values": [
        { "value_id": "448_meat", "value_name": "meat", "value_price": "2.00" },
        { "value_id": "448_fish", "value_name": "fish", "value_price": "3.00" }
      ]
    }
  ]
}

Select Extras

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/optional-extras/

Body

{
  "optional_extras": [
    {
      "id": "448",
      "option_values": [{ "value_id": "448_meat", "value_count": 1 }]
    }
  ]
}

6.10) Customer Info

Returns a JSON Schema describing additional fields required to finalize the order. These can include per-traveler and per-booking questions and always contain a required_customer_contact_info or required_info_for_payment object.

Get Customer Info Schema

GET https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/customer-info/

General Schema

{
  "title": "required_customer_info",
  "type": "object",
  "properties": {},
  "required": []
}

Examples (truncated)

  • Language+Hotel:
{
  "title": "required_customer_info",
  "type": "object",
  "properties": {
    "language": {
      "type": "object",
      "properties": { "language_live": { "type": "string", "enum": ["en"] } },
      "oneOf": [{"required": ["language_live"]}]
    },
    "hotel": { "type": "string", "title": "Hotel" }
  },
  "required": ["hotel", "language"]
}
  • Traveler + Contact:
{
  "title": "required_customer_info",
  "type": "object",
  "properties": {
    "id_adult_number_1": {
      "type": "object",
      "properties": {
        "date_of_birth": { "type": "string" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "passport_number": { "type": "string" }
      }
    },
    "required_customer_contact_info": {
      "type": "object",
      "properties": {
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "phone": { "type": "string" },
        "email": { "type": "string" },
        "address": { "type": "string" },
        "city": { "type": "string" },
        "zip_code": { "type": "string" }
      },
      "required": ["first_name", "last_name", "phone", "email", "address", "city", "zip_code"]
    }
  },
  "required": ["language", "id_adult_number_1", "required_customer_contact_info"]
}

Set Customer Info

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/customer-info/

Bodies (examples; truncated)

{
  "language": { "language_live": "en" },
  "hotel": "The Hotel"
}

{
  "id_adult_number_1": {
    "date_of_birth": "1900-01-01",
    "first_name": "John",
    "last_name": "Doe",
    "passport_number": "1234567"
  },
  "language": { "language_live": "en" },
  "required_customer_contact_info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "test@test.test",
    "phone": "+12345678",
    "address": "Test Test",
    "city": "Test",
    "zip_code": "1234567"
  }
}

7) Additional Endpoints

7.1) Save in the Cart

Call before payment/order creation to store only relevant information.

  • transaction_amount — total merchant price for the order
  • transaction_currency — e.g., USD

Request

POST https://api.bridgify.io/attractions/booking/save-in-cart/

Body

{
  "cart_uuid": "903cb3b9-558a-40ac-9479-46597ff86d55",
  "transaction_amount": 3,
  "transaction_currency": "USD"
}

Response

{ "Saved.": "" }

7.2) Coupons

Apply client-provided coupons before customer-info.

  • Include clearance_price (amount before coupon)
  • If applicable, response returns discounted_price to use going forward (payment and save-in-the-cart)

Request

PATCH https://api.bridgify.io/attractions/booking/cart/items/{cart_item_uuid}/coupon/

Body

{
  "clearance_price": 100,
  "property": "Isracard",
  "coupon_code": "123456",
  "currency": "USD"
}

Response

{ "discounted_price": 90, "discount_amount": 10 }

8) Create an Order

Create/finalize the order after completing the required endpoints.

Merchant mode liability: Once this is called, you are liable for the merchant price (+ rev-share/processing fees) of the purchased tickets.

Request (Merchant Mode)

POST https://api.bridgify.io/attractions/booking/orders

Body

{ "cart_short_uuid": "2024070716031846777", "currency_paid": "USD" }

Response

{ "order_uuid": "2024070716031846777" }

9) Get an Order

After the order is confirmed, retrieve voucher URLs (PDFs) for the e-tickets.

Some suppliers send vouchers directly to users; we may not have links (especially sports events). Confirmation can be instant or take hours/days depending on supplier.

Request

GET https://api.bridgify.io/attractions/booking/orders/{order_uuid}

Example (truncated)

{
  "The booking order: ": [
    {
      "uuid": "f18c7df8-e63f-403e-8882-5ad0876828e2",
      "status": "OK",
      "vouchers": [
        { "url": "https://api.musement.com/voucher/view/..." }
      ]
    }
  ]
}

10) Get All Orders

Gets order information (including vouchers) for all orders or a date range.

Query Params

  1. date_from — Returns attractions with availability after the date (YYYY-MM-DD). Defaults to today.
    If date_to is specified then date_from must be specified.
  2. date_to — Returns attractions with availability before the date (YYYY-MM-DD).
    If not specified, current date is used.

Request (example)

GET https://api.bridgify.io/attractions/booking/orders?date_from=2024-04-04&date_to=2024-05-05

Canceling Orders

Each attraction has its own cancellation policy:

  1. Not all attractions can be canceled.
  2. Some provide only partial refunds.
  3. Some offer full refunds with advance notice (e.g., ≥ 24–48 hours).

Use the cancellation endpoint to check policy, allowed status, and the merchant_total_price refund amount.

Check Cancellation

GET https://api.bridgify.io/attractions/booking/orders/{short_uuid}/cancellation

Example (truncated)

{
  "cancellation-info": {
    "3be16340-59a9-4744-bae2-70d707b3077b": {
      "policy": "For a full refund, cancel at least 24 hours before the scheduled departure time.",
      "merchant_total_price": 302.25,
      "currency": "USD",
      "type": "PERCENTAGE",
      "travel_date": "2024-08-14",
      "percentage": 100.0,
      "cancellation_allowed": true,
      "paxes": { "ADULT": 2 },
      "title": "Cave Tubing and Zipline Adventure from Belize City"
    }
  }
}

Cancel an Order

DELETE https://api.bridgify.io/attractions/booking/orders/{short_uuid}/{order_item_uuid}/cancellation

Response

{ "message": "Order has been canceled" }

Attraction & Availability Endpoints

The API supports searching for attractions, retrieving specific attraction details, and availability.
Refer to the Attraction API (including authentication) documentation for details.

Search Suggestions (Autocomplete)

Powers the search-bar autocomplete. Given a partial query, it returns categorised suggestions (cities, countries, artists, sports teams, attraction places, gift-card vouchers, regions, sub-regions) so the caller can render a live "as you type" dropdown.

Suggestions are served from a pre-built, in-memory (Redis) prefix index rather than a live database query, so the endpoint is optimised for very low latency. Each requested category is resolved in parallel and returned under its own key.

Request

GET https://api.bridgify.io/attractions/search-suggestion/?text_search=lon&search_base=city,country,artist&lang=en

Query Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | search_base | Yes | Comma-separated list of suggestion categories to return. Supported values: artist, team, city, country, place, region, subregion, voucher. Only the requested categories appear in the response. | | text_search | No | The partial text the user has typed. The query is lower-cased, trimmed and normalised (accents/punctuation removed) before matching, and matches are done by prefix. Alias: q. | | q | No | Alias for text_search. | | lang | No | Language for the returned localized names. Defaults to en. Supported: en, he, it, pt. | | city_id | No | Scopes suggestions to a specific city (used on a city page). When set, only place results are returned. | | country_id | No | Scopes suggestions to a specific country (used on a country page). When set, only region, subregion and place results are returned. | | region_id | No | Scopes suggestions to a specific region (used on a region page). When set, only subregion and place results are returned. |

Geo-scoping: city_id, country_id and region_id are optional filters passed from location pages. When one is supplied, categories that are not valid for that scope return an empty list. Without any of them, matching is global (across the first-letter index).

Behaviour Notes

  • Limit: at most 7 suggestions are returned per category.
  • Ranking: results are sorted by popularity (number of active attractions for the current marketplace mode) before the limit is applied, so the most relevant items surface first.
  • Marketplace mode: merchant vs. affiliate popularity counts are selected automatically based on the caller's marketplace mode.
  • Localization: name is the localized name for the requested lang; name_en is always the English name. slug mirrors the English name.

Response

The response is an object keyed by the requested categories. Each value is a list of suggestion objects. The object shape differs slightly per category:

{
  "city": [
    {
      "id": 1234,
      "name": "London",
      "name_en": "London",
      "slug": "London",
      "country_id": 44,
      "country_name": "United Kingdom",
      "country_name_en": "United Kingdom"
    }
  ],
  "country": [
    {
      "id": 44,
      "name": "United Kingdom",
      "name_en": "United Kingdom",
      "slug": "United Kingdom"
    }
  ],
  "artist": [
    {
      "id": 987,
      "name": "London Symphony Orchestra",
      "name_en": "London Symphony Orchestra",
      "slug": "London Symphony Orchestra"
    }
  ]
}

Response Fields by Category

| Category | Fields | |----------|--------| | artist, country, team | id, name, name_en, slug | | city | id, name, name_en, slug, country_id, country_name, country_name_en | | place | name, name_en, slug, and (when linked) city_id, city_name, country_id, country_name — no id | | voucher | name, name_en, slug — no id |

A category key is present in the response only if it was listed in search_base. A category with no matches returns an empty list ([]).

Notes & Tips

  1. Always follow the required-fields order; re-calling earlier steps resets later data.
  2. Inform users when flexible pricing applies (final price is returned only after tickets PATCH).
  3. For some suppliers, vouchers are delivered directly by the supplier and may not be immediately available via API.
  4. For sports events, tickets may be distributed closer to the event date.

© Bridgify. All rights reserved.