Proposals/Confirmed Bookings

Create a proposal

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

proposal_date_reserved decides what happens to the date while they decide. It defaults to false, leaving the date open to other bookings; send true to hold it for them. proposal_valid_through is the last day they can accept, and defaults to the business's own expiry setting. A date after the event is quietly pulled back to the event date; one in the past is rejected.

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 proposal with nobody attached.

Under New Customer, sending contact_email creates a full customer account the client can accept and pay through. Without one you get a plain contact record on the proposal 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 proposal 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 propose 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 or proposal_create

post/api/v1/proposals

Request

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

Headers

Api-Keystring required

Your Integration Key

Request body

proposal_date_reservedboolean

Hold the date while the client decides, blocking other bookings. Defaults to false.

proposal_valid_throughstring

Last day the client can accept, as YYYY-MM-DD. Must not be in the past, and is capped at the event date. Defaults to the business's own expiry setting.

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

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 propose under, which must be an active brand of this business. Defaults to the primary brand.

lead_idinteger

Lead this proposal 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 proposal. 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

proposal created

Changes

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