# Square Appointments

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

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/square-appointments

## Actions

### Cancel booking

Cancel a booking. The seller must subscribe to Square Appointments Plus or Premium.

**Inputs**

- Booking ID (`booking_id`, text, required): The ID of the Booking object representing the to-be-cancelled booking.
- Idempotency key (`idempotency_key`, text): A unique key to make this request an idempotent operation.
- Booking version (`booking_version`, number): The revision number for the booking used for optimistic concurrency.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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_key`, text): A unique key to make this request an idempotent operation.
- Booking ID (`booking_id`, text): A unique ID of this object representing a booking.
- Booking version (`booking_version`, number): The revision number for the booking used for optimistic concurrency.
- Booking start at (`booking_start_at`, date and time, required): The RFC 3339 timestamp specifying the starting time of this booking.
- Booking location ID (`booking_location_id`, text, required): 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_id`, text, required): The ID of the Customer object representing the customer receiving the booked service.
- Booking customer note (`booking_customer_note`, text): 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_note`, text): 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_segments`, list, required): A list of appointment segments for this booking.
- Booking all day (`booking_all_day`, true/false): Whether the booking is of a full business day.
- Booking location type (`booking_location_type`, text): The type of location where the booking is held. See [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype) for possible values. One of: `BUSINESS_LOCATION` (Business location), `CUSTOMER_LOCATION` (Customer location), `PHONE`.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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_key`, text): The idempotency key for the request. For more information, see Idempotency.
- Given name (`given_name`, text): 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_name`, text): 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_name`, text): A business name associated with the customer profile. The maximum length for this value is 500 characters.
- Nickname (`nickname`, text): A nickname for the customer profile. The maximum length for this value is 100 characters.
- Email address (`email_address`, text): The email address associated with the customer profile. The maximum length for this value is 254 characters.
- Address (`address`, object): 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_number`, text): 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_id`, text): 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 (`note`, text): A custom note associated with the customer profile.
- Birthday (`birthday`, date): 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_ids`, object): 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**

- `data` (object): 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**

```json
{
  "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_id`, text, required): The ID of the customer to delete.
- Version (`version`, number): 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**

- `data` (object): Defines the fields that are included in the response body of a request to the `DeleteCustomer` endpoint.

**Example output**

```json
{
  "data": {
    "errors": []
  }
}
```

### Get booking

Get one booking by its ID.

**Inputs**

- Booking ID (`booking_id`, text, required): The ID of the Booking object representing the to-be-retrieved booking.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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**

- `data` (object): Returned value.

**Example output**

```json
{
  "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_id`, text, required): The object ID of any type of catalog objects to be retrieved.
- Include related objects (`include_related_objects`, true/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_version`, number): 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_root`, true/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**

- `data` (object): Returned value.

**Example output**

```json
{
  "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_id`, text, required): The ID of the customer to retrieve.

**Outputs**

- `data` (object): 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**

```json
{
  "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_id`, text, required): The ID of the location to retrieve. Specify the string "main" to return the main location.

**Outputs**

- `data` (object): Defines the fields that the [RetrieveLocation](api-endpoint:Locations-RetrieveLocation) endpoint returns in a response.

**Example output**

```json
{
  "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_id`, text, required): The ID of the team member to retrieve.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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 (`limit`, number): The maximum number of results per page to return in a paged response.
- Cursor (`cursor`, text): 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_id`, text): The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.
- Team member ID (`team_member_id`, text): The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.
- Location (`location_id`, text): The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.
- Start at min (`start_at_min`, date 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_max`, date 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**

- `data` (object): Returned value.

**Example output**

```json
{
  "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 (`cursor`, text): 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 (`types`, text): 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_version`, number): 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**

- `data` (object): Returned value.

**Example output**

```json
{
  "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 (`cursor`, text): 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 (`limit`, number): 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_field`, text): Indicates how customers should be sorted. The default value is DEFAULT. One of: `DEFAULT`, `CREATED_AT` (Created at).
- Sort order (`sort_order`, text): Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order. The default value is ASC. One of: `DESC`, `ASC`.
- Count (`count`, true/false): Indicates whether to return the total count of customers in the count field of the response. The default value is false.

**Outputs**

- `data` (object): 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**

```json
{
  "data": {
    "count": 1,
    "cursor": "example",
    "customers": [],
    "errors": []
  }
}
```

### List location booking profiles

List the seller's location booking profiles.

**Inputs**

- Limit (`limit`, number): The maximum number of results to return in a paged response.
- Cursor (`cursor`, text): 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**

- `data` (object): Returned value.

**Example output**

```json
{
  "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**

- `data` (object): 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**

```json
{
  "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_only`, true/false): Indicates whether to include only bookable team members in the returned result (true) or not (false).
- Limit (`limit`, number): The maximum number of results to return in a paged response.
- Cursor (`cursor`, text): 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_id`, text): Indicates whether to include only team members enabled at the given location in the returned result.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "cursor": "example",
    "errors": [],
    "team_member_booking_profiles": []
  }
}
```

### Search availability

Search for times that are free to book.

**Inputs**

- Query filter (`query_filter`, object, required): The query filter to search for buyer-accessible availabilities of existing bookings.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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 (`cursor`, text): 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 (`limit`, number): 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_query`, object): 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 (`count`, true/false): Indicates whether to return the total count of matching customers in the count field of the response. The default value is false.

**Outputs**

- `data` (object): 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**

```json
{
  "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_id`, text, required): The ID of the Booking object representing the to-be-updated booking.
- Idempotency key (`idempotency_key`, text): A unique key to make this request an idempotent operation.
- Booking version (`booking_version`, number, required): The revision number for the booking used for optimistic concurrency.
- Booking start at (`booking_start_at`, date and time): The RFC 3339 timestamp specifying the starting time of this booking.
- Booking location ID (`booking_location_id`, text): 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_id`, text): The ID of the Customer object representing the customer receiving the booked service.
- Booking customer note (`booking_customer_note`, text): 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_note`, text): 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_segments`, list): A list of appointment segments for this booking.
- Booking all day (`booking_all_day`, true/false): Whether the booking is of a full business day.
- Booking location type (`booking_location_type`, text): The type of location where the booking is held. See [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype) for possible values. One of: `BUSINESS_LOCATION` (Business location), `CUSTOMER_LOCATION` (Customer location), `PHONE`.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "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_id`, text, required): The ID of the customer to update.
- Given name (`given_name`, text): 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_name`, text): 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_name`, text): A business name associated with the customer profile. The maximum length for this value is 500 characters.
- Nickname (`nickname`, text): A nickname for the customer profile. The maximum length for this value is 100 characters.
- Email address (`email_address`, text): The email address associated with the customer profile. The maximum length for this value is 254 characters.
- Address (`address`, object): 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_number`, text): 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_id`, text): 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 (`note`, text): A custom note associated with the customer profile.
- Birthday (`birthday`, date): 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 (`version`, number): 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_ids`, object): 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**

- `data` (object): 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**

```json
{
  "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": []
  }
}
```
