API | Bookings Endpoint
A booking represents a block of time for which an Event or multiple Events can occur.
Booking Fields Overview
Below is a comprehensive list of the fields within the Bookings Endpoint. The order displayed below is representative of the order in which they are displayed within a response body of a standard GET request.
Field Name | Description | Response Example - Key | Value |
“id” | The ID Number for the Booking. | “Id”: (Numerics), |
“name” | The Name of the Booking. | “name”: “(Alphanumerics)”, |
“customer_id” | The ID Number for the Customer that the Booking’s Site is associated with. | “customer_id”: (Numerics), |
“site_id” | The ID Number for the Site that the Booking’s Location is associated with. | “site_id”: (Numerics), |
“location_id” | The ID Number for the Location that the Booking is associated with. | “location_id”: (Numerics), |
“event_ids” | Array | An array or “collection” of IDs of the Events that are associated with the Booking. *If there is a single Event, it will still be displayed within an array. |
“event_ids”: [ (Numerics), (Numerics), … ], |
“status” | The current Status of the Booking itself. *Bookings can have a status independent of the Event(s) associated with it. The available Statuses are: PROSPECT, TENTATIVE, DEFINITE, CLOSED, and LOST |
“status”: “(PROSPECT/TENTATIVE/DEFINITE/ CLOSED/LOST)”, |
“total_event_actual_amount” | The total Actual Amount for all Events associated with the Booking. *The Actual Amount will be cumulative of all picklist items prior to any Taxes or Fees being applied. |
“total_event_actual_amount”: (Numerics), |
“total_actual_amount” |
The total Actual Amount for the Booking as a whole. *The Actual Amount will be cumulative of all picklist items prior to any Taxes or Fees being applied. |
“total_actual_amount”: (Numerics), |
“total_event_grand_total” | The total Grand Total for all Events associated with the Booking. *The Grand Total will be a cumulative total of all picklist items in addition to Taxes, Fees, etc. |
“total_event_grand_total”: (Numerics), |
“total_grand_total” | The total Grand Total for the Booking as a whole. *The Grand Total will be a cumulative total of all picklist items in addition to Taxes, Fees, etc. |
“total_grand_total”: (Numerics), |
“post_as” | This name the Booking displays as. | “post_as”: “(Alphanumerics), |
“updated_by” | The ID of the last User to update the Booking. | “updated_by”: (Numerics), |
“created_by” | The ID of the User to create the Booking. | “created_by”: (Numerics), |
“owned_by” | The ID of the current User to own the Booking. | “owned_by”: (Numerics), |
“start_date” | The date on which the Booking starts. | “start_date”: “YYYY-MM-DD”, |
“end_date” | The date on which the Booking ends. | “end_date”: “YYYY-MM-DD”, |
“definite_date” | The date on which the Booking was moved to the Definite status. | “definite_date”: “YYYY-MM-DD”, |
“tentative_date | The date on which the Booking was moved to the Tentative status. | “tentative_date”: “YYYY-MM-DD”, |
“lost_date” | The date on which the Booking was moved to the Lost status. | “lost_date”: “YYYY-MM-DD”, |
“created_at” | The date and timestamp when the Booking was created. *This is displayed in an iso8601 format |
“created_at”: “YYYY-MM-DDThh:mm:ss”, |
“updated_at” | The date and timestamp when the Booking was last updated. *This is displayed in an iso8601 format |
“updated_at”: “YYYY-MM-DDThh:mm:ss”, |
“deleted_at” | The date and timestamp when the Booking was deleted *This is displayed in an iso8601 format |
“deleted_at”: “YYYY-MM-DDThh:mm:ss”, |
“location” | Object | An object or “collection” of key and value pairs related to the Location that the Booking is associated with. *If there is a single Event, it will still be displayed within an array. |
“location”: { “id”: (Numerics), “name”: “(Alphanumerics)”, “customer_id”: (Numerics), “site_id”: (Numerics) }, |
“market_segment” | The Market Segment associated with the Booking. | “market_segment”: “(Alphanumerics)”, |
“contact” | object | An object or “collection” of key and value pairs related to the Primary Contact associated with the Booking. |
“contact”: { “id”: (Numerics), “first_name”: “(Alphanumerics)”, “last_name”: “(Alphanumerics)”, “account_id”: (Numerics), “email_addresses”: [], “phone_numbers”: [] } |
“secondary_contacts” | Array | An array or “collection” of key and value pairs related to the Secondary Contact(s) associated with the Booking. |
“secondary_contacts”: [ “id”: (Numerics), “first_name”: “(Alphanumerics)”, “last_name”: “(Alphanumerics)”, “account_id”: (Numerics), “email_addresses”: [], “phone_numbers”: [] }, |
“account” | Object | An object or “collection” of key and value pairs related to the Account associated with the Booking. |
“account”: { “id”: (Numerics), “name”: “(Alphanumerics)” } |
“owner” | Object | An object or “collection” of key and value pairs related to the User that is the Owner of the Booking. |
“owner”: { "id": (Numerics), "first_name": "(Alphanumerics)”, "last_name": "(Alphanumerics)”, "title": "(Alphanumerics)”, "email": "(Alphanumerics)", "created_at": "MM/DD/YYYY hh:mm AM/PM", "updated_at": "MM/DD/YYYY hh:mm AM/PM", "login_count": (Numerics), "login_at": “MM/DD/YYYY hh:mm AM/PM”, "customer_id": (Numerics), “phone_numbers”: [] } |
“creator” | Object | An object or “collection” of key and value pairs related to the User that is the Creator of the Booking. |
“creator”: { "id": (Numerics), "first_name": "(Alphanumerics)”,, "last_name": "(Alphanumerics)", "title": "(Alphanumerics)", "email": "(Alphanumerics)", "created_at": "MM/DD/YYYY hh:mm AM/PM", "updated_at": "MM/DD/YYYY hh:mm AM/PM", "login_count": (Numerics), "login_at": “MM/DD/YYYY hh:mm AM/PM”, "customer_id": (Numerics), "phone_numbers": [] } |
“updator” | Object | An object or “collection” of key and value pairs related to the User that is the most recent Updator of the Booking. |
“updator”: { "id": (Numerics), "first_name": "(Alphanumerics)”,, "last_name": "(Alphanumerics)", "title": "(Alphanumerics)", "email": "(Alphanumerics)", "created_at": "MM/DD/YYYY hh:mm AM/PM", "updated_at": "MM/DD/YYYY hh:mm AM/PM", "login_count": (Numerics), "login_at": “MM/DD/YYYY hh:mm AM/PM”, "customer_id": (Numerics), "phone_numbers": [] } |
“status_changes” | Array | An array or “collection” of key and value pairs related to the changes in the Status of the Booking. |
“status_changes”: [ { "status": "(PROSPECT/TENTATIVE/DEFINITE/ CLOSED/LOST)", "previous_status": “(PROSPECT/TENTATIVE/DEFINITE/ CLOSED/LOST)”, "created_at": "MM/DD/YYYY hh:mm AM/PM", "created_by": (Numerics) }, {...} ] |
“custom_fields” | Array | An array of “collection” of key and value pairs related to Custom Fields present on the Booking Level. |
“custom_fields”: [ { "id": (Numerics), "custom_field_name": "(Alphanumerics)", "custom_field_id": (Numerics), "custom_field_required": (true/false), "custom_field_slug": "(Alphanumerics)", "value": "" }, {...} ], |
“documents” | Array |
An array or “collection” of key and value pairs related to the information present on the Tripleseat Documents associated with the Booking. *Depending on the setup of your Tripleseat your team may utilize Booking Documents, Event Document. If you are unsure a User with access to Settings can navigate to Settings -> Documents where you will see headers for either “Event Documents” or “Booking Documents” |
* Please see “Pro-Tips” at the bottom of the page for a complete list of fields as well as a full breakdown on how to access these fields. * |
“payment_set” | Object | An object or “collection of key and value pairs related to the Payment(s) associated with the Booking. *It is important to note that this Payment Set object is specific to payments that fit the following criteria IF the payment is present on the Booking Level AND is not attached to any documents. |
“payment_set”: { "amount_due": "(Numerics)", "running_balance": "(Numerics)", "remaining_payment_amount": "(Numerics)", "document_name": "(Alphanumerics)", "payments": [] }, |
“events” | Array | An array or “collection of key and value pairs related to the Events associated with the Booking. | * Please see “API | Events Endpoint” for a complete list of the fields present in this array. * |
GET Request Examples:
GET https://api.tripleseat.com/v1/bookings.(XML | JSON)
This request will pull a paginated list of all Bookings.
GET https://api.tripleseat.com/v1/bookings/(Booking_ID).(XML | JSON)
This request will pull Booking information specific to the ID specified in the request URL.
Bookings Search:
GET https://api.tripleseat.com/v1/bookings/search.(XML | JSON)?(Search_Parameters)
This request will pull Booking information for any records that match the queried parameters. When you query multiple parameters, you can append parameters together using a “&”.
Parameter | Value |
query | Name, and Event Name |
order | created_at, updated_at, and name |
sort_direction | desc, asc |
location_ids | comma separated list of location ID's |
booking_start_date | mm/dd/yyyy (Date Range and requires booking_end_date) |
booking_end_date | mm/dd/yyyy (Date Range and requires booking_start_date) |
booking_created_start_date | mm/dd/yyyy (Date Range and requires booking_created_end_date) |
booking_created_end_date | mm/dd/yyyy (Date Range and requires booking_created_start_date) |
booking_updated_start_date | mm/dd/yyyy (Date Range and requires booking_updated_end_date) |
booking_updated_end_date | mm/dd/yyyy (Date Range and requires booking_updated_start_date) |
status | lost, definite, tentative, prospect and closed |
page | (Numerics starting at 1) |
site_id | numerics |
Example: ?page=1&sort_direction=desc&order=created_at
The above example would Search the Bookings list on Page 1, in descending order and ordered by the created_at field.
DELETE Request Example:
DELETE https://api.tripleseat.com/v1/bookings/(Booking_ID).(XML | JSON)
This request will delete the Booking with the associated ID specified in the request URL.
POST Request Example:
Creating Bookings via the API can be done by either:
Appending the Booking information to the end of the URL. This would look similar to the following
POST https://api.tripleseat.com/v1/bookings.(XML | JSON)?booking[name]=Tripleseat NYE Party&booking[start_date]=12/31/2023&booking[end_date]=01/01/2024&booking[location_id]=19667
Including the Booking information in the Body of the Request. The following is the URL and the Body which is in the JSON format
POST https://api.tripleseat.com/v1/bookings.(XML | JSON)
{
"booking": {
"name": "(Alphanumerics)",
"start_date": "MM/DD/YYYY",
"end_date": "MM/DD/YYYY",
"location_id": (Numerics)
}
}
Required Fields for creating a Booking:
- “name”
- “start_date”
- “end_date”
- “location_id”
PUT Request Example:
Updating Bookings via the API require the Booking ID be identified in the URL similar to the GET Example from earlier in this article. Once the URL is adjusted the update format can be done by either:
Appending the Booking information that needs to be updated to the end of the URL. This would look similar to the following:
PUT https://api.tripleseat.com/v1/bookings/(Booking_ID).(XML | JSON)?booking[end_date]=MM/DD/YYYY
Including the Booking information that needs to be updated in the Body of the Request. This would look similar to the following:
PUT https://api.tripleseat.com/v1/bookings/(Booking_ID).(XML | JSON)
{
"booking": {
"name": "(Alphanumerics)",
"start_date": "MM/DD/YYYY",
"end_date": "MM/DD/YYYY",
"location_id": (Numerics)
}
}
Pro-Tips
Booking Financial Fields
These are only visible by adding the parameter '&show_financial=true'. This will add the following financial details under the documents array:
Field Name | Description | Response Example - Key | Value |
“id” | The ID Number or “Record” for this particular Document set. | “Id”: (Numerics), |
“title” | The Title or “Name” of the Document set. | “title”: “(Alphanumerics)”, |
“document_template_id” | The ID Number for the Document Template used when adding the Document set to the Booking. | “document_template_id”: (Numerics), |
“views” | Array | The View(s) or Document Layouts that exist within the Document Set associated with the Booking. |
“views”: [ { “name”: “(Alphanumerics)”, “url”: “(Alphanumerics)” }, {...} ], |
"line_items" | Array | An array or “Collection” of information related to the Line Items present on the Document set associated with the Booking. |
"line_items": [ { "id": (Numerics), }, {...} ], |
“billing_totals” | Array | An array or “Collection” of information related to the Billing Details present on the Document set associated with the Booking. |
“billing_totals”: [ { "description": "(Alphanumerics)", "value": "(Numerics)", "total_price": "(Numerics)” }, {...} ], |
“financials” | Object |
An object containing the most frequently sought after financials on the Document set associated with the Booking. *This Object will only contain Amount Due, Grand Total, and Discounts Total |
“financials”: { "amount_due": "(Numerics)", "grand_total": "(Numerics)", "discounts_total": "(Numerics)" }, |
“payment_set” | The Payment Set represents a collection of key and value pairs related to the payments attached to the Documents that are associated with the Booking. |
“Payment_set”: { "amount_due": "(Numerics)", "running_balance": "(Numerics)", "remaining_payment_amount": "(Numerics)", "document_name": "(Alphanumerics)", "payments": [ { "id": (Numerics), "amount": "(Numerics)", "state": "(new/paid/deleted/refunded/partially_refunded)” "custom_title": "(Alphanumerics)", "created_at": "DD/MM/YYYY hh:mm AM/PM", "due_at": “DD/MM/YYYY”, "paid_at": “DD/MM/YYYY”, "payable_by_guest": (true/false), "unpaid_at": “DD/MM/YYYY”, "billing_kind": “(Alphanumerics)”, "payment_method": “(Alphanumerics)”, “credit_card_type": “(Alphanumerics)”, "refunded_at": “DD/MM/YYYY”, "amount_refunded": (Numerics), "refund_reason": “(Alphanumerics), "paid_by": “(Alphanumerics), "custom_field": “(Alphanumerics) }, {...} ] |
Comments
0 comments
Article is closed for comments.