Skip to main content
Server path: /square-bookings | Type: Application | PCID required: Yes

Tools

ToolDescription
square_bookings_bulk_delete_booking_custom_attributesBulkDeleteBookingCustomAttributes
square_bookings_bulk_retrieve_bookingsBulkRetrieveBookings
square_bookings_bulk_retrieve_team_member_booking_profilesBulkRetrieveTeamMemberBookingProfiles
square_bookings_bulk_swap_planBulkSwapPlan
square_bookings_bulk_upsert_booking_custom_attributesBulkUpsertBookingCustomAttributes
square_bookings_cancel_bookingCancelBooking
square_bookings_cancel_invoiceCancelInvoice
square_bookings_cancel_subscriptionCancelSubscription
square_bookings_change_billing_anchor_dateChangeBillingAnchorDate
square_bookings_create_bookingCreateBooking
square_bookings_create_booking_custom_attribute_definitionCreateBookingCustomAttributeDefinition
square_bookings_create_invoiceCreateInvoice
square_bookings_create_invoice_attachmentCreateInvoiceAttachment
square_bookings_create_subscriptionCreateSubscription
square_bookings_delete_booking_custom_attributeDeleteBookingCustomAttribute
square_bookings_delete_booking_custom_attribute_definitionDeleteBookingCustomAttributeDefinition
square_bookings_delete_invoiceDeleteInvoice
square_bookings_delete_invoice_attachmentDeleteInvoiceAttachment
square_bookings_delete_subscription_actionDeleteSubscriptionAction
square_bookings_get_invoiceGetInvoice
square_bookings_list_booking_custom_attribute_definitionsListBookingCustomAttributeDefinitions
square_bookings_list_booking_custom_attributesListBookingCustomAttributes
square_bookings_list_bookingsListBookings
square_bookings_list_invoicesListInvoices
square_bookings_list_location_booking_profilesListLocationBookingProfiles
square_bookings_list_subscription_eventsListSubscriptionEvents
square_bookings_list_team_member_booking_profilesListTeamMemberBookingProfiles
square_bookings_pause_subscriptionPauseSubscription
square_bookings_publish_invoicePublishInvoice
square_bookings_resume_subscriptionResumeSubscription
square_bookings_retrieve_bookingRetrieveBooking
square_bookings_retrieve_booking_custom_attributeRetrieveBookingCustomAttribute
square_bookings_retrieve_booking_custom_attribute_definitionRetrieveBookingCustomAttributeDefinition
square_bookings_retrieve_business_booking_profileRetrieveBusinessBookingProfile
square_bookings_retrieve_location_booking_profileRetrieveLocationBookingProfile
square_bookings_retrieve_subscriptionRetrieveSubscription
square_bookings_retrieve_team_member_booking_profileRetrieveTeamMemberBookingProfile
square_bookings_search_availabilitySearchAvailability
square_bookings_search_invoicesSearchInvoices
square_bookings_search_subscriptionsSearchSubscriptions
square_bookings_swap_planSwapPlan
square_bookings_update_bookingUpdateBooking
square_bookings_update_booking_custom_attribute_definitionUpdateBookingCustomAttributeDefinition
square_bookings_update_invoiceUpdateInvoice
square_bookings_update_subscriptionUpdateSubscription
square_bookings_upsert_booking_custom_attributeUpsertBookingCustomAttribute

square_bookings_bulk_delete_booking_custom_attributes

BulkDeleteBookingCustomAttributes Parameters:
ParameterTypeRequiredDefaultDescription
valuesobjectYesA map containing 1 to 25 individual Delete requests. For each request, provide an arbitrary ID that is unique for this BulkDeleteBookingCustomAttributes request and the information needed to delete a custom attribute.

square_bookings_bulk_retrieve_bookings

BulkRetrieveBookings Parameters:
ParameterTypeRequiredDefaultDescription
booking_idsstring[]YesA non-empty list of Booking IDs specifying bookings to retrieve.

square_bookings_bulk_retrieve_team_member_booking_profiles

