> ## 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-locations > Square Locations & Settings **Server path:** `/square-locations` | **Type:** Application | **PCID required:** Yes ## Tools | Tool | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [`square_locations_bulk_delete_location_custom_attributes`](#square_locations_bulk_delete_location_custom_attributes) | BulkDeleteLocationCustomAttributes | | [`square_locations_bulk_delete_merchant_custom_attributes`](#square_locations_bulk_delete_merchant_custom_attributes) | BulkDeleteMerchantCustomAttributes | | [`square_locations_bulk_retrieve_channels`](#square_locations_bulk_retrieve_channels) | BulkRetrieveChannels | | [`square_locations_bulk_upsert_location_custom_attributes`](#square_locations_bulk_upsert_location_custom_attributes) | BulkUpsertLocationCustomAttributes | | [`square_locations_bulk_upsert_merchant_custom_attributes`](#square_locations_bulk_upsert_merchant_custom_attributes) | BulkUpsertMerchantCustomAttributes | | [`square_locations_create_location`](#square_locations_create_location) | CreateLocation | | [`square_locations_create_location_custom_attribute_definition`](#square_locations_create_location_custom_attribute_definition) | CreateLocationCustomAttributeDefinition | | [`square_locations_create_merchant_custom_attribute_definition`](#square_locations_create_merchant_custom_attribute_definition) | CreateMerchantCustomAttributeDefinition | | [`square_locations_create_webhook_subscription`](#square_locations_create_webhook_subscription) | CreateWebhookSubscription | | [`square_locations_delete_location_custom_attribute`](#square_locations_delete_location_custom_attribute) | DeleteLocationCustomAttribute | | [`square_locations_delete_location_custom_attribute_definition`](#square_locations_delete_location_custom_attribute_definition) | DeleteLocationCustomAttributeDefinition | | [`square_locations_delete_merchant_custom_attribute`](#square_locations_delete_merchant_custom_attribute) | DeleteMerchantCustomAttribute | | [`square_locations_delete_merchant_custom_attribute_definition`](#square_locations_delete_merchant_custom_attribute_definition) | DeleteMerchantCustomAttributeDefinition | | [`square_locations_delete_snippet`](#square_locations_delete_snippet) | DeleteSnippet | | [`square_locations_delete_webhook_subscription`](#square_locations_delete_webhook_subscription) | DeleteWebhookSubscription | | [`square_locations_disable_events`](#square_locations_disable_events) | DisableEvents | | [`square_locations_enable_events`](#square_locations_enable_events) | EnableEvents | | [`square_locations_list_channels`](#square_locations_list_channels) | ListChannels | | [`square_locations_list_event_types`](#square_locations_list_event_types) | ListEventTypes | | [`square_locations_list_location_custom_attribute_definitions`](#square_locations_list_location_custom_attribute_definitions) | ListLocationCustomAttributeDefinitions | | [`square_locations_list_location_custom_attributes`](#square_locations_list_location_custom_attributes) | ListLocationCustomAttributes | | [`square_locations_list_locations`](#square_locations_list_locations) | ListLocations | | [`square_locations_list_merchant_custom_attribute_definitions`](#square_locations_list_merchant_custom_attribute_definitions) | ListMerchantCustomAttributeDefinitions | | [`square_locations_list_merchant_custom_attributes`](#square_locations_list_merchant_custom_attributes) | ListMerchantCustomAttributes | | [`square_locations_list_merchants`](#square_locations_list_merchants) | ListMerchants | | [`square_locations_list_sites`](#square_locations_list_sites) | ListSites | | [`square_locations_list_webhook_event_types`](#square_locations_list_webhook_event_types) | ListWebhookEventTypes | | [`square_locations_list_webhook_subscriptions`](#square_locations_list_webhook_subscriptions) | ListWebhookSubscriptions | | [`square_locations_retrieve_channel`](#square_locations_retrieve_channel) | RetrieveChannel | | [`square_locations_retrieve_location`](#square_locations_retrieve_location) | RetrieveLocation | | [`square_locations_retrieve_location_custom_attribute`](#square_locations_retrieve_location_custom_attribute) | RetrieveLocationCustomAttribute | | [`square_locations_retrieve_location_custom_attribute_definition`](#square_locations_retrieve_location_custom_attribute_definition) | RetrieveLocationCustomAttributeDefinition | | [`square_locations_retrieve_merchant`](#square_locations_retrieve_merchant) | RetrieveMerchant | | [`square_locations_retrieve_merchant_custom_attribute`](#square_locations_retrieve_merchant_custom_attribute) | RetrieveMerchantCustomAttribute | | [`square_locations_retrieve_merchant_custom_attribute_definition`](#square_locations_retrieve_merchant_custom_attribute_definition) | RetrieveMerchantCustomAttributeDefinition | | [`square_locations_retrieve_snippet`](#square_locations_retrieve_snippet) | RetrieveSnippet | | [`square_locations_retrieve_webhook_subscription`](#square_locations_retrieve_webhook_subscription) | RetrieveWebhookSubscription | | [`square_locations_search_events`](#square_locations_search_events) | SearchEvents | | [`square_locations_test_webhook_subscription`](#square_locations_test_webhook_subscription) | TestWebhookSubscription | | [`square_locations_update_location`](#square_locations_update_location) | UpdateLocation | | [`square_locations_update_location_custom_attribute_definition`](#square_locations_update_location_custom_attribute_definition) | UpdateLocationCustomAttributeDefinition | | [`square_locations_update_merchant_custom_attribute_definition`](#square_locations_update_merchant_custom_attribute_definition) | UpdateMerchantCustomAttributeDefinition | | [`square_locations_update_webhook_subscription`](#square_locations_update_webhook_subscription) | UpdateWebhookSubscription | | [`square_locations_update_webhook_subscription_signature_key`](#square_locations_update_webhook_subscription_signature_key) | UpdateWebhookSubscriptionSignatureKey | | [`square_locations_upsert_location_custom_attribute`](#square_locations_upsert_location_custom_attribute) | UpsertLocationCustomAttribute | | [`square_locations_upsert_merchant_custom_attribute`](#square_locations_upsert_merchant_custom_attribute) | UpsertMerchantCustomAttribute | | [`square_locations_upsert_snippet`](#square_locations_upsert_snippet) | UpsertSnippet | *** ## square\_locations\_bulk\_delete\_location\_custom\_attributes BulkDeleteLocationCustomAttributes **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | `values` | object | Yes | — | The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "values": { "type": "object", "description": "The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response." } }, "required": [ "PCID", "values" ] } ``` *** ## square\_locations\_bulk\_delete\_merchant\_custom\_attributes BulkDeleteMerchantCustomAttributes **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | `values` | object | Yes | — | The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "values": { "type": "object", "description": "The data used to update the `CustomAttribute` objects. The keys must be unique and are used to map to the corresponding response." } }, "required": [ "PCID", "values" ] } ``` *** ## square\_locations\_bulk\_retrieve\_channels BulkRetrieveChannels **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | --------- | -------- | ------- | ----------- | | `channel_ids` | string\[] | Yes | — | Channel Ids | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "channel_ids": { "type": "array", "items": { "type": "string" }, "description": "Channel Ids" } }, "required": [ "PCID", "channel_ids" ] } ``` *** ## square\_locations\_bulk\_upsert\_location\_custom\_attributes BulkUpsertLocationCustomAttributes **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 `BulkUpsertLocationCustomAttributes` 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 `BulkUpsertLocationCustomAttributes` request and the information needed to create or update a custom attribute." } }, "required": [ "PCID", "values" ] } ``` *** ## square\_locations\_bulk\_upsert\_merchant\_custom\_attributes BulkUpsertMerchantCustomAttributes **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 `BulkUpsertMerchantCustomAttributes` 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 `BulkUpsertMerchantCustomAttributes` request and the information needed to create or update a custom attribute." } }, "required": [ "PCID", "values" ] } ``` *** ## square\_locations\_create\_location CreateLocation **Parameters:** | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------- | | `location` | object | No | — | Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api). | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "location": { "type": "object", "description": "Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api).", "properties": { "id": { "type": "string", "description": "A short generated string of letters and numbers that uniquely identifies this location instance." }, "name": { "type": "string", "description": "The name of the location. This information appears in the Seller Dashboard as the nickname. A location name must be unique within a seller account." }, "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)." }, "timezone": { "type": "string", "description": "The [IANA time zone](https://www.iana.org/time-zones) identifier for the time zone of the location. For example, `America/Los_Angeles`." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "CREDIT_CARD_PROCESSING", "AUTOMATIC_TRANSFERS", "UNLINKED_REFUNDS" ] }, "description": "The Square features that are enabled for the location. See [LocationCapability](entity:LocationCapability) for possible values. See [LocationCapability](#type-locationcapability) for possible values" }, "status": { "type": "string", "description": "A location's status.", "enum": [ "ACTIVE", "INACTIVE" ] }, "created_at": { "type": "string", "description": "The time when the location was created, in RFC 3339 format. For more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates)." }, "merchant_id": { "type": "string", "description": "The ID of the merchant that owns the location." }, "country": { "type": "string", "description": "Indicates the country associated with another entity, such as a business. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "enum": [ "ZZ", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "language_code": { "type": "string", "description": "The language associated with the location, in [BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A). For more information, see [Language Preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences)." }, "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" ] }, "phone_number": { "type": "string", "description": "The phone number of the location. For example, `+1 855-700-6000`." }, "business_name": { "type": "string", "description": "The name of the location's overall business. This name is present on receipts and other customer-facing branding, and can be changed no more than three times in a twelve-month period." }, "type": { "type": "string", "description": "A location's type.", "enum": [ "PHYSICAL", "MOBILE" ] }, "website_url": { "type": "string", "description": "The website URL of the location. For example, `https://squareup.com`." }, "business_hours": { "type": "object", "description": "The hours of operation for a location." }, "business_email": { "type": "string", "description": "The email address of the location. This can be unique to the location and is not always the email address for the business owner or administrator." }, "description": { "type": "string", "description": "The description of the location. For example, `Main Street location`." }, "twitter_username": { "type": "string", "description": "The Twitter username of the location without the '@' symbol. For example, `Square`." }, "instagram_username": { "type": "string", "description": "The Instagram username of the location without the '@' symbol. For example, `square`." }, "facebook_url": { "type": "string", "description": "The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`." }, "coordinates": { "type": "object", "description": "Latitude and longitude coordinates." }, "logo_url": { "type": "string", "description": "The URL of the logo image for the location. When configured in the Seller Dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller. This image should have a roughly square (1:1) aspect ratio and should be at least 200x200 pixels." }, "pos_background_url": { "type": "string", "description": "The URL of the Point of Sale background image for the location." }, "mcc": { "type": "string", "description": "A four-digit number that describes the kind of goods or services sold at the location. The [merchant category code (MCC)](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) of the location as standardized by ISO 18245. For example, `5045`, for a location that sells computer goods and software." }, "full_format_logo_url": { "type": "string", "description": "The URL of a full-format logo image for the location. When configured in the Seller Dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller. This image can be wider than it is tall and should be at least 1280x648 pixels." }, "tax_ids": { "type": "object", "description": "Identifiers for the location used by various governments for tax purposes." } } } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_create\_location\_custom\_attribute\_definition CreateLocationCustomAttributeDefinition **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\_locations\_create\_merchant\_custom\_attribute\_definition CreateMerchantCustomAttributeDefinition **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\_locations\_create\_webhook\_subscription CreateWebhookSubscription **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `idempotency_key` | string | No | — | A unique string that identifies the CreateWebhookSubscription request. | | `subscription` | object | Yes | — | Represents the details of a webhook subscription, including notification URL, event types, and signature key. | ```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 [CreateWebhookSubscription](api-endpoint:WebhookSubscriptions-CreateWebhookSubscription) request." }, "subscription": { "type": "object", "description": "Represents the details of a webhook subscription, including notification URL, event types, and signature key.", "properties": { "id": { "type": "string", "description": "A Square-generated unique ID for the subscription." }, "name": { "type": "string", "description": "The name of this subscription." }, "enabled": { "type": "boolean", "description": "Indicates whether the subscription is enabled (`true`) or not (`false`)." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "The event types associated with this subscription." }, "notification_url": { "type": "string", "description": "The URL to which webhooks are sent." }, "api_version": { "type": "string", "description": "The API version of the subscription. This field is optional for `CreateWebhookSubscription`. The value defaults to the API version used by the application." }, "signature_key": { "type": "string", "description": "The Square-generated signature key used to validate the origin of the webhook event." }, "created_at": { "type": "string", "description": "The timestamp of when the subscription was created, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\"." }, "updated_at": { "type": "string", "description": "The timestamp of when the subscription was last updated, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\"." } } } }, "required": [ "PCID", "subscription" ] } ``` *** ## square\_locations\_delete\_location\_custom\_attribute DeleteLocationCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_id` | string | Yes | — | The ID of the target location. | | `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" }, "location_id": { "type": "string", "description": "The ID of the target [location](entity:Location)." }, "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", "location_id", "key" ] } ``` *** ## square\_locations\_delete\_location\_custom\_attribute\_definition DeleteLocationCustomAttributeDefinition **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\_locations\_delete\_merchant\_custom\_attribute DeleteMerchantCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_id` | string | Yes | — | The ID of the target merchant. | | `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" }, "merchant_id": { "type": "string", "description": "The ID of the target [merchant](entity:Merchant)." }, "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", "merchant_id", "key" ] } ``` *** ## square\_locations\_delete\_merchant\_custom\_attribute\_definition DeleteMerchantCustomAttributeDefinition **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\_locations\_delete\_snippet DeleteSnippet **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | --------------------------------------------- | | `site_id` | string | Yes | — | The ID of the site that contains the snippet. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "site_id": { "type": "string", "description": "The ID of the site that contains the snippet." } }, "required": [ "PCID", "site_id" ] } ``` *** ## square\_locations\_delete\_webhook\_subscription DeleteWebhookSubscription **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------- | | `subscription_id` | string | Yes | — | \[REQUIRED] The ID of the Subscription to delete. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "subscription_id": { "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to delete." } }, "required": [ "PCID", "subscription_id" ] } ``` *** ## square\_locations\_disable\_events DisableEvents ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_enable\_events EnableEvents ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_channels ListChannels **Parameters:** | Parameter | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- | | `reference_type` | string | No | — | Type of reference associated to channel | | `reference_id` | string | No | — | id of reference associated to channel | | `status` | string | No | — | Status of channel | | `cursor` | string | No | — | Cursor to fetch the next result | | `limit` | integer | No | — | Maximum number of results to return. When not provided the returned results will be cap at 100 channels. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "reference_type": { "type": "string", "description": "Type of reference associated to channel", "enum": [ "UNKNOWN_TYPE", "LOCATION", "FIRST_PARTY_INTEGRATION", "OAUTH_APPLICATION", "ONLINE_SITE", "ONLINE_CHECKOUT", "INVOICE", "GIFT_CARD", "GIFT_CARD_MARKETPLACE", "RECURRING_SUBSCRIPTION", "ONLINE_BOOKING_FLOW", "SQUARE_ASSISTANT", "CASH_LOCAL", "POINT_OF_SALE", "KIOSK" ] }, "reference_id": { "type": "string", "description": "id of reference associated to channel" }, "status": { "type": "string", "description": "Status of channel", "enum": [ "ACTIVE", "INACTIVE" ] }, "cursor": { "type": "string", "description": "Cursor to fetch the next result" }, "limit": { "type": "integer", "description": "Maximum number of results to return. When not provided the returned results will be cap at 100 channels." } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_event\_types ListEventTypes **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `api_version` | string | No | — | The API version for which to list event types. Setting this field overrides the default version used by the application. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "api_version": { "type": "string", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application." } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_location\_custom\_attribute\_definitions ListLocationCustomAttributeDefinitions **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visibility_filter` | string | No | — | Filters the `CustomAttributeDefinition` results by their `visibility` values. | | `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" }, "visibility_filter": { "type": "string", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "enum": [ "ALL", "READ", "READ_WRITE" ] }, "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\_locations\_list\_location\_custom\_attributes ListLocationCustomAttributes **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_id` | string | Yes | — | The ID of the target location. | | `visibility_filter` | string | No | — | Filters the `CustomAttributeDefinition` results by their `visibility` values. | | `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" }, "location_id": { "type": "string", "description": "The ID of the target [location](entity:Location)." }, "visibility_filter": { "type": "string", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "enum": [ "ALL", "READ", "READ_WRITE" ] }, "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", "location_id" ] } ``` *** ## square\_locations\_list\_locations ListLocations ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_merchant\_custom\_attribute\_definitions ListMerchantCustomAttributeDefinitions **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `visibility_filter` | string | No | — | Filters the `CustomAttributeDefinition` results by their `visibility` values. | | `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" }, "visibility_filter": { "type": "string", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "enum": [ "ALL", "READ", "READ_WRITE" ] }, "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\_locations\_list\_merchant\_custom\_attributes ListMerchantCustomAttributes **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_id` | string | Yes | — | The ID of the target merchant. | | `visibility_filter` | string | No | — | Filters the `CustomAttributeDefinition` results by their `visibility` values. | | `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" }, "merchant_id": { "type": "string", "description": "The ID of the target [merchant](entity:Merchant)." }, "visibility_filter": { "type": "string", "description": "Filters the `CustomAttributeDefinition` results by their `visibility` values.", "enum": [ "ALL", "READ", "READ_WRITE" ] }, "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", "merchant_id" ] } ``` *** ## square\_locations\_list\_merchants ListMerchants **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------------- | | `cursor` | integer | No | — | The cursor generated by the previous response. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "cursor": { "type": "integer", "description": "The cursor generated by the previous response." } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_sites ListSites ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_webhook\_event\_types ListWebhookEventTypes **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `api_version` | string | No | — | The API version for which to list event types. Setting this field overrides the default version used by the application. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "api_version": { "type": "string", "description": "The API version for which to list event types. Setting this field overrides the default version used by the application." } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_list\_webhook\_subscriptions ListWebhookSubscriptions **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this 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). | | `include_disabled` | boolean | No | — | Includes disabled Subscriptions. By default, all enabled Subscriptions are returned. | | `sort_order` | string | No | — | Sorts the returned list by when the Subscription was created with the specified order. This field defaults to ASC. | | `limit` | integer | No | — | The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. Default: 100 | ```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 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)." }, "include_disabled": { "type": "boolean", "description": "Includes disabled [Subscription](entity:WebhookSubscription)s. By default, all enabled [Subscription](entity:WebhookSubscription)s are returned." }, "sort_order": { "type": "string", "description": "Sorts the returned list by when the [Subscription](entity:WebhookSubscription) was created with the specified order. This field defaults to ASC.", "enum": [ "DESC", "ASC" ] }, "limit": { "type": "integer", "description": "The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. Default: 100" } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_retrieve\_channel RetrieveChannel **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | ------------ | | `channel_id` | string | Yes | — | A channel id | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "channel_id": { "type": "string", "description": "A channel id" } }, "required": [ "PCID", "channel_id" ] } ``` *** ## square\_locations\_retrieve\_location RetrieveLocation **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------ | | `location_id` | string | Yes | — | The ID of the location to retrieve. Specify the string "main" to return the main location. | ```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. Specify the string \"main\" to return the main location." } }, "required": [ "PCID", "location_id" ] } ``` *** ## square\_locations\_retrieve\_location\_custom\_attribute RetrieveLocationCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_id` | string | Yes | — | The ID of the target location. | | `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" }, "location_id": { "type": "string", "description": "The ID of the target [location](entity:Location)." }, "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", "location_id", "key" ] } ``` *** ## square\_locations\_retrieve\_location\_custom\_attribute\_definition RetrieveLocationCustomAttributeDefinition **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\_locations\_retrieve\_merchant RetrieveMerchant **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_id` | string | Yes | — | The ID of the merchant to retrieve. If the string "me" is supplied as the ID, then retrieve the merchant that is currently accessible to this call. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "merchant_id": { "type": "string", "description": "The ID of the merchant to retrieve. If the string \"me\" is supplied as the ID, then retrieve the merchant that is currently accessible to this call." } }, "required": [ "PCID", "merchant_id" ] } ``` *** ## square\_locations\_retrieve\_merchant\_custom\_attribute RetrieveMerchantCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_id` | string | Yes | — | The ID of the target merchant. | | `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" }, "merchant_id": { "type": "string", "description": "The ID of the target [merchant](entity:Merchant)." }, "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", "merchant_id", "key" ] } ``` *** ## square\_locations\_retrieve\_merchant\_custom\_attribute\_definition RetrieveMerchantCustomAttributeDefinition **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\_locations\_retrieve\_snippet RetrieveSnippet **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | --------------------------------------------- | | `site_id` | string | Yes | — | The ID of the site that contains the snippet. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "site_id": { "type": "string", "description": "The ID of the site that contains the snippet." } }, "required": [ "PCID", "site_id" ] } ``` *** ## square\_locations\_retrieve\_webhook\_subscription RetrieveWebhookSubscription **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | --------------------------------------------------- | | `subscription_id` | string | Yes | — | \[REQUIRED] The ID of the Subscription to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "subscription_id": { "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to retrieve." } }, "required": [ "PCID", "subscription_id" ] } ``` *** ## square\_locations\_search\_events SearchEvents **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 events 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 events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). Default: 100 | | `query` | object | No | — | Contains query criteria for the search. | ```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 events 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 events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). Default: 100" }, "query": { "type": "object", "description": "Contains query criteria for the search.", "properties": { "filter": { "type": "object", "description": "Criteria to filter events by." }, "sort": { "type": "object", "description": "Criteria to sort events by." } } } }, "required": [ "PCID" ] } ``` *** ## square\_locations\_test\_webhook\_subscription TestWebhookSubscription **Parameters:** | Parameter | Type | Required | Default | Description | | | ----------------- | ------ | -------- | ------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `subscription_id` | string | Yes | — | \[REQUIRED] The ID of the Subscription to test. | | | `event_type` | string | null | No | — | The event type that will be used to test the Subscription. The event type must be contained in the list of event types in the Subscription. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "subscription_id": { "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to test." }, "event_type": { "type": [ "string", "null" ], "description": "The event type that will be used to test the [Subscription](entity:WebhookSubscription). The event type must be contained in the list of event types in the [Subscription](entity:WebhookSubscription)." } }, "required": [ "PCID", "subscription_id" ] } ``` *** ## square\_locations\_update\_location UpdateLocation **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------- | | `location_id` | string | Yes | — | The ID of the location to update. | | `location` | object | No | — | Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api). | ```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 update." }, "location": { "type": "object", "description": "Represents one of a business' [locations](https://developer.squareup.com/docs/locations-api).", "properties": { "id": { "type": "string", "description": "A short generated string of letters and numbers that uniquely identifies this location instance." }, "name": { "type": "string", "description": "The name of the location. This information appears in the Seller Dashboard as the nickname. A location name must be unique within a seller account." }, "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)." }, "timezone": { "type": "string", "description": "The [IANA time zone](https://www.iana.org/time-zones) identifier for the time zone of the location. For example, `America/Los_Angeles`." }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "CREDIT_CARD_PROCESSING", "AUTOMATIC_TRANSFERS", "UNLINKED_REFUNDS" ] }, "description": "The Square features that are enabled for the location. See [LocationCapability](entity:LocationCapability) for possible values. See [LocationCapability](#type-locationcapability) for possible values" }, "status": { "type": "string", "description": "A location's status.", "enum": [ "ACTIVE", "INACTIVE" ] }, "created_at": { "type": "string", "description": "The time when the location was created, in RFC 3339 format. For more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates)." }, "merchant_id": { "type": "string", "description": "The ID of the merchant that owns the location." }, "country": { "type": "string", "description": "Indicates the country associated with another entity, such as a business. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).", "enum": [ "ZZ", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "language_code": { "type": "string", "description": "The language associated with the location, in [BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A). For more information, see [Language Preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences)." }, "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" ] }, "phone_number": { "type": "string", "description": "The phone number of the location. For example, `+1 855-700-6000`." }, "business_name": { "type": "string", "description": "The name of the location's overall business. This name is present on receipts and other customer-facing branding, and can be changed no more than three times in a twelve-month period." }, "type": { "type": "string", "description": "A location's type.", "enum": [ "PHYSICAL", "MOBILE" ] }, "website_url": { "type": "string", "description": "The website URL of the location. For example, `https://squareup.com`." }, "business_hours": { "type": "object", "description": "The hours of operation for a location." }, "business_email": { "type": "string", "description": "The email address of the location. This can be unique to the location and is not always the email address for the business owner or administrator." }, "description": { "type": "string", "description": "The description of the location. For example, `Main Street location`." }, "twitter_username": { "type": "string", "description": "The Twitter username of the location without the '@' symbol. For example, `Square`." }, "instagram_username": { "type": "string", "description": "The Instagram username of the location without the '@' symbol. For example, `square`." }, "facebook_url": { "type": "string", "description": "The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`." }, "coordinates": { "type": "object", "description": "Latitude and longitude coordinates." }, "logo_url": { "type": "string", "description": "The URL of the logo image for the location. When configured in the Seller Dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller. This image should have a roughly square (1:1) aspect ratio and should be at least 200x200 pixels." }, "pos_background_url": { "type": "string", "description": "The URL of the Point of Sale background image for the location." }, "mcc": { "type": "string", "description": "A four-digit number that describes the kind of goods or services sold at the location. The [merchant category code (MCC)](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) of the location as standardized by ISO 18245. For example, `5045`, for a location that sells computer goods and software." }, "full_format_logo_url": { "type": "string", "description": "The URL of a full-format logo image for the location. When configured in the Seller Dashboard (Receipts section), the logo appears on transactions (such as receipts and invoices) that Square generates on behalf of the seller. This image can be wider than it is tall and should be at least 1280x648 pixels." }, "tax_ids": { "type": "object", "description": "Identifiers for the location used by various governments for tax purposes." } } } }, "required": [ "PCID", "location_id" ] } ``` *** ## square\_locations\_update\_location\_custom\_attribute\_definition UpdateLocationCustomAttributeDefinition **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\_locations\_update\_merchant\_custom\_attribute\_definition UpdateMerchantCustomAttributeDefinition **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\_locations\_update\_webhook\_subscription UpdateWebhookSubscription **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `subscription_id` | string | Yes | — | \[REQUIRED] The ID of the Subscription to update. | | `subscription` | object | No | — | Represents the details of a webhook subscription, including notification URL, event types, and signature key. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "subscription_id": { "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update." }, "subscription": { "type": "object", "description": "Represents the details of a webhook subscription, including notification URL, event types, and signature key.", "properties": { "id": { "type": "string", "description": "A Square-generated unique ID for the subscription." }, "name": { "type": "string", "description": "The name of this subscription." }, "enabled": { "type": "boolean", "description": "Indicates whether the subscription is enabled (`true`) or not (`false`)." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "The event types associated with this subscription." }, "notification_url": { "type": "string", "description": "The URL to which webhooks are sent." }, "api_version": { "type": "string", "description": "The API version of the subscription. This field is optional for `CreateWebhookSubscription`. The value defaults to the API version used by the application." }, "signature_key": { "type": "string", "description": "The Square-generated signature key used to validate the origin of the webhook event." }, "created_at": { "type": "string", "description": "The timestamp of when the subscription was created, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\"." }, "updated_at": { "type": "string", "description": "The timestamp of when the subscription was last updated, in RFC 3339 format. For example, \"2016-09-04T23:59:33.123Z\"." } } } }, "required": [ "PCID", "subscription_id" ] } ``` *** ## square\_locations\_update\_webhook\_subscription\_signature\_key UpdateWebhookSubscriptionSignatureKey **Parameters:** | Parameter | Type | Required | Default | Description | | | ----------------- | ------ | -------- | ------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- | | `subscription_id` | string | Yes | — | \[REQUIRED] The ID of the Subscription to update. | | | `idempotency_key` | string | null | No | — | A unique string that identifies the UpdateWebhookSubscriptionSignatureKey request. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "subscription_id": { "type": "string", "description": "[REQUIRED] The ID of the [Subscription](entity:WebhookSubscription) to update." }, "idempotency_key": { "type": [ "string", "null" ], "description": "A unique string that identifies the [UpdateWebhookSubscriptionSignatureKey](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscriptionSignatureKey) request." } }, "required": [ "PCID", "subscription_id" ] } ``` *** ## square\_locations\_upsert\_location\_custom\_attribute UpsertLocationCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | | ------------------ | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_id` | string | Yes | — | The ID of the target location. | | | `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" }, "location_id": { "type": "string", "description": "The ID of the target [location](entity:Location)." }, "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", "location_id", "key", "custom_attribute" ] } ``` *** ## square\_locations\_upsert\_merchant\_custom\_attribute UpsertMerchantCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | | ------------------ | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merchant_id` | string | Yes | — | The ID of the target merchant. | | | `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" }, "merchant_id": { "type": "string", "description": "The ID of the target [merchant](entity:Merchant)." }, "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", "merchant_id", "key", "custom_attribute" ] } ``` *** ## square\_locations\_upsert\_snippet UpsertSnippet **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `site_id` | string | Yes | — | The ID of the site where you want to add or update the snippet. | | `snippet` | object | Yes | — | Represents the snippet that is added to a Square Online site. The snippet code is injected into the `head` element of all pages on the site, except for checkout pages. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "site_id": { "type": "string", "description": "The ID of the site where you want to add or update the snippet." }, "snippet": { "type": "object", "description": "Represents the snippet that is added to a Square Online site. The snippet code is injected into the `head` element of all pages on the site, except for checkout pages.", "properties": { "id": { "type": "string", "description": "The Square-assigned ID for the snippet." }, "site_id": { "type": "string", "description": "The ID of the site that contains the snippet." }, "content": { "type": "string", "description": "The snippet code, which can contain valid HTML, JavaScript, or both." }, "created_at": { "type": "string", "description": "The timestamp of when the snippet was initially added to the site, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp of when the snippet was last updated on the site, in RFC 3339 format." } }, "required": [ "content" ] } }, "required": [ "PCID", "site_id", "snippet" ] } ```