Square Appointments

App · 20 actions

Manage bookings, availability, customers, locations and bookable team members.

Actions

ActionWhat it does
Cancel bookingCancel a booking.
Create bookingCreate a booking.
Create customerCreate a customer profile.
Delete customerDelete a customer profile.
Get bookingGet one booking by its ID.
Get business booking profileGet the seller's booking profile.
Get catalog objectGet one catalog item by its ID, with its variations, its modifier lists and the taxes that apply to it.
Get customerGet the details of one customer.
Get locationGet the details of one location.
Get team member booking profileGet one team member's booking profile.
List bookingsList bookings, optionally for one customer, team member or location, or within a range of start times.
List catalogList the catalog objects of the types you choose, such as items, item variations, modifiers, categories, discounts, taxes and images.
List customersList the customer profiles in the Square account.
List location booking profilesList the seller's location booking profiles.
List locationsList all of the seller's locations, including inactive ones, in alphabetical order by name.
List team member booking profilesList the booking profiles of team members, optionally only bookable ones or those at one location.
Search availabilitySearch for times that are free to book.
Search customersSearch customer profiles with one or more filters.
Update bookingUpdate a booking.
Update customerUpdate 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 IDbooking_idtextRequired
The ID of the Booking object representing the to-be-cancelled booking.
Idempotency keyidempotency_keytext
A unique key to make this request an idempotent operation.
Booking versionbooking_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 keyidempotency_keytext
A unique key to make this request an idempotent operation.
Booking IDbooking_idtext
A unique ID of this object representing a booking.
Booking versionbooking_versionnumber
The revision number for the booking used for optimistic concurrency.
Booking start atbooking_start_atdate and timeRequired
The RFC 3339 timestamp specifying the starting time of this booking.
Booking location IDbooking_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 IDbooking_customer_idtextRequired
The ID of the Customer object representing the customer receiving the booked service.
Booking customer notebooking_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 notebooking_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 segmentsbooking_appointment_segmentslistRequired
A list of appointment segments for this booking.
Booking all daybooking_all_daytrue/false
Whether the booking is of a full business day.
Booking location typebooking_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 keyidempotency_keytext
The idempotency key for the request. For more information, see Idempotency.
Given namegiven_nametext
The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters.
Family namefamily_nametext
The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters.
Company namecompany_nametext
A business name associated with the customer profile. The maximum length for this value is 500 characters.
Nicknamenicknametext
A nickname for the customer profile. The maximum length for this value is 100 characters.
Email addressemail_addresstext
The email address associated with the customer profile. The maximum length for this value is 254 characters.
Addressaddressobject
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 numberphone_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 IDreference_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.
Notenotetext
A custom note associated with the customer profile.
Birthdaybirthdaydate
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 IDstax_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 IDcustomer_idtextRequired
The ID of the customer to delete.
Versionversionnumber
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 IDbooking_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 IDobject_idtextRequired
The object ID of any type of catalog objects to be retrieved.
Include related objectsinclude_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 versioncatalog_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 rootinclude_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 IDcustomer_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

Locationlocation_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 IDteam_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

Limitlimitnumber
The maximum number of results per page to return in a paged response.
Cursorcursortext
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 IDcustomer_idtext
The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.
Team member IDteam_member_idtext
The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.
Locationlocation_idtext
The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.
Start at minstart_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 maxstart_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

Cursorcursortext
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.
Typestypestext
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 versioncatalog_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

Cursorcursortext
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.
Limitlimitnumber
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 fieldsort_fieldtext
Indicates how customers should be sorted. The default value is DEFAULT.One of: DEFAULT, CREATED_AT (Created at).
Sort ordersort_ordertext
Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order. The default value is ASC.One of: DESC, ASC.
Countcounttrue/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

Limitlimitnumber
The maximum number of results to return in a paged response.
Cursorcursortext
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 onlybookable_onlytrue/false
Indicates whether to include only bookable team members in the returned result (true) or not (false).
Limitlimitnumber
The maximum number of results to return in a paged response.
Cursorcursortext
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.
Locationlocation_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 filterquery_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

Cursorcursortext
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.
Limitlimitnumber
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.
Querysearch_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.
Countcounttrue/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 IDbooking_idtextRequired
The ID of the Booking object representing the to-be-updated booking.
Idempotency keyidempotency_keytext
A unique key to make this request an idempotent operation.
Booking versionbooking_versionnumberRequired
The revision number for the booking used for optimistic concurrency.
Booking start atbooking_start_atdate and time
The RFC 3339 timestamp specifying the starting time of this booking.
Booking location IDbooking_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 IDbooking_customer_idtext
The ID of the Customer object representing the customer receiving the booked service.
Booking customer notebooking_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 notebooking_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 segmentsbooking_appointment_segmentslist
A list of appointment segments for this booking.
Booking all daybooking_all_daytrue/false
Whether the booking is of a full business day.
Booking location typebooking_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 IDcustomer_idtextRequired
The ID of the customer to update.
Given namegiven_nametext
The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters.
Family namefamily_nametext
The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters.
Company namecompany_nametext
A business name associated with the customer profile. The maximum length for this value is 500 characters.
Nicknamenicknametext
A nickname for the customer profile. The maximum length for this value is 100 characters.
Email addressemail_addresstext
The email address associated with the customer profile. The maximum length for this value is 254 characters.
Addressaddressobject
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 numberphone_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 IDreference_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.
Notenotetext
A custom note associated with the customer profile.
Birthdaybirthdaydate
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.
Versionversionnumber
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 IDstax_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": []
  }
}

On this page