BulkRetrieveTeamMemberBookingProfiles Parameters:
ParameterTypeRequiredDefaultDescription
team_member_idsstring[]YesA non-empty list of IDs of team members whose booking profiles you want to retrieve.

square_bookings_bulk_swap_plan

BulkSwapPlan Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYesThe ID of the location to associate with the swapped subscriptions.
new_plan_variation_idstringYesThe ID of the new subscription plan variation. This field is required.
old_plan_variation_idstringYesThe ID of the plan variation whose subscriptions should be swapped. Active subscriptions using this plan variation will be subscribed to the new plan variation on their next billing day.

square_bookings_bulk_upsert_booking_custom_attributes

BulkUpsertBookingCustomAttributes Parameters:
ParameterTypeRequiredDefaultDescription
valuesobjectYesA map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertBookingCustomAttributes request and the information needed to create or update a custom attribute.

square_bookings_cancel_booking

CancelBooking Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the Booking object representing the to-be-cancelled booking.
booking_versionintegerNoThe revision number for the booking used for optimistic concurrency.
idempotency_keystringNoA unique key to make this request an idempotent operation.

square_bookings_cancel_invoice

CancelInvoice Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to cancel.
versionintegerYesThe version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices.

square_bookings_cancel_subscription

CancelSubscription Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to cancel.

square_bookings_change_billing_anchor_date

ChangeBillingAnchorDate Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to update the billing anchor date.
effective_datestringNoThe YYYY-MM-DD-formatted date when the scheduled BILLING_ANCHOR_CHANGE action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the billing anchor date is changed immediately.
monthly_billing_anchor_dateintegerNoThe anchor day for the billing cycle.

square_bookings_create_booking

CreateBooking Parameters:
ParameterTypeRequiredDefaultDescription
bookingobjectYesRepresents a booking as a time-bound service contract for a seller’s staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments.
idempotency_keystringNoA unique key to make this request an idempotent operation.

square_bookings_create_booking_custom_attribute_definition

CreateBookingCustomAttributeDefinition Parameters:
ParameterTypeRequiredDefaultDescription
custom_attribute_definitionobjectYesRepresents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.
idempotency_keystringNoA unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

square_bookings_create_invoice

CreateInvoice Parameters:
ParameterTypeRequiredDefaultDescription
idempotency_keystringNoA unique string that identifies the CreateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
invoiceobjectYesStores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Invoices API Overview.

square_bookings_create_invoice_attachment

CreateInvoiceAttachment Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to attach the file to.
image_filestringNoImage File
requestobjectNoRepresents a CreateInvoiceAttachment request.

square_bookings_create_subscription

CreateSubscription Parameters:
ParameterTypeRequiredDefaultDescription
canceled_datestringNoThe YYYY-MM-DD-formatted date when the newly created subscription is scheduled for cancellation. This date overrides the cancellation date set in the plan variation configuration. If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle. When the subscription plan of the newly created subscription has a fixed number of cycles and the canceled_date occurs before the subscription plan completes, the specified canceled_date sets the date when the subscription stops through the end of the last cycle.
card_idstringNoThe ID of the subscriber’s card to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription.
customer_idstringYesThe ID of the customer subscribing to the subscription plan variation.
idempotency_keystringNoA unique string that identifies this CreateSubscription request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency keys.
location_idstringYesThe ID of the location the subscription is associated with.
monthly_billing_anchor_dateintegerNoThe day-of-the-month to change the billing date to.
phasesobject[]Noarray of phases for this subscription
plan_variation_idstringNoThe ID of the subscription plan variation created using the Catalog API.
price_override_moneyobjectNoRepresents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
sourceobjectNoThe origination details of the subscription.
start_datestringNoThe YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately.
tax_percentagestringNoThe tax to add when billing the subscription. The percentage is expressed in decimal form, using a '.' as the decimal separator and without a '%' sign. For example, a value of 7.5 corresponds to 7.5%.
timezonestringNoThe timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to “America/New_York”. Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see List of tz database time zones.

