/square-customers | Type: Application | PCID required: Yes
Tools
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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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 that uniquely identifies the create request. Each value contains the customer data used to create the customer profile. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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 for more information. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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 control. For more information, see Delete a customer profile. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
query | object | No | — | Represents filtering and sorting criteria for a SearchCustomers request. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. |
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. |
Show inputSchema
Show inputSchema
{
"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. | |
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. |
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. | |
version | integer | No | — | The current version of the customer profile. As a best practice, you should include this field to enable optimistic concurrency control. For more information, see Update a customer profile. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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. |
Show inputSchema
Show inputSchema
{
"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"
]
}