Square Appointments
App · 20 actions
Manage bookings, availability, customers, locations and bookable team members.
Actions
| Action | What it does |
|---|---|
| Cancel booking | Cancel a booking. |
| Create booking | Create a booking. |
| Create customer | Create a customer profile. |
| Delete customer | Delete a customer profile. |
| Get booking | Get one booking by its ID. |
| Get business booking profile | Get the seller's booking profile. |
| Get catalog object | Get one catalog item by its ID, with its variations, its modifier lists and the taxes that apply to it. |
| Get customer | Get the details of one customer. |
| Get location | Get the details of one location. |
| Get team member booking profile | Get one team member's booking profile. |
| List bookings | List bookings, optionally for one customer, team member or location, or within a range of start times. |
| List catalog | List the catalog objects of the types you choose, such as items, item variations, modifiers, categories, discounts, taxes and images. |
| List customers | List the customer profiles in the Square account. |
| List location booking profiles | List the seller's location booking profiles. |
| List locations | List all of the seller's locations, including inactive ones, in alphabetical order by name. |
| List team member booking profiles | List the booking profiles of team members, optionally only bookable ones or those at one location. |
| Search availability | Search for times that are free to book. |
| Search customers | Search customer profiles with one or more filters. |
| Update booking | Update a booking. |
| Update customer | Update a customer profile; only the fields you fill in are changed. |
Cancel booking
Cancel a booking. The seller must subscribe to Square Appointments Plus or Premium.
Inputs
- Booking ID
booking_idtextRequired - The ID of the Booking object representing the to-be-cancelled booking.
- Idempotency key
idempotency_keytext - A unique key to make this request an idempotent operation.
- Booking version
booking_versionnumber - The revision number for the booking used for optimistic concurrency.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"booking": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"all_day": false,
"appointment_segments": [],
"created_at": "example",
"creator_details": {
"creator_type": "TEAM_MEMBER",
"customer_id": "example",
"team_member_id": "example"
},
"customer_id": "example",
"customer_note": "example",
"id": "example",
"location_id": "example",
"location_type": "BUSINESS_LOCATION",
"seller_note": "example",
"source": "FIRST_PARTY_MERCHANT",
"start_at": "example",
"status": "PENDING",
"transition_time_minutes": 1,
"updated_at": "example",
"version": 1
},
"errors": []
}
}Create booking
Create a booking. It needs a location, a start time, and at least one appointment segment with a team member, service variation and service variation version. The seller must subscribe to Square Appointments Plus or Premium.
Inputs
- Idempotency key
idempotency_keytext - A unique key to make this request an idempotent operation.
- Booking ID
booking_idtext - A unique ID of this object representing a booking.
- Booking version
booking_versionnumber - The revision number for the booking used for optimistic concurrency.
- Booking start at
booking_start_atdate and timeRequired - The RFC 3339 timestamp specifying the starting time of this booking.
- Booking location ID
booking_location_idtextRequired - The ID of the Location object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed.
- Booking customer ID
booking_customer_idtextRequired - The ID of the Customer object representing the customer receiving the booked service.
- Booking customer note
booking_customer_notetext - The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant CatalogObject instance.
- Booking seller note
booking_seller_notetext - The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific CatalogObject instance. This field should not be visible to customers.
- Booking appointment segments
booking_appointment_segmentslistRequired - A list of appointment segments for this booking.
- Booking all day
booking_all_daytrue/false - Whether the booking is of a full business day.
- Booking location type
booking_location_typetext - The type of location where the booking is held. See [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype) for possible valuesOne of:
BUSINESS_LOCATION(Business location),CUSTOMER_LOCATION(Customer location),PHONE.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"booking": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"all_day": false,
"appointment_segments": [],
"created_at": "example",
"creator_details": {
"creator_type": "TEAM_MEMBER",
"customer_id": "example",
"team_member_id": "example"
},
"customer_id": "example",
"customer_note": "example",
"id": "example",
"location_id": "example",
"location_type": "BUSINESS_LOCATION",
"seller_note": "example",
"source": "FIRST_PARTY_MERCHANT",
"start_at": "example",
"status": "PENDING",
"transition_time_minutes": 1,
"updated_at": "example",
"version": 1
},
"errors": []
}
}Create customer
Create a customer profile. Give at least one of a first name, last name, company name, email address or phone number.
Inputs
- Idempotency key
idempotency_keytext - The idempotency key for the request. For more information, see Idempotency.
- Given name
given_nametext - The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters.
- Family name
family_nametext - The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters.
- Company name
company_nametext - A business name associated with the customer profile. The maximum length for this value is 500 characters.
- Nickname
nicknametext - A nickname for the customer profile. The maximum length for this value is 100 characters.
- Email address
email_addresstext - The email address associated with the customer profile. The maximum length for this value is 254 characters.
- Address
addressobject - The physical address associated with the customer profile. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.
- Phone number
phone_numbertext - The phone number associated with the customer profile. The phone number must be valid and can contain 9-16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.
- Reference ID
reference_idtext - An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters.
- Note
notetext - A custom note associated with the customer profile.
- Birthday
birthdaydate - The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.
- Tax IDs
tax_idsobject - The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see Customer tax IDs.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the [CreateCustomer](api-endpoint:Customers-CreateCustomer) or [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers) endpoint. Either `errors` or `customer` is present in a given response (never both).
Example output
{
"data": {
"customer": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"birthday": "example",
"company_name": "example",
"created_at": "example",
"creation_source": "OTHER",
"email_address": "example",
"family_name": "example",
"given_name": "example",
"group_ids": [],
"id": "example",
"nickname": "example",
"note": "example",
"phone_number": "example",
"preferences": {
"email_unsubscribed": false
},
"reference_id": "example",
"segment_ids": [],
"tax_ids": {
"eu_vat": "example"
},
"updated_at": "example",
"version": 1
},
"errors": []
}
}Delete customer
Delete a customer profile. For a profile created by merging others, use the ID of the merged profile.
Inputs
- Customer ID
customer_idtextRequired - The ID of the customer to delete.
- Version
versionnumber - The current version of the customer profile. As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the `DeleteCustomer` endpoint.
Example output
{
"data": {
"errors": []
}
}Get booking
Get one booking by its ID.
Inputs
- Booking ID
booking_idtextRequired - The ID of the Booking object representing the to-be-retrieved booking.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"booking": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"all_day": false,
"appointment_segments": [],
"created_at": "example",
"creator_details": {
"creator_type": "TEAM_MEMBER",
"customer_id": "example",
"team_member_id": "example"
},
"customer_id": "example",
"customer_note": "example",
"id": "example",
"location_id": "example",
"location_type": "BUSINESS_LOCATION",
"seller_note": "example",
"source": "FIRST_PARTY_MERCHANT",
"start_at": "example",
"status": "PENDING",
"transition_time_minutes": 1,
"updated_at": "example",
"version": 1
},
"errors": []
}
}Get business booking profile
Get the seller's booking profile.
Inputs
None.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"business_booking_profile": {
"allow_user_cancel": false,
"booking_enabled": false,
"booking_policy": "ACCEPT_ALL",
"business_appointment_settings": {
"alignment_time": "SERVICE_DURATION",
"any_team_member_booking_enabled": false,
"cancellation_fee_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
},
"cancellation_policy": "CANCELLATION_TREATED_AS_NO_SHOW",
"cancellation_policy_text": "example",
"cancellation_window_seconds": 1,
"location_types": [],
"max_appointments_per_day_limit": 1,
"max_appointments_per_day_limit_type": "PER_TEAM_MEMBER",
"max_booking_lead_time_seconds": 1,
"min_booking_lead_time_seconds": 1,
"multiple_service_booking_enabled": false,
"skip_booking_flow_staff_selection": false
},
"created_at": "example",
"customer_timezone_choice": "BUSINESS_LOCATION_TIMEZONE",
"seller_id": "example",
"support_seller_level_writes": false
},
"errors": []
}
}Get catalog object
Get one catalog item by its ID, with its variations, its modifier lists and the taxes that apply to it.
Inputs
- Object ID
object_idtextRequired - The object ID of any type of catalog objects to be retrieved.
- Include related objects
include_related_objectstrue/false - If true, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the objects field of the response. These objects are put in the related_objects field. Setting this to true is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response. Default value: false
- Catalog version
catalog_versionnumber - Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects. If not included, results will be from the current version of the catalog.
- Include category path to root
include_category_path_to_roottrue/false - Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"errors": [],
"object": {
"absent_at_location_ids": [],
"availability_period_data": {
"day_of_week": "SUN",
"end_local_time": "example",
"start_local_time": "example"
},
"catalog_v1_ids": [],
"category_data": {
"availability_period_ids": [],
"category_type": "REGULAR_CATEGORY",
"channels": [],
"ecom_seo_data": {
"page_description": "example",
"page_title": "example",
"permalink": "example"
},
"image_ids": [],
"is_top_level": false,
"name": "example",
"online_visibility": false,
"parent_category": {
"id": "example",
"ordinal": 1
},
"path_to_root": [],
"root_category": "example"
},
"custom_attribute_definition_data": {
"allowed_object_types": [],
"app_visibility": "APP_VISIBILITY_HIDDEN",
"custom_attribute_usage_count": 1,
"description": "example",
"key": "example",
"name": "example",
"number_config": {
"precision": 1
},
"selection_config": {
"allowed_selections": [],
"max_allowed_selections": 1
},
"seller_visibility": "SELLER_VISIBILITY_HIDDEN",
"source_application": {
"application_id": "example",
"name": "example",
"product": "SQUARE_POS"
},
"string_config": {
"enforce_uniqueness": false
},
"type": "STRING"
},
"custom_attribute_values": {},
"discount_data": {
"amount_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
},
"discount_type": "FIXED_PERCENTAGE",
"label_color": "example",
"maximum_amount_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
},
"modify_tax_basis": "MODIFY_TAX_BASIS",
"name": "example",
"percentage": "example",
"pin_required": false
},
"id": "example",
"image_data": {
"caption": "example",
"name": "example",
"photo_studio_order_id": "example",
"url": "example"
},
"is_deleted": false,
"item_data": {
"abbreviation": "example",
"buyer_facing_name": "example",
"categories": [],
"category_id": "example",
"channels": [],
"description": "example",
"description_html": "example",
"description_plaintext": "example",
"ecom_image_uris": [],
"ecom_seo_data": {
"page_description": "example",
"page_title": "example",
"permalink": "example"
},
"ecom_uri": "example",
"food_and_beverage_details": {
"calorie_count": 1,
"dietary_preferences": [],
"ingredients": []
},
"image_ids": [],
"is_alcoholic": false,
"is_archived": false,
"is_taxable": false,
"item_options": [],
"kitchen_name": "example",
"label_color": "example",
"modifier_list_info": [],
"name": "example",
"product_type": "REGULAR",
"reporting_category": {
"id": "example",
"ordinal": 1
},
"skip_modifier_screen": false,
"sort_name": "example",
"tax_ids": [],
"variations": []
},
"item_option_data": {
"description": "example",
"display_name": "example",
"name": "example",
"show_colors": false,
"values": []
},
"item_option_value_data": {
"color": "example",
"description": "example",
"item_option_id": "example",
"name": "example",
"ordinal": 1
},
"item_variation_data": {
"available_for_booking": false,
"image_ids": [],
"inventory_alert_threshold": 1,
"inventory_alert_type": "NONE",
"item_id": "example",
"item_option_values": [],
"kitchen_name": "example",
"location_overrides": [],
"measurement_unit_id": "example",
"name": "example",
"ordinal": 1,
"price_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
},
"pricing_type": "FIXED_PRICING",
"sellable": false,
"service_duration": 1,
"sku": "example",
"stockable": false,
"stockable_conversion": {
"nonstockable_quantity": "example",
"stockable_item_variation_id": "example",
"stockable_quantity": "example"
},
"team_member_ids": [],
"track_inventory": false,
"upc": "example",
"user_data": "example",
"vendor_information": []
},
"measurement_unit_data": {
"measurement_unit": {
"area_unit": "IMPERIAL_ACRE",
"custom_unit": {
"abbreviation": "example",
"name": "example"
},
"generic_unit": "UNIT",
"length_unit": "IMPERIAL_INCH",
"time_unit": "GENERIC_MILLISECOND",
"type": "TYPE_CUSTOM",
"volume_unit": "GENERIC_FLUID_OUNCE",
"weight_unit": "IMPERIAL_WEIGHT_OUNCE"
},
"precision": 1
},
"modifier_data": {
"child_modifier_list_ids": [],
"hidden_online": false,
"image_id": "example",
"kitchen_name": "example",
"location_overrides": [],
"modifier_list_id": "example",
"name": "example",
"on_by_default": false,
"ordinal": 1,
"price_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
}
},
"modifier_list_data": {
"allow_quantities": false,
"hidden_from_customer": false,
"image_ids": [],
"internal_name": "example",
"is_conversational": false,
"max_length": 1,
"max_selected_modifiers": 1,
"min_selected_modifiers": 1,
"modifier_type": "LIST",
"modifiers": [],
"name": "example",
"ordinal": 1,
"selection_type": "SINGLE",
"text_required": false
},
"present_at_all_locations": false,
"present_at_location_ids": [],
"pricing_rule_data": {
"apply_products_id": "example",
"customer_group_ids_any": [],
"discount_id": "example",
"exclude_products_id": "example",
"exclude_strategy": "LEAST_EXPENSIVE",
"match_products_id": "example",
"minimum_order_subtotal_money": {
"amount": 1,
"currency": "UNKNOWN_CURRENCY"
},
"name": "example",
"time_period_ids": [],
"valid_from_date": "example",
"valid_from_local_time": "example",
"valid_until_date": "example",
"valid_until_local_time": "example"
},
"product_set_data": {
"all_products": false,
"name": "example",
"product_ids_all": [],
"product_ids_any": [],
"quantity_exact": 1,
"quantity_max": 1,
"quantity_min": 1
},
"quick_amounts_settings_data": {
"amounts": [],
"eligible_for_auto_amounts": false,
"option": "DISABLED"
},
"subscription_plan_data": {
"all_items": false,
"eligible_category_ids": [],
"eligible_item_ids": [],
"name": "example",
"phases": [],
"subscription_plan_variations": []
},
"subscription_plan_variation_data": {
"can_prorate": false,
"monthly_billing_anchor_date": 1,
"name": "example",
"phases": [],
"subscription_plan_id": "example",
"successor_plan_variation_id": "example"
},
"tax_data": {
"applies_to_custom_amounts": false,
"applies_to_product_set_id": "example",
"calculation_phase": "TAX_SUBTOTAL_PHASE",
"enabled": false,
"inclusion_type": "ADDITIVE",
"name": "example",
"percentage": "example"
},
"time_period_data": {
"event": "example"
},
"type": "ITEM",
"updated_at": "example",
"version": 1
},
"related_objects": []
}
}Get customer
Get the details of one customer.
Inputs
- Customer ID
customer_idtextRequired - The ID of the customer to retrieve.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the `RetrieveCustomer` endpoint. Either `errors` or `customer` is present in a given response (never both).
Example output
{
"data": {
"customer": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"birthday": "example",
"company_name": "example",
"created_at": "example",
"creation_source": "OTHER",
"email_address": "example",
"family_name": "example",
"given_name": "example",
"group_ids": [],
"id": "example",
"nickname": "example",
"note": "example",
"phone_number": "example",
"preferences": {
"email_unsubscribed": false
},
"reference_id": "example",
"segment_ids": [],
"tax_ids": {
"eu_vat": "example"
},
"updated_at": "example",
"version": 1
},
"errors": []
}
}Get location
Get the details of one location. Enter main as the location ID to get the main location.
Inputs
- Location
location_idtextRequired - The ID of the location to retrieve. Specify the string "main" to return the main location.
Outputs
dataobject- Defines the fields that the [RetrieveLocation](api-endpoint:Locations-RetrieveLocation) endpoint returns in a response.
Example output
{
"data": {
"errors": [],
"location": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"business_email": "example",
"business_hours": {
"periods": []
},
"business_name": "example",
"capabilities": [],
"coordinates": {
"latitude": 1,
"longitude": 1
},
"country": "ZZ",
"created_at": "example",
"currency": "UNKNOWN_CURRENCY",
"custom_receipt_text": "example",
"description": "example",
"facebook_url": "example",
"full_format_logo_url": "example",
"id": "example",
"instagram_username": "example",
"language_code": "example",
"logo_url": "example",
"mcc": "example",
"merchant_id": "example",
"name": "example",
"phone_number": "example",
"pos_background_url": "example",
"return_policy": "example",
"status": "ACTIVE",
"tax_ids": {
"es_nif": "example",
"eu_vat": "example",
"fr_naf": "example",
"fr_siret": "example",
"jp_qii": "example"
},
"timezone": "example",
"twitter_username": "example",
"type": "PHYSICAL",
"website_url": "example"
}
}
}Get team member booking profile
Get one team member's booking profile.
Inputs
- Team member ID
team_member_idtextRequired - The ID of the team member to retrieve.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"errors": [],
"team_member_booking_profile": {
"description": "example",
"display_name": "example",
"is_bookable": false,
"profile_image_url": "example",
"team_member_id": "example"
}
}
}List bookings
List bookings, optionally for one customer, team member or location, or within a range of start times.
Inputs
- Limit
limitnumber - The maximum number of results per page to return in a paged response.
- Cursor
cursortext - The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.
- Customer ID
customer_idtext - The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.
- Team member ID
team_member_idtext - The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.
- Location
location_idtext - The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.
- Start at min
start_at_mindate and time - The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.
- Start at max
start_at_maxdate and time - The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after start_at_min is used.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"bookings": [],
"cursor": "example",
"errors": []
}
}List catalog
List the catalog objects of the types you choose, such as items, item variations, modifiers, categories, discounts, taxes and images. Always choose the types. Deleted items are not included.
Inputs
- Cursor
cursortext - The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See Pagination for more information.
- Types
typestext - An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc. If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults. At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.
- Catalog version
catalog_versionnumber - The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. If not included, results will be from the current version of the catalog.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"cursor": "example",
"errors": [],
"objects": []
}
}List customers
List the customer profiles in the Square account. New or changed profiles usually show up within 30 seconds, but can occasionally take a minute or more.
Inputs
- Cursor
cursortext - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- Limit
limitnumber - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100. For more information, see Pagination.
- Sort field
sort_fieldtext - Indicates how customers should be sorted. The default value is DEFAULT.One of:
DEFAULT,CREATED_AT(Created at). - Sort order
sort_ordertext - Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order. The default value is ASC.One of:
DESC,ASC. - Count
counttrue/false - Indicates whether to return the total count of customers in the count field of the response. The default value is false.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the `ListCustomers` endpoint. Either `errors` or `customers` is present in a given response (never both).
Example output
{
"data": {
"count": 1,
"cursor": "example",
"customers": [],
"errors": []
}
}List location booking profiles
List the seller's location booking profiles.
Inputs
- Limit
limitnumber - The maximum number of results to return in a paged response.
- Cursor
cursortext - The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"cursor": "example",
"errors": [],
"location_booking_profiles": []
}
}List locations
List all of the seller's locations, including inactive ones, in alphabetical order by name.
Inputs
None.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the [ListLocations](api-endpoint:Locations-ListLocations) endpoint. Either `errors` or `locations` is present in a given response (never both).
Example output
{
"data": {
"errors": [],
"locations": []
}
}List team member booking profiles
List the booking profiles of team members, optionally only bookable ones or those at one location.
Inputs
- Bookable only
bookable_onlytrue/false - Indicates whether to include only bookable team members in the returned result (true) or not (false).
- Limit
limitnumber - The maximum number of results to return in a paged response.
- Cursor
cursortext - The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.
- Location
location_idtext - Indicates whether to include only team members enabled at the given location in the returned result.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"cursor": "example",
"errors": [],
"team_member_booking_profiles": []
}
}Search availability
Search for times that are free to book.
Inputs
- Query filter
query_filterobjectRequired - The query filter to search for buyer-accessible availabilities of existing bookings.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"availabilities": [],
"errors": []
}
}Search customers
Search customer profiles with one or more filters. With no filters it returns every profile, sorted by first and last name. New or changed profiles usually show up within 30 seconds, but can occasionally take a minute or more.
Inputs
- Cursor
cursortext - Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. For more information, see Pagination.
- Limit
limitnumber - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100. For more information, see Pagination.From 1 to 100.
- Query
search_queryobject - The filtering and sorting criteria for the search request. If a query is not specified, Square returns all customer profiles ordered alphabetically by given_name and family_name.
- Count
counttrue/false - Indicates whether to return the total count of matching customers in the count field of the response. The default value is false.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the `SearchCustomers` endpoint. Either `errors` or `customers` is present in a given response (never both).
Example output
{
"data": {
"count": 1,
"cursor": "example",
"customers": [],
"errors": []
}
}Update booking
Update a booking. The seller must subscribe to Square Appointments Plus or Premium.
Inputs
- Booking ID
booking_idtextRequired - The ID of the Booking object representing the to-be-updated booking.
- Idempotency key
idempotency_keytext - A unique key to make this request an idempotent operation.
- Booking version
booking_versionnumberRequired - The revision number for the booking used for optimistic concurrency.
- Booking start at
booking_start_atdate and time - The RFC 3339 timestamp specifying the starting time of this booking.
- Booking location ID
booking_location_idtext - The ID of the Location object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed.
- Booking customer ID
booking_customer_idtext - The ID of the Customer object representing the customer receiving the booked service.
- Booking customer note
booking_customer_notetext - The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant CatalogObject instance.
- Booking seller note
booking_seller_notetext - The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific CatalogObject instance. This field should not be visible to customers.
- Booking appointment segments
booking_appointment_segmentslist - A list of appointment segments for this booking.
- Booking all day
booking_all_daytrue/false - Whether the booking is of a full business day.
- Booking location type
booking_location_typetext - The type of location where the booking is held. See [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype) for possible valuesOne of:
BUSINESS_LOCATION(Business location),CUSTOMER_LOCATION(Customer location),PHONE.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"booking": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"all_day": false,
"appointment_segments": [],
"created_at": "example",
"creator_details": {
"creator_type": "TEAM_MEMBER",
"customer_id": "example",
"team_member_id": "example"
},
"customer_id": "example",
"customer_note": "example",
"id": "example",
"location_id": "example",
"location_type": "BUSINESS_LOCATION",
"seller_note": "example",
"source": "FIRST_PARTY_MERCHANT",
"start_at": "example",
"status": "PENDING",
"transition_time_minutes": 1,
"updated_at": "example",
"version": 1
},
"errors": []
}
}Update customer
Update a customer profile; only the fields you fill in are changed. For a profile created by merging others, use the ID of the merged profile.
Inputs
- Customer ID
customer_idtextRequired - The ID of the customer to update.
- Given name
given_nametext - The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters.
- Family name
family_nametext - The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters.
- Company name
company_nametext - A business name associated with the customer profile. The maximum length for this value is 500 characters.
- Nickname
nicknametext - A nickname for the customer profile. The maximum length for this value is 100 characters.
- Email address
email_addresstext - The email address associated with the customer profile. The maximum length for this value is 254 characters.
- Address
addressobject - The physical address associated with the customer profile. Only new or changed fields are required in the request. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.
- Phone number
phone_numbertext - The phone number associated with the customer profile. The phone number must be valid and can contain 9-16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.
- Reference ID
reference_idtext - An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters.
- Note
notetext - A custom note associated with the customer profile.
- Birthday
birthdaydate - The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.
- Version
versionnumber - The current version of the customer profile. As a best practice, you should include this field to enable optimistic concurrency control. For more information, see Update a customer profile.
- Tax IDs
tax_idsobject - The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see Customer tax IDs.
Outputs
dataobject- Defines the fields that are included in the response body of a request to the [UpdateCustomer](api-endpoint:Customers-UpdateCustomer) or [BulkUpdateCustomers](api-endpoint:Customers-BulkUpdateCustomers) endpoint. Either `errors` or `customer` is present in a given response (never both).
Example output
{
"data": {
"customer": {
"address": {
"address_line_1": "example",
"address_line_2": "example",
"address_line_3": "example",
"administrative_district_level_1": "example",
"administrative_district_level_2": "example",
"administrative_district_level_3": "example",
"country": "ZZ",
"first_name": "example",
"last_name": "example",
"locality": "example",
"postal_code": "example",
"sublocality": "example",
"sublocality_2": "example",
"sublocality_3": "example"
},
"birthday": "example",
"company_name": "example",
"created_at": "example",
"creation_source": "OTHER",
"email_address": "example",
"family_name": "example",
"given_name": "example",
"group_ids": [],
"id": "example",
"nickname": "example",
"note": "example",
"phone_number": "example",
"preferences": {
"email_unsubscribed": false
},
"reference_id": "example",
"segment_ids": [],
"tax_ids": {
"eu_vat": "example"
},
"updated_at": "example",
"version": 1
},
"errors": []
}
}