> ## 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-customers > Square Customers & Loyalty **Server path:** `/square-customers` | **Type:** Application | **PCID required:** Yes ## Tools | Tool | Description | | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | [`square_customers_accumulate_loyalty_points`](#square_customers_accumulate_loyalty_points) | AccumulateLoyaltyPoints | | [`square_customers_add_group_to_customer`](#square_customers_add_group_to_customer) | AddGroupToCustomer | | [`square_customers_adjust_loyalty_points`](#square_customers_adjust_loyalty_points) | AdjustLoyaltyPoints | | [`square_customers_bulk_create_customers`](#square_customers_bulk_create_customers) | BulkCreateCustomers | | [`square_customers_bulk_delete_customers`](#square_customers_bulk_delete_customers) | BulkDeleteCustomers | | [`square_customers_bulk_retrieve_customers`](#square_customers_bulk_retrieve_customers) | BulkRetrieveCustomers | | [`square_customers_bulk_update_customers`](#square_customers_bulk_update_customers) | BulkUpdateCustomers | | [`square_customers_bulk_upsert_customer_custom_attributes`](#square_customers_bulk_upsert_customer_custom_attributes) | BulkUpsertCustomerCustomAttributes | | [`square_customers_calculate_loyalty_points`](#square_customers_calculate_loyalty_points) | CalculateLoyaltyPoints | | [`square_customers_cancel_loyalty_promotion`](#square_customers_cancel_loyalty_promotion) | CancelLoyaltyPromotion | | [`square_customers_create_customer`](#square_customers_create_customer) | CreateCustomer | | [`square_customers_create_customer_custom_attribute_definition`](#square_customers_create_customer_custom_attribute_definition) | CreateCustomerCustomAttributeDefinition | | [`square_customers_create_customer_group`](#square_customers_create_customer_group) | CreateCustomerGroup | | [`square_customers_create_loyalty_account`](#square_customers_create_loyalty_account) | CreateLoyaltyAccount | | [`square_customers_create_loyalty_promotion`](#square_customers_create_loyalty_promotion) | CreateLoyaltyPromotion | | [`square_customers_create_loyalty_reward`](#square_customers_create_loyalty_reward) | CreateLoyaltyReward | | [`square_customers_delete_customer`](#square_customers_delete_customer) | DeleteCustomer | | [`square_customers_delete_customer_custom_attribute`](#square_customers_delete_customer_custom_attribute) | DeleteCustomerCustomAttribute | | [`square_customers_delete_customer_custom_attribute_definition`](#square_customers_delete_customer_custom_attribute_definition) | DeleteCustomerCustomAttributeDefinition | | [`square_customers_delete_customer_group`](#square_customers_delete_customer_group) | DeleteCustomerGroup | | [`square_customers_delete_loyalty_reward`](#square_customers_delete_loyalty_reward) | DeleteLoyaltyReward | | [`square_customers_list_customer_custom_attribute_definitions`](#square_customers_list_customer_custom_attribute_definitions) | ListCustomerCustomAttributeDefinitions | | [`square_customers_list_customer_custom_attributes`](#square_customers_list_customer_custom_attributes) | ListCustomerCustomAttributes | | [`square_customers_list_customer_groups`](#square_customers_list_customer_groups) | ListCustomerGroups | | [`square_customers_list_customer_segments`](#square_customers_list_customer_segments) | ListCustomerSegments | | [`square_customers_list_customers`](#square_customers_list_customers) | ListCustomers | | [`square_customers_list_loyalty_promotions`](#square_customers_list_loyalty_promotions) | ListLoyaltyPromotions | | [`square_customers_redeem_loyalty_reward`](#square_customers_redeem_loyalty_reward) | RedeemLoyaltyReward | | [`square_customers_remove_group_from_customer`](#square_customers_remove_group_from_customer) | RemoveGroupFromCustomer | | [`square_customers_retrieve_customer`](#square_customers_retrieve_customer) | RetrieveCustomer | | [`square_customers_retrieve_customer_custom_attribute`](#square_customers_retrieve_customer_custom_attribute) | RetrieveCustomerCustomAttribute | | [`square_customers_retrieve_customer_custom_attribute_definition`](#square_customers_retrieve_customer_custom_attribute_definition) | RetrieveCustomerCustomAttributeDefinition | | [`square_customers_retrieve_customer_group`](#square_customers_retrieve_customer_group) | RetrieveCustomerGroup | | [`square_customers_retrieve_customer_segment`](#square_customers_retrieve_customer_segment) | RetrieveCustomerSegment | | [`square_customers_retrieve_loyalty_account`](#square_customers_retrieve_loyalty_account) | RetrieveLoyaltyAccount | | [`square_customers_retrieve_loyalty_program`](#square_customers_retrieve_loyalty_program) | RetrieveLoyaltyProgram | | [`square_customers_retrieve_loyalty_promotion`](#square_customers_retrieve_loyalty_promotion) | RetrieveLoyaltyPromotion | | [`square_customers_retrieve_loyalty_reward`](#square_customers_retrieve_loyalty_reward) | RetrieveLoyaltyReward | | [`square_customers_search_customers`](#square_customers_search_customers) | SearchCustomers | | [`square_customers_search_loyalty_accounts`](#square_customers_search_loyalty_accounts) | SearchLoyaltyAccounts | | [`square_customers_search_loyalty_events`](#square_customers_search_loyalty_events) | SearchLoyaltyEvents | | [`square_customers_search_loyalty_rewards`](#square_customers_search_loyalty_rewards) | SearchLoyaltyRewards | | [`square_customers_update_customer`](#square_customers_update_customer) | UpdateCustomer | | [`square_customers_update_customer_custom_attribute_definition`](#square_customers_update_customer_custom_attribute_definition) | UpdateCustomerCustomAttributeDefinition | | [`square_customers_update_customer_group`](#square_customers_update_customer_group) | UpdateCustomerGroup | | [`square_customers_upsert_customer_custom_attribute`](#square_customers_upsert_customer_custom_attribute) | UpsertCustomerCustomAttribute | *** ## square\_customers\_accumulate\_loyalty\_points AccumulateLoyaltyPoints **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `account_id` | string | Yes | — | The ID of the target loyalty account. | | `accumulate_points` | object | Yes | — | Provides metadata when the event `type` is `ACCUMULATE_POINTS`. | | `idempotency_key` | string | Yes | — | A unique string that identifies the `AccumulateLoyaltyPoints` request. Keys can be any valid string but must be unique for every request. | | `location_id` | string | Yes | — | The location where the purchase was made. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "account_id": { "type": "string", "description": "The ID of the target [loyalty account](entity:LoyaltyAccount)." }, "accumulate_points": { "type": "object", "description": "Provides metadata when the event `type` is `ACCUMULATE_POINTS`.", "properties": { "loyalty_program_id": { "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram)." }, "points": { "type": "integer", "description": "The number of points accumulated by the event." }, "order_id": { "type": "string", "description": "The ID of the [order](entity:Order) for which the buyer accumulated the points. This field is returned only if the Orders API is used to process orders." } } }, "idempotency_key": { "type": "string", "description": "A unique string that identifies the `AccumulateLoyaltyPoints` request. Keys can be any valid string but must be unique for every request." }, "location_id": { "type": "string", "description": "The [location](entity:Location) where the purchase was made." } }, "required": [ "PCID", "account_id", "accumulate_points", "idempotency_key", "location_id" ] } ``` *** ## square\_customers\_add\_group\_to\_customer AddGroupToCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the customer to add to a group. | | `group_id` | string | Yes | — | The ID of the customer group to add the customer to. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_id": { "type": "string", "description": "The ID of the customer to add to a group." }, "group_id": { "type": "string", "description": "The ID of the customer group to add the customer to." } }, "required": [ "PCID", "customer_id", "group_id" ] } ``` *** ## square\_customers\_adjust\_loyalty\_points AdjustLoyaltyPoints **Parameters:** | Parameter | Type | Required | Default | Description | | | ------------------------ | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | string | Yes | — | The ID of the target loyalty account. | | | `adjust_points` | object | Yes | — | Provides metadata when the event `type` is `ADJUST_POINTS`. | | | `allow_negative_balance` | boolean | null | No | — | Indicates whether to allow a negative adjustment to result in a negative balance. If `true`, a negative balance is allowed when subtracting points. If `false`, Square returns a `BAD_REQUEST` error when subtracting the specified number of points would result in a negative balance. The default value is `false`. | | `idempotency_key` | string | Yes | — | A unique string that identifies this `AdjustLoyaltyPoints` request. Keys can be any valid string, but must be unique for every request. | | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "account_id": { "type": "string", "description": "The ID of the target [loyalty account](entity:LoyaltyAccount)." }, "adjust_points": { "type": "object", "description": "Provides metadata when the event `type` is `ADJUST_POINTS`.", "properties": { "loyalty_program_id": { "type": "string", "description": "The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram)." }, "points": { "type": "integer", "description": "The number of points added or removed." }, "reason": { "type": "string", "description": "The reason for the adjustment of points." } }, "required": [ "points" ] }, "allow_negative_balance": { "type": [ "boolean", "null" ], "description": "Indicates whether to allow a negative adjustment to result in a negative balance. If `true`, a negative balance is allowed when subtracting points. If `false`, Square returns a `BAD_REQUEST` error when subtracting the specified number of points would result in a negative balance. The default value is `false`." }, "idempotency_key": { "type": "string", "description": "A unique string that identifies this `AdjustLoyaltyPoints` request. Keys can be any valid string, but must be unique for every request." } }, "required": [ "PCID", "account_id", "adjust_points", "idempotency_key" ] } ``` *** ## square\_customers\_bulk\_create\_customers BulkCreateCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `customers` | object | Yes | — | A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }` key-value pairs. Each key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) that uniquely identifies the create request. Each value contains the customer data used to create the customer profile. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customers": { "type": "object", "description": "A map of 1 to 100 individual create requests, represented by `idempotency key: { customer data }` key-value pairs. Each key is an [idempotency key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) that uniquely identifies the create request. Each value contains the customer data used to create the customer profile." } }, "required": [ "PCID", "customers" ] } ``` *** ## square\_customers\_bulk\_delete\_customers BulkDeleteCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | --------- | -------- | ------- | ------------------------------------------- | | `customer_ids` | string\[] | Yes | — | The IDs of the customer profiles to delete. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the [customer profiles](entity:Customer) to delete." } }, "required": [ "PCID", "customer_ids" ] } ``` *** ## square\_customers\_bulk\_retrieve\_customers BulkRetrieveCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | --------- | -------- | ------- | --------------------------------------------- | | `customer_ids` | string\[] | Yes | — | The IDs of the customer profiles to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of the [customer profiles](entity:Customer) to retrieve." } }, "required": [ "PCID", "customer_ids" ] } ``` *** ## square\_customers\_bulk\_update\_customers BulkUpdateCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customers` | object | Yes | — | A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }` key-value pairs. Each key is the ID of the customer profile to update. To update a customer profile that was created by merging existing profiles, provide the ID of the newly created profile. Each value contains the updated customer data. Only new or changed fields are required. To add or update a field, specify the new value. To remove a field, specify `null`. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customers": { "type": "object", "description": "A map of 1 to 100 individual update requests, represented by `customer ID: { customer data }` key-value pairs. Each key is the ID of the [customer profile](entity:Customer) to update. To update a customer profile that was created by merging existing profiles, provide the ID of the newly created profile. Each value contains the updated customer data. Only new or changed fields are required. To add or update a field, specify the new value. To remove a field, specify `null`." } }, "required": [ "PCID", "customers" ] } ``` *** ## square\_customers\_bulk\_upsert\_customer\_custom\_attributes BulkUpsertCustomerCustomAttributes **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 `BulkUpsertCustomerCustomAttributes` 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 `BulkUpsertCustomerCustomAttributes` request and the information needed to create or update a custom attribute." } }, "required": [ "PCID", "values" ] } ``` *** ## square\_customers\_calculate\_loyalty\_points CalculateLoyaltyPoints **Parameters:** | Parameter | Type | Required | Default | Description | | | -------------------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `program_id` | string | Yes | — | The ID of the loyalty program, which defines the rules for accruing points. | | | `loyalty_account_id` | string | null | No | — | The ID of the target loyalty account. Optionally specify this field if your application uses the Orders API to process orders. If specified, the `promotion_points` field in the response shows the number of points the buyer would earn from the purchase. In this case, Square uses the account ID to determine whether the promotion's `trigger_limit` (the maximum number of times that a buyer can trigger the promotion) has been reached. If not specified, the `promotion_points` field shows the number of points the purchase qualifies for regardless of the trigger limit. | | `order_id` | string | null | No | — | The order ID for which to calculate the points. Specify this field if your application uses the Orders API to process orders. Otherwise, specify the `transaction_amount_money`. | | `transaction_amount_money` | object | No | — | Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information. | | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "program_id": { "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram), which defines the rules for accruing points." }, "loyalty_account_id": { "type": [ "string", "null" ], "description": "The ID of the target [loyalty account](entity:LoyaltyAccount). Optionally specify this field if your application uses the Orders API to process orders. If specified, the `promotion_points` field in the response shows the number of points the buyer would earn from the purchase. In this case, Square uses the account ID to determine whether the promotion's `trigger_limit` (the maximum number of times that a buyer can trigger the promotion) has been reached. If not specified, the `promotion_points` field shows the number of points the purchase qualifies for regardless of the trigger limit." }, "order_id": { "type": [ "string", "null" ], "description": "The [order](entity:Order) ID for which to calculate the points. Specify this field if your application uses the Orders API to process orders. Otherwise, specify the `transaction_amount_money`." }, "transaction_amount_money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.", "properties": { "amount": { "type": "integer", "description": "The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case." }, "currency": { "type": "string", "description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).", "enum": [ "UNKNOWN_CURRENCY", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SLE", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XTS", "XXX", "YER", "ZAR", "ZMK", "ZMW", "BTC", "XUS" ] } } } }, "required": [ "PCID", "program_id" ] } ``` *** ## square\_customers\_cancel\_loyalty\_promotion CancelLoyaltyPromotion **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | `promotion_id` | string | Yes | — | The ID of the loyalty promotion to cancel. You can cancel a promotion that has an `ACTIVE` or `SCHEDULED` status. | | `program_id` | string | Yes | — | The ID of the base loyalty program. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "promotion_id": { "type": "string", "description": "The ID of the [loyalty promotion](entity:LoyaltyPromotion) to cancel. You can cancel a promotion that has an `ACTIVE` or `SCHEDULED` status." }, "program_id": { "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram)." } }, "required": [ "PCID", "promotion_id", "program_id" ] } ``` *** ## square\_customers\_create\_customer CreateCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | object | No | — | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | | `birthday` | string | No | — | The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified. | | `company_name` | string | No | — | A business name associated with the customer profile. The maximum length for this value is 500 characters. | | `email_address` | string | No | — | The email address associated with the customer profile. The maximum length for this value is 254 characters. | | `family_name` | string | No | — | The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters. | | `given_name` | string | No | — | The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters. | | `idempotency_key` | string | No | — | The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). | | `nickname` | string | No | — | A nickname for the customer profile. The maximum length for this value is 100 characters. | | `note` | string | No | — | A custom note associated with the customer profile. | | `phone_number` | string | No | — | The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number). | | `reference_id` | string | No | — | An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters. | | `tax_ids` | object | No | — | Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "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).", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields)." }, "address_line_2": { "type": "string", "description": "The second line of the address, if any." }, "address_line_3": { "type": "string", "description": "The third line of the address, if any." }, "locality": { "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "sublocality": { "type": "string", "description": "A civil region within the address's `locality`, if any." }, "sublocality_2": { "type": "string", "description": "A civil region within the address's `sublocality`, if any." }, "sublocality_3": { "type": "string", "description": "A civil region within the address's `sublocality_2`, if any." }, "administrative_district_level_1": { "type": "string", "description": "A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "administrative_district_level_2": { "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county." }, "administrative_district_level_3": { "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`, if any." }, "postal_code": { "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "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" ] }, "first_name": { "type": "string", "description": "Optional first name when it's representing recipient." }, "last_name": { "type": "string", "description": "Optional last name when it's representing recipient." } } }, "birthday": { "type": "string", "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified." }, "company_name": { "type": "string", "description": "A business name associated with the customer profile. The maximum length for this value is 500 characters." }, "email_address": { "type": "string", "description": "The email address associated with the customer profile. The maximum length for this value is 254 characters." }, "family_name": { "type": "string", "description": "The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters." }, "given_name": { "type": "string", "description": "The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters." }, "idempotency_key": { "type": "string", "description": "The idempotency key for the request.\tFor more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." }, "nickname": { "type": "string", "description": "A nickname for the customer profile. The maximum length for this value is 100 characters." }, "note": { "type": "string", "description": "A custom note associated with the customer profile." }, "phone_number": { "type": "string", "description": "The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)." }, "reference_id": { "type": "string", "description": "An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters." }, "tax_ids": { "type": "object", "description": "Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).", "properties": { "eu_vat": { "type": "string", "description": "The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only." } } } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_create\_customer\_custom\_attribute\_definition CreateCustomerCustomAttributeDefinition **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\_customers\_create\_customer\_group CreateCustomerGroup **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `group` | object | Yes | — | Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale. | | `idempotency_key` | string | No | — | The idempotency key for the request. 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" }, "group": { "type": "object", "description": "Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.", "properties": { "id": { "type": "string", "description": "A unique Square-generated ID for the customer group." }, "name": { "type": "string", "description": "The name of the customer group." }, "created_at": { "type": "string", "description": "The timestamp when the customer group was created, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the customer group was last updated, in RFC 3339 format." } }, "required": [ "name" ] }, "idempotency_key": { "type": "string", "description": "The idempotency key for the request. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." } }, "required": [ "PCID", "group" ] } ``` *** ## square\_customers\_create\_loyalty\_account CreateLoyaltyAccount **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `idempotency_key` | string | Yes | — | A unique string that identifies this `CreateLoyaltyAccount` request. Keys can be any valid string, but must be unique for every request. | | `loyalty_account` | object | Yes | — | Describes a loyalty account in a loyalty program. For more information, see [Create and Retrieve Loyalty Accounts](https://developer.squareup.com/docs/loyalty-api/loyalty-accounts). | ```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 this `CreateLoyaltyAccount` request. Keys can be any valid string, but must be unique for every request." }, "loyalty_account": { "type": "object", "description": "Describes a loyalty account in a [loyalty program](entity:LoyaltyProgram). For more information, see [Create and Retrieve Loyalty Accounts](https://developer.squareup.com/docs/loyalty-api/loyalty-accounts).", "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the loyalty account." }, "program_id": { "type": "string", "description": "The Square-assigned ID of the [loyalty program](entity:LoyaltyProgram) to which the account belongs." }, "balance": { "type": "integer", "description": "The available point balance in the loyalty account. If points are scheduled to expire, they are listed in the `expiring_point_deadlines` field. Your application should be able to handle loyalty accounts that have a negative point balance (`balance` is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange." }, "lifetime_points": { "type": "integer", "description": "The total points accrued during the lifetime of the account." }, "customer_id": { "type": "string", "description": "The Square-assigned ID of the [customer](entity:Customer) that is associated with the account." }, "enrolled_at": { "type": "string", "description": "The timestamp when the buyer joined the loyalty program, in RFC 3339 format. This field is used to display the **Enrolled On** or **Member Since** date in first-party Square products. If this field is not set in a `CreateLoyaltyAccount` request, Square populates it after the buyer's first action on their account (when `AccumulateLoyaltyPoints` or `CreateLoyaltyReward` is called). In first-party flows, Square populates the field when the buyer agrees to the terms of service on Square Point of Sale. If this field is set in a `CreateLoyaltyAccount` request, it is meant to be used when there is a loyalty migration from another system and into Square. In that case, the timestamp can reflect when the buyer originally enrolled in the previous system. It may represent a current or past date, but cannot be set in the future. Note: Setting this field in this scenario does not, by itself, impact the first-party enrollment flow on Square Point of Sale." }, "created_at": { "type": "string", "description": "The timestamp when the loyalty account was created, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the loyalty account was last updated, in RFC 3339 format." }, "mapping": { "type": "object", "description": "Represents the mapping that associates a loyalty account with a buyer. Currently, a loyalty account can only be mapped to a buyer by phone number. For more information, see [Loyalty Overview](https://developer.squareup.com/docs/loyalty/overview)." }, "expiring_point_deadlines": { "type": "array", "items": { "type": "object" }, "description": "The schedule for when points expire in the loyalty account balance. This field is present only if the account has points that are scheduled to expire. The total number of points in this field equals the number of points in the `balance` field." } }, "required": [ "program_id" ] } }, "required": [ "PCID", "idempotency_key", "loyalty_account" ] } ``` *** ## square\_customers\_create\_loyalty\_promotion CreateLoyaltyPromotion **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `program_id` | string | Yes | — | The ID of the loyalty program to associate with the promotion. To get the program ID, call RetrieveLoyaltyProgram using the `main` keyword. | | `idempotency_key` | string | Yes | — | A unique identifier for this request, which is used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). | | `loyalty_promotion` | object | Yes | — | Represents a promotion for a loyalty program. Loyalty promotions enable buyers to earn extra points on top of those earned from the base program. A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "program_id": { "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram) to associate with the promotion. To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword." }, "idempotency_key": { "type": "string", "description": "A unique identifier for this request, which is used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)." }, "loyalty_promotion": { "type": "object", "description": "Represents a promotion for a [loyalty program](entity:LoyaltyProgram). Loyalty promotions enable buyers to earn extra points on top of those earned from the base program. A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status.", "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the promotion." }, "name": { "type": "string", "description": "The name of the promotion." }, "incentive": { "type": "object", "description": "Represents how points for a [loyalty promotion](entity:LoyaltyPromotion) are calculated, either by multiplying the points earned from the base program or by adding a specified number of points to the points earned from the base program." }, "available_time": { "type": "object", "description": "Represents scheduling information that determines when purchases can qualify to earn points from a [loyalty promotion](entity:LoyaltyPromotion)." }, "trigger_limit": { "type": "object", "description": "Represents the number of times a buyer can earn points during a [loyalty promotion](entity:LoyaltyPromotion). If this field is not set, buyers can trigger the promotion an unlimited number of times to earn points during the time that the promotion is available. A purchase that is disqualified from earning points because of this limit might qualify for another active promotion." }, "status": { "type": "string", "description": "Indicates the status of a [loyalty promotion](entity:LoyaltyPromotion).", "enum": [ "ACTIVE", "ENDED", "CANCELED", "SCHEDULED" ] }, "created_at": { "type": "string", "description": "The timestamp of when the promotion was created, in RFC 3339 format." }, "canceled_at": { "type": "string", "description": "The timestamp of when the promotion was canceled, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the promotion was last updated, in RFC 3339 format." }, "loyalty_program_id": { "type": "string", "description": "The ID of the [loyalty program](entity:LoyaltyProgram) associated with the promotion." }, "minimum_spend_amount_money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information." }, "qualifying_item_variation_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of any qualifying `ITEM_VARIATION` [catalog objects](entity:CatalogObject). If specified, the purchase must include at least one of these items to qualify for the promotion. This option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule. With `SPEND` accrual rules, make sure that qualifying promotional items are not excluded. You can specify `qualifying_item_variation_ids` or `qualifying_category_ids` for a given promotion, but not both." }, "qualifying_category_ids": { "type": "array", "items": { "type": "string" }, "description": "The IDs of any qualifying `CATEGORY` [catalog objects](entity:CatalogObject). If specified, the purchase must include at least one item from one of these categories to qualify for the promotion. This option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule. With `SPEND` accrual rules, make sure that qualifying promotional items are not excluded. You can specify `qualifying_category_ids` or `qualifying_item_variation_ids` for a promotion, but not both." } }, "required": [ "name", "incentive", "available_time" ] } }, "required": [ "PCID", "program_id", "idempotency_key", "loyalty_promotion" ] } ``` *** ## square\_customers\_create\_loyalty\_reward CreateLoyaltyReward **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `idempotency_key` | string | Yes | — | A unique string that identifies this `CreateLoyaltyReward` request. Keys can be any valid string, but must be unique for every request. | | `reward` | object | Yes | — | Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see [Manage loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards). | ```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 this `CreateLoyaltyReward` request. Keys can be any valid string, but must be unique for every request." }, "reward": { "type": "object", "description": "Represents a contract to redeem loyalty points for a [reward tier](entity:LoyaltyProgramRewardTier) discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see [Manage loyalty rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards).", "properties": { "id": { "type": "string", "description": "The Square-assigned ID of the loyalty reward." }, "status": { "type": "string", "description": "The status of the loyalty reward.", "enum": [ "ISSUED", "REDEEMED", "DELETED" ] }, "loyalty_account_id": { "type": "string", "description": "The Square-assigned ID of the [loyalty account](entity:LoyaltyAccount) to which the reward belongs." }, "reward_tier_id": { "type": "string", "description": "The Square-assigned ID of the [reward tier](entity:LoyaltyProgramRewardTier) used to create the reward." }, "points": { "type": "integer", "description": "The number of loyalty points used for the reward." }, "order_id": { "type": "string", "description": "The Square-assigned ID of the [order](entity:Order) to which the reward is attached." }, "created_at": { "type": "string", "description": "The timestamp when the reward was created, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the reward was last updated, in RFC 3339 format." }, "redeemed_at": { "type": "string", "description": "The timestamp when the reward was redeemed, in RFC 3339 format." } }, "required": [ "loyalty_account_id", "reward_tier_id" ] } }, "required": [ "PCID", "idempotency_key", "reward" ] } ``` *** ## square\_customers\_delete\_customer DeleteCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the customer to delete. | | `version` | integer | No | — | The current version of the customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile). | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_id": { "type": "string", "description": "The ID of the customer to delete." }, "version": { "type": "integer", "description": "The current version of the customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile)." } }, "required": [ "PCID", "customer_id" ] } ``` *** ## square\_customers\_delete\_customer\_custom\_attribute DeleteCustomerCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the target customer profile. | | `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" }, "customer_id": { "type": "string", "description": "The ID of the target [customer profile](entity:Customer)." }, "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", "customer_id", "key" ] } ``` *** ## square\_customers\_delete\_customer\_custom\_attribute\_definition DeleteCustomerCustomAttributeDefinition **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\_customers\_delete\_customer\_group DeleteCustomerGroup **Parameters:** | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------------------- | | `group_id` | string | Yes | — | The ID of the customer group to delete. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "group_id": { "type": "string", "description": "The ID of the customer group to delete." } }, "required": [ "PCID", "group_id" ] } ``` *** ## square\_customers\_delete\_loyalty\_reward DeleteLoyaltyReward **Parameters:** | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------- | | `reward_id` | string | Yes | — | The ID of the loyalty reward to delete. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "reward_id": { "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to delete." } }, "required": [ "PCID", "reward_id" ] } ``` *** ## square\_customers\_list\_customer\_custom\_attribute\_definitions ListCustomerCustomAttributeDefinitions **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | integer | No | — | The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `cursor` | string | No | — | The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "cursor": { "type": "string", "description": "The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_list\_customer\_custom\_attributes ListCustomerCustomAttributes **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the target customer profile. | | `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" }, "customer_id": { "type": "string", "description": "The ID of the target [customer profile](entity:Customer)." }, "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", "customer_id" ] } ``` *** ## square\_customers\_list\_customer\_groups ListCustomerGroups **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | integer | No | — | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. 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" }, "cursor": { "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_list\_customer\_segments ListCustomerSegments **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cursor` | string | No | — | A pagination cursor returned by previous calls to `ListCustomerSegments`. This cursor is used to retrieve the next set of query results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | integer | No | — | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. 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" }, "cursor": { "type": "string", "description": "A pagination cursor returned by previous calls to `ListCustomerSegments`. This cursor is used to retrieve the next set of query results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 50, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_list\_customers ListCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | integer | No | — | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `sort_field` | string | No | — | Indicates how customers should be sorted. The default value is `DEFAULT`. | | `sort_order` | string | No | — | Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`. | | `count` | boolean | No | — | Indicates whether to return the total count of customers in the `count` field of the response. The default value is `false`. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "cursor": { "type": "string", "description": "A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "sort_field": { "type": "string", "description": "Indicates how customers should be sorted. The default value is `DEFAULT`.", "enum": [ "DEFAULT", "CREATED_AT" ] }, "sort_order": { "type": "string", "description": "Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`.", "enum": [ "DESC", "ASC" ] }, "count": { "type": "boolean", "description": "Indicates whether to return the total count of customers in the `count` field of the response. The default value is `false`." } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_list\_loyalty\_promotions ListLoyaltyPromotions **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `program_id` | string | Yes | — | The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the `main` keyword. | | `status` | string | No | — | The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned. | | `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). | | `limit` | integer | No | — | The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. 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" }, "program_id": { "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword." }, "status": { "type": "string", "description": "The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned.", "enum": [ "ACTIVE", "ENDED", "CANCELED", "SCHEDULED" ] }, "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)." }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." } }, "required": [ "PCID", "program_id" ] } ``` *** ## square\_customers\_redeem\_loyalty\_reward RedeemLoyaltyReward **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `reward_id` | string | Yes | — | The ID of the loyalty reward to redeem. | | `idempotency_key` | string | Yes | — | A unique string that identifies this `RedeemLoyaltyReward` request. Keys can be any valid string, but must be unique for every request. | | `location_id` | string | Yes | — | The ID of the location where the reward is redeemed. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "reward_id": { "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to redeem." }, "idempotency_key": { "type": "string", "description": "A unique string that identifies this `RedeemLoyaltyReward` request. Keys can be any valid string, but must be unique for every request." }, "location_id": { "type": "string", "description": "The ID of the [location](entity:Location) where the reward is redeemed." } }, "required": [ "PCID", "reward_id", "idempotency_key", "location_id" ] } ``` *** ## square\_customers\_remove\_group\_from\_customer RemoveGroupFromCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | --------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the customer to remove from the group. | | `group_id` | string | Yes | — | The ID of the customer group to remove the customer from. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_id": { "type": "string", "description": "The ID of the customer to remove from the group." }, "group_id": { "type": "string", "description": "The ID of the customer group to remove the customer from." } }, "required": [ "PCID", "customer_id", "group_id" ] } ``` *** ## square\_customers\_retrieve\_customer RetrieveCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ----------------------------------- | | `customer_id` | string | Yes | — | The ID of the customer to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_id": { "type": "string", "description": "The ID of the customer to retrieve." } }, "required": [ "PCID", "customer_id" ] } ``` *** ## square\_customers\_retrieve\_customer\_custom\_attribute RetrieveCustomerCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | ----------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the target customer profile. | | `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" }, "customer_id": { "type": "string", "description": "The ID of the target [customer profile](entity:Customer)." }, "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", "customer_id", "key" ] } ``` *** ## square\_customers\_retrieve\_customer\_custom\_attribute\_definition RetrieveCustomerCustomAttributeDefinition **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\_customers\_retrieve\_customer\_group RetrieveCustomerGroup **Parameters:** | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | ----------------------------------------- | | `group_id` | string | Yes | — | The ID of the customer group to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "group_id": { "type": "string", "description": "The ID of the customer group to retrieve." } }, "required": [ "PCID", "group_id" ] } ``` *** ## square\_customers\_retrieve\_customer\_segment RetrieveCustomerSegment **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | --------------------------------------------- | | `segment_id` | string | Yes | — | The Square-issued ID of the customer segment. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "segment_id": { "type": "string", "description": "The Square-issued ID of the customer segment." } }, "required": [ "PCID", "segment_id" ] } ``` *** ## square\_customers\_retrieve\_loyalty\_account RetrieveLoyaltyAccount **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | ------------------------------------------ | | `account_id` | string | Yes | — | The ID of the loyalty account to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "account_id": { "type": "string", "description": "The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve." } }, "required": [ "PCID", "account_id" ] } ``` *** ## square\_customers\_retrieve\_loyalty\_program RetrieveLoyaltyProgram **Parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `program_id` | string | Yes | — | The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "program_id": { "type": "string", "description": "The ID of the loyalty program or the keyword `main`. Either value can be used to retrieve the single loyalty program that belongs to the seller." } }, "required": [ "PCID", "program_id" ] } ``` *** ## square\_customers\_retrieve\_loyalty\_promotion RetrieveLoyaltyPromotion **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `promotion_id` | string | Yes | — | The ID of the loyalty promotion to retrieve. | | `program_id` | string | Yes | — | The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the `main` keyword. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "promotion_id": { "type": "string", "description": "The ID of the [loyalty promotion](entity:LoyaltyPromotion) to retrieve." }, "program_id": { "type": "string", "description": "The ID of the base [loyalty program](entity:LoyaltyProgram). To get the program ID, call [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram) using the `main` keyword." } }, "required": [ "PCID", "promotion_id", "program_id" ] } ``` *** ## square\_customers\_retrieve\_loyalty\_reward RetrieveLoyaltyReward **Parameters:** | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ----------------------------------------- | | `reward_id` | string | Yes | — | The ID of the loyalty reward to retrieve. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "reward_id": { "type": "string", "description": "The ID of the [loyalty reward](entity:LoyaltyReward) to retrieve." } }, "required": [ "PCID", "reward_id" ] } ``` *** ## square\_customers\_search\_customers SearchCustomers **Parameters:** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `count` | boolean | No | — | Indicates whether to return the total count of matching customers in the `count` field of the response. The default value is `false`. | | `cursor` | string | No | — | Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `limit` | integer | No | — | The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). | | `query` | object | No | — | Represents filtering and sorting criteria for a SearchCustomers request. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "count": { "type": "boolean", "description": "Indicates whether to return the total count of matching customers in the `count` field of the response. The default value is `false`." }, "cursor": { "type": "string", "description": "Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "limit": { "type": "integer", "description": "The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is 100. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "query": { "type": "object", "description": "Represents filtering and sorting criteria for a [SearchCustomers](api-endpoint:Customers-SearchCustomers) request.", "properties": { "filter": { "type": "object", "description": "Represents the filtering criteria in a [search query](entity:CustomerQuery) that defines how to filter customer profiles returned in [SearchCustomers](api-endpoint:Customers-SearchCustomers) results." }, "sort": { "type": "object", "description": "Represents the sorting criteria in a [search query](entity:CustomerQuery) that defines how to sort customer profiles returned in [SearchCustomers](api-endpoint:Customers-SearchCustomers) results." } } } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_search\_loyalty\_accounts SearchLoyaltyAccounts **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 the 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 results to include in the response. The default value is 30. | | `query` | object | No | — | The search criteria for the loyalty accounts. | ```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 the 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 results to include in the response. The default value is 30." }, "query": { "type": "object", "description": "The search criteria for the loyalty accounts.", "properties": { "mappings": { "type": "array", "items": { "type": "object" }, "description": "The set of mappings to use in the loyalty account search. This cannot be combined with `customer_ids`. Max: 30 mappings" }, "customer_ids": { "type": "array", "items": { "type": "string" }, "description": "The set of customer IDs to use in the loyalty account search. This cannot be combined with `mappings`. Max: 30 customer IDs" } } } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_search\_loyalty\_events SearchLoyaltyEvents **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). | | `limit` | integer | No | — | The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events. | | `query` | object | No | — | Represents a query used to search for loyalty events. | ```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)." }, "limit": { "type": "integer", "description": "The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events." }, "query": { "type": "object", "description": "Represents a query used to search for loyalty events.", "properties": { "filter": { "type": "object", "description": "The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them." } } } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_search\_loyalty\_rewards SearchLoyaltyRewards **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 the 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 results to return in the response. The default value is 30. | | `query` | object | No | — | The set of search requirements. | ```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 the 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 results to return in the response. The default value is 30." }, "query": { "type": "object", "description": "The set of search requirements.", "properties": { "loyalty_account_id": { "type": "string", "description": "The ID of the [loyalty account](entity:LoyaltyAccount) to which the loyalty reward belongs." }, "status": { "type": "string", "description": "The status of the loyalty reward.", "enum": [ "ISSUED", "REDEEMED", "DELETED" ] } }, "required": [ "loyalty_account_id" ] } }, "required": [ "PCID" ] } ``` *** ## square\_customers\_update\_customer UpdateCustomer **Parameters:** | Parameter | Type | Required | Default | Description | | | --------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the customer to update. | | | `address` | object | No | — | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). | | | `birthday` | string | null | No | — | The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified. | | `company_name` | string | null | No | — | A business name associated with the customer profile. The maximum length for this value is 500 characters. | | `email_address` | string | null | No | — | The email address associated with the customer profile. The maximum length for this value is 254 characters. | | `family_name` | string | null | No | — | The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters. | | `given_name` | string | null | No | — | The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters. | | `nickname` | string | null | No | — | A nickname for the customer profile. The maximum length for this value is 100 characters. | | `note` | string | null | No | — | A custom note associated with the customer profile. | | `phone_number` | string | null | No | — | The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number). | | `reference_id` | string | null | No | — | An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters. | | `tax_ids` | object | No | — | Represents the tax ID associated with a customer profile. The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids). | | | `version` | integer | No | — | The current version of the customer profile. As a best practice, you should include this field to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Update a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile). | | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "customer_id": { "type": "string", "description": "The ID of the customer to update." }, "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).", "properties": { "address_line_1": { "type": "string", "description": "The first line of the address. Fields that start with `address_line` provide the address's most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields)." }, "address_line_2": { "type": "string", "description": "The second line of the address, if any." }, "address_line_3": { "type": "string", "description": "The third line of the address, if any." }, "locality": { "type": "string", "description": "The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "sublocality": { "type": "string", "description": "A civil region within the address's `locality`, if any." }, "sublocality_2": { "type": "string", "description": "A civil region within the address's `sublocality`, if any." }, "sublocality_3": { "type": "string", "description": "A civil region within the address's `sublocality_2`, if any." }, "administrative_district_level_1": { "type": "string", "description": "A civil entity within the address's country. In the US, this is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "administrative_district_level_2": { "type": "string", "description": "A civil entity within the address's `administrative_district_level_1`. In the US, this is the county." }, "administrative_district_level_3": { "type": "string", "description": "A civil entity within the address's `administrative_district_level_2`, if any." }, "postal_code": { "type": "string", "description": "The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." }, "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" ] }, "first_name": { "type": "string", "description": "Optional first name when it's representing recipient." }, "last_name": { "type": "string", "description": "Optional last name when it's representing recipient." } } }, "birthday": { "type": [ "string", "null" ], "description": "The birthday associated with the customer profile, in `YYYY-MM-DD` or `MM-DD` format. For example, specify `1998-09-21` for September 21, 1998, or `09-21` for September 21. Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the specified birth year or `0000` if a birth year is not specified." }, "company_name": { "type": [ "string", "null" ], "description": "A business name associated with the customer profile. The maximum length for this value is 500 characters." }, "email_address": { "type": [ "string", "null" ], "description": "The email address associated with the customer profile. The maximum length for this value is 254 characters." }, "family_name": { "type": [ "string", "null" ], "description": "The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters." }, "given_name": { "type": [ "string", "null" ], "description": "The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters." }, "nickname": { "type": [ "string", "null" ], "description": "A nickname for the customer profile. The maximum length for this value is 100 characters." }, "note": { "type": [ "string", "null" ], "description": "A custom note associated with the customer profile." }, "phone_number": { "type": [ "string", "null" ], "description": "The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional `+` prefix and country code. For more information, see [Customer phone numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number)." }, "reference_id": { "type": [ "string", "null" ], "description": "An optional second ID used to associate the customer profile with an entity in another system. The maximum length for this value is 100 characters." }, "tax_ids": { "type": "object", "description": "Represents the tax ID associated with a [customer profile](entity:Customer). The corresponding `tax_ids` field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see [Customer tax IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).", "properties": { "eu_vat": { "type": "string", "description": "The EU VAT identification number for the customer. For example, `IE3426675K`. The ID can contain alphanumeric characters only." } } }, "version": { "type": "integer", "description": "The current version of the customer profile. As a best practice, you should include this field to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Update a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile)." } }, "required": [ "PCID", "customer_id" ] } ``` *** ## square\_customers\_update\_customer\_custom\_attribute\_definition UpdateCustomerCustomAttributeDefinition **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\_customers\_update\_customer\_group UpdateCustomerGroup **Parameters:** | Parameter | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `group_id` | string | Yes | — | The ID of the customer group to update. | | `group` | object | Yes | — | Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale. | ```json theme={null} { "type": "object", "properties": { "PCID": { "type": "string", "description": "Pink Connect ID for the authenticated connection" }, "group_id": { "type": "string", "description": "The ID of the customer group to update." }, "group": { "type": "object", "description": "Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.", "properties": { "id": { "type": "string", "description": "A unique Square-generated ID for the customer group." }, "name": { "type": "string", "description": "The name of the customer group." }, "created_at": { "type": "string", "description": "The timestamp when the customer group was created, in RFC 3339 format." }, "updated_at": { "type": "string", "description": "The timestamp when the customer group was last updated, in RFC 3339 format." } }, "required": [ "name" ] } }, "required": [ "PCID", "group_id", "group" ] } ``` *** ## square\_customers\_upsert\_customer\_custom\_attribute UpsertCustomerCustomAttribute **Parameters:** | Parameter | Type | Required | Default | Description | | | ------------------ | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer_id` | string | Yes | — | The ID of the target customer profile. | | | `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" }, "customer_id": { "type": "string", "description": "The ID of the target [customer profile](entity:Customer)." }, "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", "customer_id", "key", "custom_attribute" ] } ```