square_bookings_delete_booking_custom_attribute

DeleteBookingCustomAttribute Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the target booking.
keystringYesThe key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

square_bookings_delete_booking_custom_attribute_definition

DeleteBookingCustomAttributeDefinition Parameters:
ParameterTypeRequiredDefaultDescription
keystringYesThe key of the custom attribute definition to delete.

square_bookings_delete_invoice

DeleteInvoice Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to delete.
versionintegerNoThe version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.

square_bookings_delete_invoice_attachment

DeleteInvoiceAttachment Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to delete the attachment from.
attachment_idstringYesThe ID of the attachment to delete.

square_bookings_delete_subscription_action

DeleteSubscriptionAction Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription the targeted action is to act upon.
action_idstringYesThe ID of the targeted action to be deleted.

square_bookings_get_invoice

GetInvoice Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to retrieve.

square_bookings_list_booking_custom_attribute_definitions

ListBookingCustomAttributeDefinitions Parameters:
ParameterTypeRequiredDefaultDescription
limitintegerNoThe maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursorstringNoThe cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

square_bookings_list_booking_custom_attributes

ListBookingCustomAttributes Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the target booking.
limitintegerNoThe maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.
cursorstringNoThe cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.
with_definitionsbooleanNoIndicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

square_bookings_list_bookings

ListBookings Parameters:
ParameterTypeRequiredDefaultDescription
limitintegerNoThe maximum number of results per page to return in a paged response.
cursorstringNoThe 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_idstringNoThe customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.
team_member_idstringNoThe team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.
location_idstringNoThe location for which to retrieve bookings. If this is not set, all locations’ bookings are retrieved.
start_at_minstringNoThe RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.
start_at_maxstringNoThe 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.

square_bookings_list_invoices

ListInvoices Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYesThe ID of the location for which to list invoices.
cursorstringNoA 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.
limitintegerNoThe maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices.

square_bookings_list_location_booking_profiles

ListLocationBookingProfiles Parameters:
ParameterTypeRequiredDefaultDescription
limitintegerNoThe maximum number of results to return in a paged response.
cursorstringNoThe 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.

square_bookings_list_subscription_events

ListSubscriptionEvents Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to retrieve the events for.
cursorstringNoWhen the total number of resulting subscription events exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results. For more information, see Pagination.
limitintegerNoThe upper limit on the number of subscription events to return in a paged response.

square_bookings_list_team_member_booking_profiles

ListTeamMemberBookingProfiles Parameters:
ParameterTypeRequiredDefaultDescription
bookable_onlybooleanNoIndicates whether to include only bookable team members in the returned result (true) or not (false).
limitintegerNoThe maximum number of results to return in a paged response.
cursorstringNoThe 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_idstringNoIndicates whether to include only team members enabled at the given location in the returned result.

square_bookings_pause_subscription

PauseSubscription Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to pause.
pause_cycle_durationintegerNoThe number of billing cycles the subscription will be paused before it is reactivated. When this is set, a RESUME action is also scheduled to take place on the subscription at the end of the specified pause cycle duration. In this case, neither resume_effective_date nor resume_change_timing may be specified.
pause_effective_datestringNoThe YYYY-MM-DD-formatted date when the scheduled PAUSE action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the subscription is paused on the starting date of the next billing cycle.
pause_reasonstringNoThe user-provided reason to pause the subscription.
resume_change_timingstringNoSupported timings when a pending change, as an action, takes place to a subscription.
resume_effective_datestringNoThe date when the subscription is reactivated by a scheduled RESUME action. This date must be at least one billing cycle ahead of pause_effective_date.

square_bookings_publish_invoice

PublishInvoice Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to publish.
idempotency_keystringNoA unique string that identifies the PublishInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
versionintegerYesThe version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected.

square_bookings_resume_subscription

ResumeSubscription Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to resume.
resume_change_timingstringNoSupported timings when a pending change, as an action, takes place to a subscription.
resume_effective_datestringNoThe YYYY-MM-DD-formatted date when the subscription reactivated.

square_bookings_retrieve_booking

