Proposals/Confirmed Bookings

Create a booking

Creates a booking -- an event the client has already committed to. For one they still have to accept, use POST /api/v1/proposals.

signature_collected defaults to true, which creates the booking confirmed. Send false when you are still waiting on the contract and it is created awaiting_signature instead.

Attaching the client

contact_type decides where the client comes from. It takes one of three exact strings -- anything else is rejected:

contact_type	What it does
New Customer	The default. Creates the client from the contact_* fields, and contact_name is required. If contact_email matches someone the business already has, that person is linked rather than duplicated.
Existing Customer	Links a client who already exists. customer_user_id is required, and must be a user on this business.
None	Creates the booking with nobody attached.

Under New Customer, sending contact_email creates a full customer account the client can sign and pay through. Without one you get a plain contact record on the booking instead, which can do neither.

The contact_* address fields hold the client's address. The venue address is separate, in the venue_* fields.

Packages

packages is required -- a booking with no package has nothing to price. Each entry needs an event_type_id (a package id from GET /api/v1/packages) and a starts_at_date. Send several to book more than one package on the same event.

Pricing, tax, travel fees and the title are all calculated from the packages and the venue. Send total_amount only to override the calculated total.

Dates, times and amounts

Dates are ISO YYYY-MM-DD. Other numeric formats are read according to the business's own date format setting, so 03-04-2027 is March 4th for a US business and April 3rd for an international one. Times take 11:00AM, 2:30pm or 14:30.

Amounts are in the business's currency in whole units rather than cents, so 1250.00 is $1,250.00.

Required permission: event_create

post/api/v1/bookings

Request

Base URL: https://api.checkcherry.com
URL: https://api.checkcherry.com/api/v1/bookings
Auth: none declared. Required headers: Api-Key

Headers

Api-Keystring required

Your Integration Key

Request body

signature_collectedboolean

Has the signature already been collected? Defaults to true, creating a confirmed booking. false creates it awaiting_signature.

contact_type'New Customer' | 'Existing Customer' | 'None'

Where the client comes from. See the description above.

customer_user_idinteger

The existing client's user ID, which must belong to this business. Required when contact_type is Existing Customer.

contact_namestring

Client's name. Required when contact_type is New Customer.

contact_emailstring

Client's email. Creates a full customer account rather than a plain contact record.

contact_phonestring

Client's phone

contact_company_namestring

Client's company name

contact_descriptionstring

Client's role, e.g. "Bride" or "Father of the Groom"

contact_streetstring

Client's street address

contact_citystring

Client's city

contact_state_codestring

Client's state or province code, in whatever form the business's country uses, e.g. MA

contact_postal_codestring

Client's postal code

send_contact_invitation_to_create_accountboolean

Email the client an invitation to create an account. Requires contact_email.

send_booking_confirmation_emailsboolean

Send the client the booking confirmation emails. Requires contact_email.

venue_namestring

Venue name

venue_addressstring

Venue street address

venue_citystring

Venue city

venue_statestring

Venue state or province code, in whatever form the business's country uses, e.g. MA

venue_zipstring

Venue postal code

venue_google_place_idstring

Google Place ID for the venue

venue_latitudenumber

Venue latitude

venue_longitudenumber

Venue longitude

add_taxboolean

Apply tax based on the venue's tax zone. Defaults to true.

add_travelboolean

Apply travel fees based on the venue's travel zone. Defaults to true.

public_notesstring

Notes visible to the client

private_notesstring

Notes only staff can see

custom_titlestring

Overrides the generated title

brand_idinteger

Brand to book under, which must be an active brand of this business. Defaults to the primary brand.

lead_idinteger

Lead this booking converts, from GET /api/v1/leads. The lead's details and attribution carry over and it is marked converted.

total_amountnumber

Overrides the calculated event total. In whole currency units, so 1250.00 means $1,250.00. Max 999000.

paid_amountnumber

Payment already collected outside Check Cherry, recorded against the booking. In whole currency units. Max 999000.

custom_deposit_amountnumber

Overrides the calculated deposit due. In whole currency units, and capped at the event total. Max 999000.

Response

booking created

Changes

No recorded changes to this operation across all 2 revisions of this API.