> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# square-bookings
> Square Bookings & Invoices
**Server path:** `/square-bookings` | **Type:** Application | **PCID required:** Yes
## Tools
| Tool | Description |
| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [`square_bookings_bulk_delete_booking_custom_attributes`](#square_bookings_bulk_delete_booking_custom_attributes) | BulkDeleteBookingCustomAttributes |
| [`square_bookings_bulk_retrieve_bookings`](#square_bookings_bulk_retrieve_bookings) | BulkRetrieveBookings |
| [`square_bookings_bulk_retrieve_team_member_booking_profiles`](#square_bookings_bulk_retrieve_team_member_booking_profiles) | BulkRetrieveTeamMemberBookingProfiles |
| [`square_bookings_bulk_swap_plan`](#square_bookings_bulk_swap_plan) | BulkSwapPlan |
| [`square_bookings_bulk_upsert_booking_custom_attributes`](#square_bookings_bulk_upsert_booking_custom_attributes) | BulkUpsertBookingCustomAttributes |
| [`square_bookings_cancel_booking`](#square_bookings_cancel_booking) | CancelBooking |
| [`square_bookings_cancel_invoice`](#square_bookings_cancel_invoice) | CancelInvoice |
| [`square_bookings_cancel_subscription`](#square_bookings_cancel_subscription) | CancelSubscription |
| [`square_bookings_change_billing_anchor_date`](#square_bookings_change_billing_anchor_date) | ChangeBillingAnchorDate |
| [`square_bookings_create_booking`](#square_bookings_create_booking) | CreateBooking |
| [`square_bookings_create_booking_custom_attribute_definition`](#square_bookings_create_booking_custom_attribute_definition) | CreateBookingCustomAttributeDefinition |
| [`square_bookings_create_invoice`](#square_bookings_create_invoice) | CreateInvoice |
| [`square_bookings_create_invoice_attachment`](#square_bookings_create_invoice_attachment) | CreateInvoiceAttachment |
| [`square_bookings_create_subscription`](#square_bookings_create_subscription) | CreateSubscription |
| [`square_bookings_delete_booking_custom_attribute`](#square_bookings_delete_booking_custom_attribute) | DeleteBookingCustomAttribute |
| [`square_bookings_delete_booking_custom_attribute_definition`](#square_bookings_delete_booking_custom_attribute_definition) | DeleteBookingCustomAttributeDefinition |
| [`square_bookings_delete_invoice`](#square_bookings_delete_invoice) | DeleteInvoice |
| [`square_bookings_delete_invoice_attachment`](#square_bookings_delete_invoice_attachment) | DeleteInvoiceAttachment |
| [`square_bookings_delete_subscription_action`](#square_bookings_delete_subscription_action) | DeleteSubscriptionAction |
| [`square_bookings_get_invoice`](#square_bookings_get_invoice) | GetInvoice |
| [`square_bookings_list_booking_custom_attribute_definitions`](#square_bookings_list_booking_custom_attribute_definitions) | ListBookingCustomAttributeDefinitions |
| [`square_bookings_list_booking_custom_attributes`](#square_bookings_list_booking_custom_attributes) | ListBookingCustomAttributes |
| [`square_bookings_list_bookings`](#square_bookings_list_bookings) | ListBookings |
| [`square_bookings_list_invoices`](#square_bookings_list_invoices) | ListInvoices |
| [`square_bookings_list_location_booking_profiles`](#square_bookings_list_location_booking_profiles) | ListLocationBookingProfiles |
| [`square_bookings_list_subscription_events`](#square_bookings_list_subscription_events) | ListSubscriptionEvents |
| [`square_bookings_list_team_member_booking_profiles`](#square_bookings_list_team_member_booking_profiles) | ListTeamMemberBookingProfiles |
| [`square_bookings_pause_subscription`](#square_bookings_pause_subscription) | PauseSubscription |
| [`square_bookings_publish_invoice`](#square_bookings_publish_invoice) | PublishInvoice |
| [`square_bookings_resume_subscription`](#square_bookings_resume_subscription) | ResumeSubscription |
| [`square_bookings_retrieve_booking`](#square_bookings_retrieve_booking) | RetrieveBooking |
| [`square_bookings_retrieve_booking_custom_attribute`](#square_bookings_retrieve_booking_custom_attribute) | RetrieveBookingCustomAttribute |
| [`square_bookings_retrieve_booking_custom_attribute_definition`](#square_bookings_retrieve_booking_custom_attribute_definition) | RetrieveBookingCustomAttributeDefinition |
| [`square_bookings_retrieve_business_booking_profile`](#square_bookings_retrieve_business_booking_profile) | RetrieveBusinessBookingProfile |
| [`square_bookings_retrieve_location_booking_profile`](#square_bookings_retrieve_location_booking_profile) | RetrieveLocationBookingProfile |
| [`square_bookings_retrieve_subscription`](#square_bookings_retrieve_subscription) | RetrieveSubscription |
| [`square_bookings_retrieve_team_member_booking_profile`](#square_bookings_retrieve_team_member_booking_profile) | RetrieveTeamMemberBookingProfile |
| [`square_bookings_search_availability`](#square_bookings_search_availability) | SearchAvailability |
| [`square_bookings_search_invoices`](#square_bookings_search_invoices) | SearchInvoices |
| [`square_bookings_search_subscriptions`](#square_bookings_search_subscriptions) | SearchSubscriptions |
| [`square_bookings_swap_plan`](#square_bookings_swap_plan) | SwapPlan |
| [`square_bookings_update_booking`](#square_bookings_update_booking) | UpdateBooking |
| [`square_bookings_update_booking_custom_attribute_definition`](#square_bookings_update_booking_custom_attribute_definition) | UpdateBookingCustomAttributeDefinition |
| [`square_bookings_update_invoice`](#square_bookings_update_invoice) | UpdateInvoice |
| [`square_bookings_update_subscription`](#square_bookings_update_subscription) | UpdateSubscription |
| [`square_bookings_upsert_booking_custom_attribute`](#square_bookings_upsert_booking_custom_attribute) | UpsertBookingCustomAttribute |
***
## square\_bookings\_bulk\_delete\_booking\_custom\_attributes
BulkDeleteBookingCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `values` | object | Yes | — | A 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"values": {
"type": "object",
"description": "A 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."
}
},
"required": [
"PCID",
"values"
]
}
```
***
## square\_bookings\_bulk\_retrieve\_bookings
BulkRetrieveBookings
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | --------- | -------- | ------- | ---------------------------------------------------------------- |
| `booking_ids` | string\[] | Yes | — | A non-empty list of Booking IDs specifying bookings to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A non-empty list of [Booking](entity:Booking) IDs specifying bookings to retrieve."
}
},
"required": [
"PCID",
"booking_ids"
]
}
```
***
## square\_bookings\_bulk\_retrieve\_team\_member\_booking\_profiles
BulkRetrieveTeamMemberBookingProfiles
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `team_member_ids` | string\[] | Yes | — | A non-empty list of IDs of team members whose booking profiles you want to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"team_member_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A non-empty list of IDs of team members whose booking profiles you want to retrieve."
}
},
"required": [
"PCID",
"team_member_ids"
]
}
```
***
## square\_bookings\_bulk\_swap\_plan
BulkSwapPlan
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `location_id` | string | Yes | — | The ID of the location to associate with the swapped subscriptions. |
| `new_plan_variation_id` | string | Yes | — | The ID of the new subscription plan variation. This field is required. |
| `old_plan_variation_id` | string | Yes | — | The 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location to associate with the swapped subscriptions."
},
"new_plan_variation_id": {
"type": "string",
"description": "The ID of the new subscription plan variation. This field is required."
},
"old_plan_variation_id": {
"type": "string",
"description": "The 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."
}
},
"required": [
"PCID",
"location_id",
"new_plan_variation_id",
"old_plan_variation_id"
]
}
```
***
## square\_bookings\_bulk\_upsert\_booking\_custom\_attributes
BulkUpsertBookingCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `values` | object | Yes | — | A 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"values": {
"type": "object",
"description": "A 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."
}
},
"required": [
"PCID",
"values"
]
}
```
***
## square\_bookings\_cancel\_booking
CancelBooking
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | ------- | -------- | ------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the Booking object representing the to-be-cancelled booking. | |
| `booking_version` | integer | null | No | — | The revision number for the booking used for optimistic concurrency. |
| `idempotency_key` | string | null | No | — | A unique key to make this request an idempotent operation. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the [Booking](entity:Booking) object representing the to-be-cancelled booking."
},
"booking_version": {
"type": [
"integer",
"null"
],
"description": "The revision number for the booking used for optimistic concurrency."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique key to make this request an idempotent operation."
}
},
"required": [
"PCID",
"booking_id"
]
}
```
***
## square\_bookings\_cancel\_invoice
CancelInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to cancel. |
| `version` | integer | Yes | — | The version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the [invoice](entity:Invoice) to cancel."
},
"version": {
"type": "integer",
"description": "The version of the [invoice](entity:Invoice) to cancel. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices)."
}
},
"required": [
"PCID",
"invoice_id",
"version"
]
}
```
***
## square\_bookings\_cancel\_subscription
CancelSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to cancel. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to cancel."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_change\_billing\_anchor\_date
ChangeBillingAnchorDate
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------------- | ------- | -------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to update the billing anchor date. | |
| `effective_date` | string | null | No | — | The `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_date` | integer | null | No | — | The anchor day for the billing cycle. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to update the billing anchor date."
},
"effective_date": {
"type": [
"string",
"null"
],
"description": "The `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_date": {
"type": [
"integer",
"null"
],
"description": "The anchor day for the billing cycle."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_create\_booking
CreateBooking
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking` | object | Yes | — | Represents 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_key` | string | No | — | A unique key to make this request an idempotent operation. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking": {
"type": "object",
"description": "Represents 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.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID of this object representing a booking."
},
"version": {
"type": "integer",
"description": "The revision number for the booking used for optimistic concurrency."
},
"status": {
"type": "string",
"description": "Supported booking statuses.",
"enum": [
"PENDING",
"CANCELLED_BY_CUSTOMER",
"CANCELLED_BY_SELLER",
"DECLINED",
"ACCEPTED",
"NO_SHOW"
]
},
"created_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the creation time of this booking."
},
"updated_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the most recent update time of this booking."
},
"start_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the starting time of this booking."
},
"location_id": {
"type": "string",
"description": "The ID of the [Location](entity:Location) object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed."
},
"customer_id": {
"type": "string",
"description": "The ID of the [Customer](entity:Customer) object representing the customer receiving the booked service."
},
"customer_note": {
"type": "string",
"description": "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](entity:CatalogObject) instance."
},
"seller_note": {
"type": "string",
"description": "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](entity:CatalogObject) instance. This field should not be visible to customers."
},
"appointment_segments": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of appointment segments for this booking."
},
"transition_time_minutes": {
"type": "integer",
"description": "Additional time at the end of a booking. Applications should not make this field visible to customers of a seller."
},
"all_day": {
"type": "boolean",
"description": "Whether the booking is of a full business day."
},
"location_type": {
"type": "string",
"description": "Supported types of location where service is provided.",
"enum": [
"BUSINESS_LOCATION",
"CUSTOMER_LOCATION",
"PHONE"
]
},
"creator_details": {
"type": "object",
"description": "Information about a booking creator."
},
"source": {
"type": "string",
"description": "Supported sources a booking was created from.",
"enum": [
"FIRST_PARTY_MERCHANT",
"FIRST_PARTY_BUYER",
"THIRD_PARTY_BUYER",
"API"
]
},
"address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
}
}
},
"idempotency_key": {
"type": "string",
"description": "A unique key to make this request an idempotent operation."
}
},
"required": [
"PCID",
"booking"
]
}
```
***
## square\_bookings\_create\_booking\_custom\_attribute\_definition
CreateBookingCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `custom_attribute_definition` | object | Yes | — | Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. |
| `idempotency_key` | string | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"custom_attribute_definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-). This field can not be changed after the custom attribute definition is created. This field is required when creating a definition and must be unique per application, seller, and resource type."
},
"schema": {
"type": "object",
"description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition."
},
"name": {
"type": "string",
"description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must be unique within the seller and application pair. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"description": {
"type": "string",
"description": "Seller-oriented description of the custom attribute definition, including any constraints that the seller should observe. May be displayed as a tooltip in Square UIs. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute definition. The value is incremented each time the custom attribute definition is updated. When updating a custom attribute definition, you can provide this field and specify the current version of the custom attribute definition to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). On writes, this field must be set to the latest version. Stale writes are rejected. This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created or most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": "string",
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"custom_attribute_definition"
]
}
```
***
## square\_bookings\_create\_invoice
CreateInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `idempotency_key` | string | No | — | A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `invoice` | object | Yes | — | Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"idempotency_key": {
"type": "string",
"description": "A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"invoice": {
"type": "object",
"description": "Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the invoice."
},
"version": {
"type": "integer",
"description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice."
},
"location_id": {
"type": "string",
"description": "The ID of the location that this invoice is associated with. If specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order."
},
"order_id": {
"type": "string",
"description": "The ID of the [order](entity:Order) for which the invoice is created. This field is required when creating an invoice, and the order must be in the `OPEN` state. To view the line items and other information for the associated order, call the [RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID."
},
"primary_recipient": {
"type": "object",
"description": "Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice and that Square uses to deliver the invoice. When you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates the remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published. Square updates the customer ID in response to a merge operation, but does not update other fields."
},
"payment_requests": {
"type": "array",
"items": {
"type": "object"
},
"description": "The payment schedule for the invoice, represented by one or more payment requests that define payment settings, such as amount due and due date. An invoice supports the following payment request combinations: - One balance - One deposit with one balance - 2–12 installments - One deposit with 2–12 installments This field is required when creating an invoice. It must contain at least one payment request. All payment requests for the invoice must equal the total order amount. For more information, see [Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests). Adding `INSTALLMENT` payment requests to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)."
},
"delivery_method": {
"type": "string",
"description": "Indicates how Square delivers the [invoice](entity:Invoice) to the customer.",
"enum": [
"EMAIL",
"SHARE_MANUALLY",
"SMS"
]
},
"invoice_number": {
"type": "string",
"description": "A user-friendly invoice number that is displayed on the invoice. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and is padded with zeros making it 7 characters long (for example, 0000001 and 0000002)."
},
"title": {
"type": "string",
"description": "The title of the invoice, which is displayed on the invoice."
},
"description": {
"type": "string",
"description": "The description of the invoice, which is displayed on the invoice."
},
"scheduled_at": {
"type": "string",
"description": "The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings. If the field is not set, Square processes the invoice immediately after it is published."
},
"public_url": {
"type": "string",
"description": "A temporary link to the Square-hosted payment page where the customer can pay the invoice. If the link expires, customers can provide the email address or phone number associated with the invoice and request a new link directly from the expired payment page. This field is added after the invoice is published and reaches the scheduled date (if one is defined)."
},
"next_payment_amount_money": {
"type": "object",
"description": "Represents 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"status": {
"type": "string",
"description": "Indicates the status of an [invoice](entity:Invoice).",
"enum": [
"DRAFT",
"UNPAID",
"SCHEDULED",
"PARTIALLY_PAID",
"PAID",
"PARTIALLY_REFUNDED",
"REFUNDED",
"CANCELED",
"FAILED",
"PAYMENT_PENDING"
]
},
"timezone": {
"type": "string",
"description": "The time zone used to interpret calendar dates on the invoice, such as `due_date`. When an invoice is created, this field is set to the `timezone` specified for the seller location. The value cannot be changed. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\\_Angeles becomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z)."
},
"created_at": {
"type": "string",
"description": "The timestamp when the invoice was created, in RFC 3339 format."
},
"updated_at": {
"type": "string",
"description": "The timestamp when the invoice was last updated, in RFC 3339 format."
},
"accepted_payment_methods": {
"type": "object",
"description": "The payment methods that customers can use to pay an [invoice](entity:Invoice) on the Square-hosted invoice payment page."
},
"custom_fields": {
"type": "array",
"items": {
"type": "object"
},
"description": "Additional seller-defined fields that are displayed on the invoice. For more information, see [Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields). Adding custom fields to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). Max: 2 custom fields"
},
"subscription_id": {
"type": "string",
"description": "The ID of the [subscription](entity:Subscription) associated with the invoice. This field is present only on subscription billing invoices."
},
"sale_or_service_date": {
"type": "string",
"description": "The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format. This field can be used to specify a past or future date which is displayed on the invoice."
},
"payment_conditions": {
"type": "string",
"description": "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, see [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions). For countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests."
},
"store_payment_method_enabled": {
"type": "boolean",
"description": "Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a bank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the invoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`."
},
"attachments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Metadata about the attachments on the invoice. Invoice attachments are managed using the [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints."
},
"creator_team_member_id": {
"type": "string",
"description": "The ID of the [team member](entity:TeamMember) who created the invoice. This field is present only on invoices created in the Square Dashboard or Square Invoices app by a logged-in team member."
}
}
}
},
"required": [
"PCID",
"invoice"
]
}
```
***
## square\_bookings\_create\_invoice\_attachment
CreateInvoiceAttachment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | --------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to attach the file to. |
| `image_file` | string | No | — | Image File |
| `request` | object | No | — | Represents a CreateInvoiceAttachment request. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the [invoice](entity:Invoice) to attach the file to."
},
"image_file": {
"type": "string",
"description": "Image File"
},
"request": {
"type": "object",
"description": "Represents a [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) request.",
"properties": {
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies the `CreateInvoiceAttachment` request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"description": {
"type": "string",
"description": "The description of the attachment to display on the invoice."
}
}
}
},
"required": [
"PCID",
"invoice_id"
]
}
```
***
## square\_bookings\_create\_subscription
CreateSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canceled_date` | string | No | — | The `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_id` | string | No | — | The 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_id` | string | Yes | — | The ID of the customer subscribing to the subscription plan variation. |
| `idempotency_key` | string | No | — | A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `location_id` | string | Yes | — | The ID of the location the subscription is associated with. |
| `monthly_billing_anchor_date` | integer | No | — | The day-of-the-month to change the billing date to. |
| `phases` | object\[] | No | — | array of phases for this subscription |
| `plan_variation_id` | string | No | — | The ID of the [subscription plan variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations) created using the Catalog API. |
| `price_override_money` | object | No | — | Represents 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. |
| `source` | object | No | — | The origination details of the subscription. |
| `start_date` | string | No | — | The `YYYY-MM-DD`-formatted date to start the subscription. If it is unspecified, the subscription starts immediately. |
| `tax_percentage` | string | No | — | The 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%. |
| `timezone` | string | No | — | The 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"canceled_date": {
"type": "string",
"description": "The `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_id": {
"type": "string",
"description": "The ID of the [subscriber's](entity:Customer) [card](entity:Card) to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription."
},
"customer_id": {
"type": "string",
"description": "The ID of the [customer](entity:Customer) subscribing to the subscription plan variation."
},
"idempotency_key": {
"type": "string",
"description": "A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"location_id": {
"type": "string",
"description": "The ID of the location the subscription is associated with."
},
"monthly_billing_anchor_date": {
"type": "integer",
"description": "The day-of-the-month to change the billing date to."
},
"phases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "id of subscription phase"
},
"ordinal": {
"type": "integer",
"format": "int64",
"description": "index of phase in total subscription plan"
},
"order_template_id": {
"type": "string",
"description": "id of order to be used in billing"
},
"plan_phase_uid": {
"type": "string",
"description": "the uid from the plan's phase in catalog"
}
}
},
"description": "array of phases for this subscription"
},
"plan_variation_id": {
"type": "string",
"description": "The ID of the [subscription plan variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations) created using the Catalog API."
},
"price_override_money": {
"type": "object",
"description": "Represents 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.",
"properties": {
"amount": {
"type": "integer",
"description": "The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"enum": [
"UNKNOWN_CURRENCY",
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BOV",
"BRL",
"BSD",
"BTN",
"BWP",
"BYR",
"BZD",
"CAD",
"CDF",
"CHE",
"CHF",
"CHW",
"CLF",
"CLP",
"CNY",
"COP",
"COU",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"INR",
"IQD",
"IRR",
"ISK",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LTL",
"LVL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRO",
"MUR",
"MVR",
"MWK",
"MXN",
"MXV",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLL",
"SLE",
"SOS",
"SRD",
"SSP",
"STD",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"USN",
"USS",
"UYI",
"UYU",
"UZS",
"VEF",
"VND",
"VUV",
"WST",
"XAF",
"XAG",
"XAU",
"XBA",
"XBB",
"XBC",
"XBD",
"XCD",
"XDR",
"XOF",
"XPD",
"XPF",
"XPT",
"XTS",
"XXX",
"YER",
"ZAR",
"ZMK",
"ZMW",
"BTC",
"XUS"
]
}
}
},
"source": {
"type": "object",
"description": "The origination details of the subscription.",
"properties": {
"name": {
"type": "string",
"description": "The name used to identify the place (physical or digital) that a subscription originates. If unset, the name defaults to the name of the application that created the subscription."
}
}
},
"start_date": {
"type": "string",
"description": "The `YYYY-MM-DD`-formatted date to start the subscription. If it is unspecified, the subscription starts immediately."
},
"tax_percentage": {
"type": "string",
"description": "The 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%."
},
"timezone": {
"type": "string",
"description": "The 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)."
}
},
"required": [
"PCID",
"customer_id",
"location_id"
]
}
```
***
## square\_bookings\_delete\_booking\_custom\_attribute
DeleteBookingCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the target booking. |
| `key` | string | Yes | — | The 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the target [booking](entity:Booking)."
},
"key": {
"type": "string",
"description": "The 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."
}
},
"required": [
"PCID",
"booking_id",
"key"
]
}
```
***
## square\_bookings\_delete\_booking\_custom\_attribute\_definition
DeleteBookingCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to delete."
}
},
"required": [
"PCID",
"key"
]
}
```
***
## square\_bookings\_delete\_invoice
DeleteInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to delete. |
| `version` | integer | No | — | The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the invoice to delete."
},
"version": {
"type": "integer",
"description": "The version of the [invoice](entity:Invoice) to delete. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices)."
}
},
"required": [
"PCID",
"invoice_id"
]
}
```
***
## square\_bookings\_delete\_invoice\_attachment
DeleteInvoiceAttachment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ---------------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to delete the attachment from. |
| `attachment_id` | string | Yes | — | The ID of the attachment to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the [invoice](entity:Invoice) to delete the attachment from."
},
"attachment_id": {
"type": "string",
"description": "The ID of the [attachment](entity:InvoiceAttachment) to delete."
}
},
"required": [
"PCID",
"invoice_id",
"attachment_id"
]
}
```
***
## square\_bookings\_delete\_subscription\_action
DeleteSubscriptionAction
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | -------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription the targeted action is to act upon. |
| `action_id` | string | Yes | — | The ID of the targeted action to be deleted. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription the targeted action is to act upon."
},
"action_id": {
"type": "string",
"description": "The ID of the targeted action to be deleted."
}
},
"required": [
"PCID",
"subscription_id",
"action_id"
]
}
```
***
## square\_bookings\_get\_invoice
GetInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ---------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the invoice to retrieve."
}
},
"required": [
"PCID",
"invoice_id"
]
}
```
***
## square\_bookings\_list\_booking\_custom\_attribute\_definitions
ListBookingCustomAttributeDefinitions
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | No | — | The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `cursor` | string | No | — | The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"limit": {
"type": "integer",
"description": "The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"cursor": {
"type": "string",
"description": "The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_list\_booking\_custom\_attributes
ListBookingCustomAttributes
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the target booking. |
| `limit` | integer | No | — | The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `cursor` | string | No | — | The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `with_definitions` | boolean | No | — | Indicates 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`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the target [booking](entity:Booking)."
},
"limit": {
"type": "integer",
"description": "The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"cursor": {
"type": "string",
"description": "The 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"with_definitions": {
"type": "boolean",
"description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) 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`."
}
},
"required": [
"PCID",
"booking_id"
]
}
```
***
## square\_bookings\_list\_bookings
ListBookings
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | No | — | The maximum number of results per page to return in a paged response. |
| `cursor` | string | No | — | 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` | string | No | — | The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved. |
| `team_member_id` | string | No | — | The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved. |
| `location_id` | string | No | — | The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved. |
| `start_at_min` | string | No | — | The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used. |
| `start_at_max` | string | No | — | 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"limit": {
"type": "integer",
"description": "The maximum number of results per page to return in a paged response."
},
"cursor": {
"type": "string",
"description": "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": {
"type": "string",
"description": "The [customer](entity:Customer) for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved."
},
"team_member_id": {
"type": "string",
"description": "The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved."
},
"location_id": {
"type": "string",
"description": "The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved."
},
"start_at_min": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used."
},
"start_at_max": {
"type": "string",
"description": "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."
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_list\_invoices
ListInvoices
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location_id` | string | Yes | — | The ID of the location for which to list invoices. |
| `cursor` | string | No | — | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `limit` | integer | No | — | The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location for which to list invoices."
},
"cursor": {
"type": "string",
"description": "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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"limit": {
"type": "integer",
"description": "The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices."
}
},
"required": [
"PCID",
"location_id"
]
}
```
***
## square\_bookings\_list\_location\_booking\_profiles
ListLocationBookingProfiles
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | No | — | The maximum number of results to return in a paged response. |
| `cursor` | string | No | — | 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in a paged response."
},
"cursor": {
"type": "string",
"description": "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."
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_list\_subscription\_events
ListSubscriptionEvents
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to retrieve the events for. |
| `cursor` | string | No | — | When 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `limit` | integer | No | — | The upper limit on the number of subscription events to return in a paged response. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to retrieve the events for."
},
"cursor": {
"type": "string",
"description": "When 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"limit": {
"type": "integer",
"description": "The upper limit on the number of subscription events to return in a paged response."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_list\_team\_member\_booking\_profiles
ListTeamMemberBookingProfiles
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bookable_only` | boolean | No | — | Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`). |
| `limit` | integer | No | — | The maximum number of results to return in a paged response. |
| `cursor` | string | No | — | 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_id` | string | No | — | Indicates whether to include only team members enabled at the given location in the returned result. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"bookable_only": {
"type": "boolean",
"description": "Indicates whether to include only bookable team members in the returned result (`true`) or not (`false`)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to return in a paged response."
},
"cursor": {
"type": "string",
"description": "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_id": {
"type": "string",
"description": "Indicates whether to include only team members enabled at the given location in the returned result."
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_pause\_subscription
PauseSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to pause. | |
| `pause_cycle_duration` | integer | null | No | — | The 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_date` | string | null | No | — | The `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_reason` | string | null | No | — | The user-provided reason to pause the subscription. |
| `resume_change_timing` | string | No | — | Supported timings when a pending change, as an action, takes place to a subscription. | |
| `resume_effective_date` | string | null | No | — | The 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`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to pause."
},
"pause_cycle_duration": {
"type": [
"integer",
"null"
],
"description": "The 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_date": {
"type": [
"string",
"null"
],
"description": "The `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_reason": {
"type": [
"string",
"null"
],
"description": "The user-provided reason to pause the subscription."
},
"resume_change_timing": {
"type": "string",
"description": "Supported timings when a pending change, as an action, takes place to a subscription.",
"enum": [
"IMMEDIATE",
"END_OF_BILLING_CYCLE"
]
},
"resume_effective_date": {
"type": [
"string",
"null"
],
"description": "The 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`."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_publish\_invoice
PublishInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to publish. | |
| `idempotency_key` | string | null | No | — | A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `version` | integer | Yes | — | The version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the invoice to publish."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"version": {
"type": "integer",
"description": "The version of the [invoice](entity:Invoice) to publish. This must match the current version of the invoice; otherwise, the request is rejected."
}
},
"required": [
"PCID",
"invoice_id",
"version"
]
}
```
***
## square\_bookings\_resume\_subscription
ResumeSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `subscription_id` | string | Yes | — | The ID of the subscription to resume. | |
| `resume_change_timing` | string | No | — | Supported timings when a pending change, as an action, takes place to a subscription. | |
| `resume_effective_date` | string | null | No | — | The `YYYY-MM-DD`-formatted date when the subscription reactivated. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to resume."
},
"resume_change_timing": {
"type": "string",
"description": "Supported timings when a pending change, as an action, takes place to a subscription.",
"enum": [
"IMMEDIATE",
"END_OF_BILLING_CYCLE"
]
},
"resume_effective_date": {
"type": [
"string",
"null"
],
"description": "The `YYYY-MM-DD`-formatted date when the subscription reactivated."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_retrieve\_booking
RetrieveBooking
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ---------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the Booking object representing the to-be-retrieved booking. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the [Booking](entity:Booking) object representing the to-be-retrieved booking."
}
},
"required": [
"PCID",
"booking_id"
]
}
```
***
## square\_bookings\_retrieve\_booking\_custom\_attribute
RetrieveBookingCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the target booking. |
| `key` | string | Yes | — | The 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_definition` | boolean | No | — | Indicates 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`. |
| `version` | integer | No | — | The 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the target [booking](entity:Booking)."
},
"key": {
"type": "string",
"description": "The 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_definition": {
"type": "boolean",
"description": "Indicates whether to return the [custom attribute definition](entity:CustomAttributeDefinition) 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`."
},
"version": {
"type": "integer",
"description": "The 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."
}
},
"required": [
"PCID",
"booking_id",
"key"
]
}
```
***
## square\_bookings\_retrieve\_booking\_custom\_attribute\_definition
RetrieveBookingCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key. |
| `version` | integer | No | — | The 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key."
},
"version": {
"type": "integer",
"description": "The 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."
}
},
"required": [
"PCID",
"key"
]
}
```
***
## square\_bookings\_retrieve\_business\_booking\_profile
RetrieveBusinessBookingProfile
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_retrieve\_location\_booking\_profile
RetrieveLocationBookingProfile
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------- |
| `location_id` | string | Yes | — | The ID of the location to retrieve the booking profile. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location to retrieve the booking profile."
}
},
"required": [
"PCID",
"location_id"
]
}
```
***
## square\_bookings\_retrieve\_subscription
RetrieveSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `subscription_id` | string | Yes | — | The ID of the subscription to retrieve. |
| `include` | string | No | — | A 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to retrieve."
},
"include": {
"type": "string",
"description": "A 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."
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_retrieve\_team\_member\_booking\_profile
RetrieveTeamMemberBookingProfile
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------- | ------ | -------- | ------- | -------------------------------------- |
| `team_member_id` | string | Yes | — | The ID of the team member to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"team_member_id": {
"type": "string",
"description": "The ID of the team member to retrieve."
}
},
"required": [
"PCID",
"team_member_id"
]
}
```
***
## square\_bookings\_search\_availability
SearchAvailability
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------------------------------------------- |
| `query` | object | Yes | — | The query used to search for buyer-accessible availabilities of bookings. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"query": {
"type": "object",
"description": "The query used to search for buyer-accessible availabilities of bookings.",
"properties": {
"filter": {
"type": "object",
"description": "A query filter to search for buyer-accessible availabilities by."
}
},
"required": [
"filter"
]
}
},
"required": [
"PCID",
"query"
]
}
```
***
## square\_bookings\_search\_invoices
SearchInvoices
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `limit` | integer | No | — | The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices. |
| `query` | object | Yes | — | Describes query criteria for searching invoices. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"limit": {
"type": "integer",
"description": "The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices."
},
"query": {
"type": "object",
"description": "Describes query criteria for searching invoices.",
"properties": {
"filter": {
"type": "object",
"description": "Describes query filters to apply."
},
"sort": {
"type": "object",
"description": "Identifies the sort field and sort order."
}
},
"required": [
"filter"
]
}
},
"required": [
"PCID",
"query"
]
}
```
***
## square\_bookings\_search\_subscriptions
SearchSubscriptions
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | When 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `include` | string\[] | No | — | An option to include related information in the response. The supported values are: - `actions`: to include scheduled actions on the targeted subscriptions. |
| `limit` | integer | No | — | The upper limit on the number of subscriptions to return in a paged response. |
| `query` | object | No | — | Represents a query, consisting of specified query expressions, used to search for subscriptions. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "When 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"include": {
"type": "array",
"items": {
"type": "string"
},
"description": "An option to include related information in the response. The supported values are: - `actions`: to include scheduled actions on the targeted subscriptions."
},
"limit": {
"type": "integer",
"description": "The upper limit on the number of subscriptions to return in a paged response."
},
"query": {
"type": "object",
"description": "Represents a query, consisting of specified query expressions, used to search for subscriptions.",
"properties": {
"filter": {
"type": "object",
"description": "Represents a set of query expressions (filters) to narrow the scope of targeted subscriptions returned by the [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions) endpoint."
}
}
}
},
"required": [
"PCID"
]
}
```
***
## square\_bookings\_swap\_plan
SwapPlan
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------- | --------- | -------- | ------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to swap the subscription plan for. | |
| `new_plan_variation_id` | string | null | Yes | — | The ID of the new subscription plan variation. This field is required. |
| `phases` | object\[] | No | — | A list of PhaseInputs, to pass phase-specific information used in the swap. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to swap the subscription plan for."
},
"new_plan_variation_id": {
"type": [
"string",
"null"
],
"description": "The ID of the new subscription plan variation. This field is required."
},
"phases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ordinal": {
"type": "integer",
"format": "int64",
"description": "index of phase in total subscription plan"
},
"order_template_id": {
"type": "string",
"description": "id of order to be used in billing"
}
},
"required": [
"ordinal"
]
},
"description": "A list of PhaseInputs, to pass phase-specific information used in the swap."
}
},
"required": [
"PCID",
"subscription_id",
"new_plan_variation_id"
]
}
```
***
## square\_bookings\_update\_booking
UpdateBooking
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the Booking object representing the to-be-updated booking. | |
| `booking` | object | Yes | — | Represents 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_key` | string | null | No | — | A unique key to make this request an idempotent operation. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the [Booking](entity:Booking) object representing the to-be-updated booking."
},
"booking": {
"type": "object",
"description": "Represents 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.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID of this object representing a booking."
},
"version": {
"type": "integer",
"description": "The revision number for the booking used for optimistic concurrency."
},
"status": {
"type": "string",
"description": "Supported booking statuses.",
"enum": [
"PENDING",
"CANCELLED_BY_CUSTOMER",
"CANCELLED_BY_SELLER",
"DECLINED",
"ACCEPTED",
"NO_SHOW"
]
},
"created_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the creation time of this booking."
},
"updated_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the most recent update time of this booking."
},
"start_at": {
"type": "string",
"description": "The RFC 3339 timestamp specifying the starting time of this booking."
},
"location_id": {
"type": "string",
"description": "The ID of the [Location](entity:Location) object representing the location where the booked service is provided. Once set when the booking is created, its value cannot be changed."
},
"customer_id": {
"type": "string",
"description": "The ID of the [Customer](entity:Customer) object representing the customer receiving the booked service."
},
"customer_note": {
"type": "string",
"description": "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](entity:CatalogObject) instance."
},
"seller_note": {
"type": "string",
"description": "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](entity:CatalogObject) instance. This field should not be visible to customers."
},
"appointment_segments": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of appointment segments for this booking."
},
"transition_time_minutes": {
"type": "integer",
"description": "Additional time at the end of a booking. Applications should not make this field visible to customers of a seller."
},
"all_day": {
"type": "boolean",
"description": "Whether the booking is of a full business day."
},
"location_type": {
"type": "string",
"description": "Supported types of location where service is provided.",
"enum": [
"BUSINESS_LOCATION",
"CUSTOMER_LOCATION",
"PHONE"
]
},
"creator_details": {
"type": "object",
"description": "Information about a booking creator."
},
"source": {
"type": "string",
"description": "Supported sources a booking was created from.",
"enum": [
"FIRST_PARTY_MERCHANT",
"FIRST_PARTY_BUYER",
"THIRD_PARTY_BUYER",
"API"
]
},
"address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
}
}
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique key to make this request an idempotent operation."
}
},
"required": [
"PCID",
"booking_id",
"booking"
]
}
```
***
## square\_bookings\_update\_booking\_custom\_attribute\_definition
UpdateBookingCustomAttributeDefinition
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | string | Yes | — | The key of the custom attribute definition to update. | |
| `custom_attribute_definition` | object | Yes | — | Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. | |
| `idempotency_key` | string | null | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"key": {
"type": "string",
"description": "The key of the custom attribute definition to update."
},
"custom_attribute_definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-). This field can not be changed after the custom attribute definition is created. This field is required when creating a definition and must be unique per application, seller, and resource type."
},
"schema": {
"type": "object",
"description": "The JSON schema for the custom attribute definition, which determines the data type of the corresponding custom attributes. For more information, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview). This field is required when creating a definition."
},
"name": {
"type": "string",
"description": "The name of the custom attribute definition for API and seller-facing UI purposes. The name must be unique within the seller and application pair. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"description": {
"type": "string",
"description": "Seller-oriented description of the custom attribute definition, including any constraints that the seller should observe. May be displayed as a tooltip in Square UIs. This field is required if the `visibility` field is `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute definition. The value is incremented each time the custom attribute definition is updated. When updating a custom attribute definition, you can provide this field and specify the current version of the custom attribute definition to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). On writes, this field must be set to the latest version. Stale writes are rejected. This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created or most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute definition was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"key",
"custom_attribute_definition"
]
}
```
***
## square\_bookings\_update\_invoice
UpdateInvoice
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice_id` | string | Yes | — | The ID of the invoice to update. | |
| `fields_to_clear` | string\[] | No | — | The 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](https://developer.squareup.com/docs/invoices-api/update-invoices). | |
| `idempotency_key` | string | null | No | — | A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `invoice` | object | Yes | — | Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview). | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"invoice_id": {
"type": "string",
"description": "The ID of the invoice to update."
},
"fields_to_clear": {
"type": "array",
"items": {
"type": "string"
},
"description": "The 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](https://developer.squareup.com/docs/invoices-api/update-invoices)."
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"invoice": {
"type": "object",
"description": "Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see [Invoices API Overview](https://developer.squareup.com/docs/invoices-api/overview).",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the invoice."
},
"version": {
"type": "integer",
"description": "The Square-assigned version number, which is incremented each time an update is committed to the invoice."
},
"location_id": {
"type": "string",
"description": "The ID of the location that this invoice is associated with. If specified in a `CreateInvoice` request, the value must match the `location_id` of the associated order."
},
"order_id": {
"type": "string",
"description": "The ID of the [order](entity:Order) for which the invoice is created. This field is required when creating an invoice, and the order must be in the `OPEN` state. To view the line items and other information for the associated order, call the [RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using the order ID."
},
"primary_recipient": {
"type": "object",
"description": "Represents a snapshot of customer data. This object stores customer data that is displayed on the invoice and that Square uses to deliver the invoice. When you provide a customer ID for a draft invoice, Square retrieves the associated customer profile and populates the remaining `InvoiceRecipient` fields. You cannot update these fields after the invoice is published. Square updates the customer ID in response to a merge operation, but does not update other fields."
},
"payment_requests": {
"type": "array",
"items": {
"type": "object"
},
"description": "The payment schedule for the invoice, represented by one or more payment requests that define payment settings, such as amount due and due date. An invoice supports the following payment request combinations: - One balance - One deposit with one balance - 2–12 installments - One deposit with 2–12 installments This field is required when creating an invoice. It must contain at least one payment request. All payment requests for the invoice must equal the total order amount. For more information, see [Configuring payment requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests). Adding `INSTALLMENT` payment requests to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription)."
},
"delivery_method": {
"type": "string",
"description": "Indicates how Square delivers the [invoice](entity:Invoice) to the customer.",
"enum": [
"EMAIL",
"SHARE_MANUALLY",
"SMS"
]
},
"invoice_number": {
"type": "string",
"description": "A user-friendly invoice number that is displayed on the invoice. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and is padded with zeros making it 7 characters long (for example, 0000001 and 0000002)."
},
"title": {
"type": "string",
"description": "The title of the invoice, which is displayed on the invoice."
},
"description": {
"type": "string",
"description": "The description of the invoice, which is displayed on the invoice."
},
"scheduled_at": {
"type": "string",
"description": "The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings. If the field is not set, Square processes the invoice immediately after it is published."
},
"public_url": {
"type": "string",
"description": "A temporary link to the Square-hosted payment page where the customer can pay the invoice. If the link expires, customers can provide the email address or phone number associated with the invoice and request a new link directly from the expired payment page. This field is added after the invoice is published and reaches the scheduled date (if one is defined)."
},
"next_payment_amount_money": {
"type": "object",
"description": "Represents 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"status": {
"type": "string",
"description": "Indicates the status of an [invoice](entity:Invoice).",
"enum": [
"DRAFT",
"UNPAID",
"SCHEDULED",
"PARTIALLY_PAID",
"PAID",
"PARTIALLY_REFUNDED",
"REFUNDED",
"CANCELED",
"FAILED",
"PAYMENT_PENDING"
]
},
"timezone": {
"type": "string",
"description": "The time zone used to interpret calendar dates on the invoice, such as `due_date`. When an invoice is created, this field is set to the `timezone` specified for the seller location. The value cannot be changed. For example, a payment `due_date` of 2021-03-09 with a `timezone` of America/Los\\_Angeles becomes overdue at midnight on March 9 in America/Los\\_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z)."
},
"created_at": {
"type": "string",
"description": "The timestamp when the invoice was created, in RFC 3339 format."
},
"updated_at": {
"type": "string",
"description": "The timestamp when the invoice was last updated, in RFC 3339 format."
},
"accepted_payment_methods": {
"type": "object",
"description": "The payment methods that customers can use to pay an [invoice](entity:Invoice) on the Square-hosted invoice payment page."
},
"custom_fields": {
"type": "array",
"items": {
"type": "object"
},
"description": "Additional seller-defined fields that are displayed on the invoice. For more information, see [Custom fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields). Adding custom fields to an invoice requires an [Invoices Plus subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription). Max: 2 custom fields"
},
"subscription_id": {
"type": "string",
"description": "The ID of the [subscription](entity:Subscription) associated with the invoice. This field is present only on subscription billing invoices."
},
"sale_or_service_date": {
"type": "string",
"description": "The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format. This field can be used to specify a past or future date which is displayed on the invoice."
},
"payment_conditions": {
"type": "string",
"description": "**France only.** The payment terms and conditions that are displayed on the invoice. For more information, see [Payment conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions). For countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and \"Payment conditions are not supported for this location's country\" detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests."
},
"store_payment_method_enabled": {
"type": "boolean",
"description": "Indicates whether to allow a customer to save a credit or debit card as a card on file or a bank transfer as a bank account on file. If `true`, Square displays a __Save my card on file__ or __Save my bank on file__ checkbox on the invoice payment page. Stored payment information can be used for future automatic payments. The default value is `false`."
},
"attachments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Metadata about the attachments on the invoice. Invoice attachments are managed using the [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment) and [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment) endpoints."
},
"creator_team_member_id": {
"type": "string",
"description": "The ID of the [team member](entity:TeamMember) who created the invoice. This field is present only on invoices created in the Square Dashboard or Square Invoices app by a logged-in team member."
}
}
}
},
"required": [
"PCID",
"invoice_id",
"invoice"
]
}
```
***
## square\_bookings\_update\_subscription
UpdateSubscription
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscription_id` | string | Yes | — | The ID of the subscription to update. |
| `subscription` | object | No | — | Represents a subscription purchased by a customer. For more information, see [Manage Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"subscription_id": {
"type": "string",
"description": "The ID of the subscription to update."
},
"subscription": {
"type": "object",
"description": "Represents a subscription purchased by a customer. For more information, see [Manage Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions).",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the subscription."
},
"location_id": {
"type": "string",
"description": "The ID of the location associated with the subscription."
},
"plan_variation_id": {
"type": "string",
"description": "The ID of the subscribed-to [subscription plan variation](entity:CatalogSubscriptionPlanVariation)."
},
"customer_id": {
"type": "string",
"description": "The ID of the subscribing [customer](entity:Customer) profile."
},
"start_date": {
"type": "string",
"description": "The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to start the subscription."
},
"canceled_date": {
"type": "string",
"description": "The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to cancel the subscription, when the subscription status changes to `CANCELED` and the subscription billing stops. If this field is not set, the subscription ends according its subscription plan. This field cannot be updated, other than being cleared."
},
"charged_through_date": {
"type": "string",
"description": "The `YYYY-MM-DD`-formatted date up to when the subscriber is invoiced for the subscription. After the invoice is sent for a given billing period, this date will be the last day of the billing period. For example, suppose for the month of May a subscriber gets an invoice (or charged the card) on May 1. For the monthly billing scenario, this date is then set to May 31."
},
"status": {
"type": "string",
"description": "Supported subscription statuses.",
"enum": [
"PENDING",
"ACTIVE",
"CANCELED",
"DEACTIVATED",
"PAUSED",
"COMPLETED"
]
},
"tax_percentage": {
"type": "string",
"description": "The tax amount applied 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%."
},
"invoice_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the [invoices](entity:Invoice) created for the subscription, listed in order when the invoices were created (newest invoices appear first)."
},
"price_override_money": {
"type": "object",
"description": "Represents 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information."
},
"version": {
"type": "integer",
"description": "The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting."
},
"created_at": {
"type": "string",
"description": "The timestamp when the subscription was created, in RFC 3339 format."
},
"card_id": {
"type": "string",
"description": "The ID of the [subscriber's](entity:Customer) [card](entity:Card) used to charge for the subscription."
},
"timezone": {
"type": "string",
"description": "Timezone that will be used in date calculations for the subscription. Defaults to the timezone of the location based on `location_id`. Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`)."
},
"source": {
"type": "object",
"description": "The origination details of the subscription."
},
"actions": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of scheduled actions on this subscription. It is set only in the response from [RetrieveSubscription](api-endpoint:Subscriptions-RetrieveSubscription) with the query parameter of `include=actions` or from [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions) with the input parameter of `include:[\"actions\"]`."
},
"monthly_billing_anchor_date": {
"type": "integer",
"description": "The day of the month on which the subscription will issue invoices and publish orders."
},
"phases": {
"type": "array",
"items": {
"type": "object"
},
"description": "array of phases for this subscription"
},
"completed_date": {
"type": "string",
"description": "The `YYYY-MM-DD`-formatted date when the subscription enters a terminal state."
}
}
}
},
"required": [
"PCID",
"subscription_id"
]
}
```
***
## square\_bookings\_upsert\_booking\_custom\_attribute
UpsertBookingCustomAttribute
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ------------------ | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `booking_id` | string | Yes | — | The ID of the target booking. | |
| `key` | string | Yes | — | The 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_attribute` | object | Yes | — | A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object. | |
| `idempotency_key` | string | null | No | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"booking_id": {
"type": "string",
"description": "The ID of the target [booking](entity:Booking)."
},
"key": {
"type": "string",
"description": "The 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_attribute": {
"type": "object",
"description": "A custom attribute value. Each custom attribute value has a corresponding `CustomAttributeDefinition` object.",
"properties": {
"key": {
"type": "string",
"description": "The identifier of the custom attribute definition and its corresponding custom attributes. This value can be a simple key, which is the key that is provided when the custom attribute definition is created, or a qualified key, if the requesting application is not the definition owner. The qualified key consists of the application ID of the custom attribute definition owner followed by the simple key that was provided when the definition was created. It has the format application_id:simple key. The value for a simple key can contain up to 60 alphanumeric characters, periods (.), underscores (_), and hyphens (-)."
},
"value": {
"description": "The value assigned to the custom attribute. It is validated against the custom attribute definition's schema on write operations. For more information about custom attribute values, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"version": {
"type": "integer",
"description": "Read only. The current version of the custom attribute. This field is incremented when the custom attribute is changed. When updating an existing custom attribute value, you can provide this field and specify the current version of the custom attribute to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency). This field can also be used to enforce strong consistency for reads. For more information about strong consistency for reads, see [Custom Attributes Overview](https://developer.squareup.com/docs/devtools/customattributes/overview)."
},
"visibility": {
"type": "string",
"description": "The level of permission that a seller or other applications requires to view this custom attribute definition. The `Visibility` field controls who can read and write the custom attribute values and custom attribute definition.",
"enum": [
"VISIBILITY_HIDDEN",
"VISIBILITY_READ_ONLY",
"VISIBILITY_READ_WRITE_VALUES"
]
},
"definition": {
"type": "object",
"description": "Represents a definition for custom attribute values. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute."
},
"updated_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute was created or was most recently updated, in RFC 3339 format."
},
"created_at": {
"type": "string",
"description": "The timestamp that indicates when the custom attribute was created, in RFC 3339 format."
}
}
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
}
},
"required": [
"PCID",
"booking_id",
"key",
"custom_attribute"
]
}
```