Wiki

Method: POST

Path: /booking

Create a new booking as non-logged-in customer.

IMPORTANT: do not call this API endpoint simultaneously for different bookings with the same discount_code to prevent discount code (discount, giftcard, reward) overuse.

Request schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Create booking request",
  "type": "object",

  "properties": {
    "quote_uuid": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 255
    },
    "location_id": {
        "type": ["integer", "null"]
    },
    "user": {
        "title": "Customer details",
        "type": "object",
        "properties": {
            "email": {
                "type": "string",
                "format": "email",
                "minLength": 1,
                "maxLength": 255
            },
            "first_name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
            },
            "last_name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
            },
            "company_name": {
                "type": ["string", "null"],
                "minLength": 1,
                "maxLength": 255
            }
        },
        "required": ["email", "first_name", "last_name"]
    },
    "address": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255
    },
    "city": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 100
    },
    "state": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 3
    },
    "zip": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 10
    },
    "phone": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 20
    },
    "sms_notifications": {
        "type": ["boolean", "null"]
    },
    "frequency_id": {
        "type": "integer",
        "minimum": 1
    },
    "service_date": {
        "type": "string",
        "pattern": "\\A\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\z"
    },
    "arrival_window": {
        "title": "arrival window in minutes",
        "type": "integer",
        "minimum": 0,
        "maximum": 1440
    },
    "services": {
      "type": "array",
      "items": {
        "title": "Service",
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "minimum": 1
            },
            "hourly": {
                "type": ["object", "null"],
                "properties": {
                    "quantity": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100
                    },
                    "minutes": {
                        "type": "integer",
                        "minimum": 30,
                        "maximum": 1440,
                        "multipleOf": 30
                    }
                },
                "required": ["quantity", "minutes"]
            },
            "extras": {
                "type": ["array", "null"],
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "quantity": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 10000
                        },
                        "recurring": {
                            "type": ["boolean", "null"]
                        }
                    },
                    "required": ["id", "quantity"]
                }
            },
            "pricing_parameters": {
                "type": ["array", "null"],
                "items": {
                    "type": "object",
                    "properties": {
                        "id": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "quantity": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 250000
                        }
                    },
                    "required": ["id", "quantity"]
                }
            }
        },
        "required": ["id"]
      },
      "minItems": 1
    },
    "discount_code": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 255
    },
    "tip": {
        "type": ["number", "null"],
        "minimum": 0,
        "maximum": 100000
    },
    "tip_recurring": {
        "type": ["boolean", "null"]
    },
    "payment_method": {
        "type": "string",
        "enum": ["stripe", "paypal", "cash", "check"]
    },
    "stripe_token": {
        "type": ["string", "null"],
        "minLength": 1,
        "maxLength": 100
    },
    "customer_notes": {
        "type": ["string", "null"],
        "minLength": 1
    },
    "custom_fields": {
        "type": ["array", "null"],
        "items": {
            "oneOf": [{
                "title": "Single-Line or Multi-Line values or Date (\\A\\d{4}-\\d{2}-\\d{2}\\z) or DateTime (\\A\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\z) or Checkbox (true or false)",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "value": {
                        "type": "string",
                        "minLength": 0
                    }
                },
                "required": ["id", "value"],
                "additionalProperties": false
            }, {
                "title": "Radio buttons, drop downs or checkboxes values",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "values": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer",
                                    "minimum": 1
                                },
                                "other": {
                                    "type": ["string", "null"]
                                }
                            },
                            "required": ["id"]
                        },
                        "minItems": 0
                    }
                },
                "required": ["id", "values"],
                "additionalProperties": false
            }]
        }
    },
    "meta": {
        "type": ["array", "null"],
        "items": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "string",
                    "minLength": 1
                },
                "value": {
                    "type": "string",
                    "minLength": 1
                }
            },
            "required": ["code", "value"]
        },
        "minItems": 0
    }
  },

  "required": [
     "user",
     "address",
     "frequency_id",
     "service_date",
     "arrival_window",
     "services",
     "payment_method"
  ]
}

Where:

location_id (required) is unique ID of location (use Location for booking to get location details by booking address)
user (required) is customer details, has following attributes:
- email (required) is customer's email
- first_name (required) is customer's first name
- last_name (required) is customer's last name
- company_name (optional) is customer's company name
address (required) is street address part of booking address
city (optional or required, depends on account settings) is city part of booking address
state (optional or required, depends on account settings) is state part of booking address
zip (optional or required, depends on account settings) is zip code (postal code) part of booking address
phone (optional or required, depends on account settings) is customer's contact phone for the booking
sms_notifications (optional or required, depends on account settings) tells if customer wants receive SMS notifications about this booking or not
frequency_id (required) is unique ID of frequency (use Frequencies for booking to get frequency details)
service_date (required) is booked date and time
arrival_window (required) is booked arrival window in minutes; possible values 0 - 1440; 0 means that booked appointment supposed to start exactly at service_date, while values from 1 to 1440 allows flexibility. Note: combination of service_date and arrival_window must correspond to available spots (see Spots for booking, use mode="new")
services (required) is a list of booked services (see service attributes below); at least one service must be booked; more than one service can be booked if features -> booking -> multiple_services is true (see Get settings)
discount_code (optional) is one of allowed discounts (note: provided code could or could not be eligible to get discount for booking), code could be:
- code of discount by code
- gift card code (requires features -> gift_cards, see Get settings))
- referral code (requires features -> customer_referral_engine, see Get settings))
tip (optional) is value of the tip for booking. Note: tips could be prohibited for account (see features -> booking -> tips in Get settings)
tip_recurring (optional) is recurring preference for tip (copy tip value over to the next recurring booking or not); if value not provided, tip considered to be non-recurring
payment_method is payment method preference for booking, must be one of accepted account's payment methods (see payment_methods in Get settings). Note: "stripe" payment method requires account to be linked to Stripe.
stripe_token (required for payment_method="stripe") is credit card token generated using stripe_public_key (see Get settings) and Stripe.js.
customer_notes (optional or required, depends on account settings) is a free text note that customer might want to add
custom_fields (optional) is a set of answers to custom questions (see custom field attributes below). Note: custom_fields are required if at least one custom field is required (see Custom_fields_for_booking)
meta (optional) just ignore it
service attributes:
- id (required) is unique ID of service (use Services for booking to get service details)
- hourly (required for hourly services, see hourly in Services for booking), has attributes:
  - quantity is a number of booked workers
  - minutes is a number of minutes booked per worker
- extras (optional) is a list of booked extras (see exta attributes below). Note: only extras that linked to the service can be booked as part of the service (see extras in Services for booking)
- pricing_parameters (required if service has linked pricing parameters) is a list of booked pricing parameters (see pricing parameter attributes below). Note: only pricing parameters that linked to the service can be booked as part of the service (see pricing_parameters in Services for booking)
exta attributes:
- id (required) is unique ID of extra (see extras in Services for booking)
- quantity (required) is number of booked extra's units. Note: quantity greater than 1 cannot be used unless extra has quantity_based=true (see extras in Services for booking)
- recurring (optional) is recurring preference for extra (copy extra over to the next recurring booking or not); if value not provided, default value for extra will be used (see recurring for extra in Services for booking)
pricing parameter attributes:
- id (required) is unique ID of pricing parameter (see pricing_parameters in Services for booking)
- quantity (required) is number of booked pricing parameter's units. Note: value must be within allowed range for pricing parameter (see quantity_minimum and quantity_maximum for pricing parameter in Services for booking)
custom field attributes:
- id (required) is unique ID of custom field (see Custom fields for booking)
- value (attribute required and must be present only for custom field with type single_line, multi_line, date, datetime or checkbox) can be empty string if custom field is not required (i.e. value_required=false for the custom field in Custom fields for booking), othervise expects value in following format:
  - free text for single_line or multi_line
  - "YYYY-MM-DD" for date
  - "YYYY-MM-DDTHH:MM:SS" for datetime
  - "true" or "false" for checkbox
- values (attribute required and must be present only for custom field with type radio_buttons, checkboxes or drop_down) is a list of selected options, every option has attributes:
  - id (required) is unique ID of option (see Custom fields for booking)
  - other (required for options with other=true, see Custom fields for booking) is a free text provided by customer for option if option requires additional explanation.

Example request:

For production, replace https://acme-sandbox.l27.co with https://<your subdomain>.launch27.com

curl -H "Content-Type: application/json" \
     -X POST -k \
     -d '{"user": {"email": "user@email.com", "first_name": "First", "last_name": "Last"}, "address":"595 Market St", "city":"San Francisco", "state":"CA", "zip":"94105", "phone":"462-485-0790", "frequency_id": 1, "service_date": "2019-08-15T09:30:00", "arrival_window":0, "services":[{"id":1}],  "payment_method":"cash" }' \
      https://acme-sandbox.l27.co/latest/booking

Example of response

{
  "id": 1,
  "ga_transaction": {
    "id": "NcUHgV93Vkf7Jxgr8P6rvOi3DMLpYvc2",
    "affilation": "acme-sandbox",
    "revenue": 99.00
  },
  "ga_item": {
    "id": "NcUHgV93Vkf7Jxgr8P6rvOi3DMLpYvc2",
    "name": "Booking",
    "price": 99.00,
    "quantity": 1
  }
}

Where:

id is unique ID of created booking
ga_transaction and ga_item contain data for GA ecommerce tracking:
- id is unique digest code of created booking
- name is always Booking
- affilation is account's subdomain
- revenue is final price of created booking
- price is final price of created booking
- quantity is always 1