RetrieveBooking Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the Booking object representing the to-be-retrieved booking.

square_bookings_retrieve_booking_custom_attribute

RetrieveBookingCustomAttribute Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the target booking.
keystringYesThe key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
with_definitionbooleanNoIndicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.
versionintegerNoThe current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

square_bookings_retrieve_booking_custom_attribute_definition

RetrieveBookingCustomAttributeDefinition Parameters:
ParameterTypeRequiredDefaultDescription
keystringYesThe key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.
versionintegerNoThe current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

square_bookings_retrieve_business_booking_profile

RetrieveBusinessBookingProfile

square_bookings_retrieve_location_booking_profile

RetrieveLocationBookingProfile Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYesThe ID of the location to retrieve the booking profile.

square_bookings_retrieve_subscription

RetrieveSubscription Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to retrieve.
includestringNoA query parameter to specify related information to be included in the response. The supported query parameter values are: - actions: to include scheduled actions on the targeted subscription.

square_bookings_retrieve_team_member_booking_profile

RetrieveTeamMemberBookingProfile Parameters:
ParameterTypeRequiredDefaultDescription
team_member_idstringYesThe ID of the team member to retrieve.

square_bookings_search_availability

SearchAvailability Parameters:
ParameterTypeRequiredDefaultDescription
queryobjectYesThe query used to search for buyer-accessible availabilities of bookings.

square_bookings_search_invoices

SearchInvoices Parameters:
ParameterTypeRequiredDefaultDescription
cursorstringNoA 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.
limitintegerNoThe maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices.
queryobjectYesDescribes query criteria for searching invoices.

square_bookings_search_subscriptions

SearchSubscriptions Parameters:
ParameterTypeRequiredDefaultDescription
cursorstringNoWhen the total number of resulting subscriptions exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results. For more information, see Pagination.
includestring[]NoAn option to include related information in the response. The supported values are: - actions: to include scheduled actions on the targeted subscriptions.
limitintegerNoThe upper limit on the number of subscriptions to return in a paged response.
queryobjectNoRepresents a query, consisting of specified query expressions, used to search for subscriptions.

square_bookings_swap_plan

SwapPlan Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to swap the subscription plan for.
new_plan_variation_idstringYesThe ID of the new subscription plan variation. This field is required.
phasesobject[]NoA list of PhaseInputs, to pass phase-specific information used in the swap.

square_bookings_update_booking

UpdateBooking Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the Booking object representing the to-be-updated booking.
bookingobjectYesRepresents a booking as a time-bound service contract for a seller’s staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments.
idempotency_keystringNoA unique key to make this request an idempotent operation.

square_bookings_update_booking_custom_attribute_definition

UpdateBookingCustomAttributeDefinition Parameters:
ParameterTypeRequiredDefaultDescription
keystringYesThe key of the custom attribute definition to update.
custom_attribute_definitionobjectYesRepresents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.
idempotency_keystringNoA unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

square_bookings_update_invoice

UpdateInvoice Parameters:
ParameterTypeRequiredDefaultDescription
invoice_idstringYesThe ID of the invoice to update.
fields_to_clearstring[]NoThe list of fields to clear. Although this field is currently supported, we recommend using null values or the remove field when possible. For examples, see Update an Invoice.
idempotency_keystringNoA unique string that identifies the UpdateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
invoiceobjectYesStores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Invoices API Overview.

square_bookings_update_subscription

UpdateSubscription Parameters:
ParameterTypeRequiredDefaultDescription
subscription_idstringYesThe ID of the subscription to update.
subscriptionobjectNoRepresents a subscription purchased by a customer. For more information, see Manage Subscriptions.

square_bookings_upsert_booking_custom_attribute

UpsertBookingCustomAttribute Parameters:
ParameterTypeRequiredDefaultDescription
booking_idstringYesThe ID of the target booking.
keystringYesThe key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.
custom_attributeobjectYesA custom attribute value. Each custom attribute value has a corresponding CustomAttributeDefinition object.
idempotency_keystringNoA unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.