customers_api = client.customers
CustomersApi
- List Customers
- Create Customer
- Bulk Create Customers
- Bulk Delete Customers
- Bulk Retrieve Customers
- Bulk Update Customers
- Search Customers
- Delete Customer
- Retrieve Customer
- Update Customer
- Create Customer Card
- Delete Customer Card
- Remove Group From Customer
- Add Group to Customer
Lists customer profiles associated with a Square account.
Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.
def list_customers(self,
cursor=None,
limit=None,
sort_field=None,
sort_order=None,
count=False)
Parameter | Type | Tags | Description |
---|---|---|---|
cursor |
str |
Query, Optional | 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 |
int |
Query, Optional | 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 |
str (Customer Sort Field) |
Query, Optional | Indicates how customers should be sorted. The default value is DEFAULT . |
sort_order |
str (Sort Order) |
Query, Optional | Indicates whether customers should be sorted in ascending (ASC ) ordescending ( DESC ) order.The default value is ASC . |
count |
bool |
Query, Optional | Indicates whether to return the total count of customers in the count field of the response.The default value is false .Default: False |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type List Customers Response
.
count = False
result = customers_api.list_customers(
count=count
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Creates a new customer for a business.
You must provide at least one of the following values in your request to this endpoint:
given_name
family_name
company_name
email_address
phone_number
def create_customer(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Create Customer Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Create Customer Response
.
body = {
'given_name': 'Amelia',
'family_name': 'Earhart',
'email_address': '[email protected]',
'address': {
'address_line_1': '500 Electric Ave',
'address_line_2': 'Suite 600',
'locality': 'New York',
'administrative_district_level_1': 'NY',
'postal_code': '10003',
'country': 'US'
},
'phone_number': '+1-212-555-4240',
'reference_id': 'YOUR_REFERENCE_ID',
'note': 'a customer'
}
result = customers_api.create_customer(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Creates multiple customer profiles for a business.
This endpoint takes a map of individual create requests and returns a map of responses.
You must provide at least one of the following values in each create request:
given_name
family_name
company_name
email_address
phone_number
def bulk_create_customers(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Bulk Create Customers Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Bulk Create Customers Response
.
body = {
'customers': {
'8bb76c4f-e35d-4c5b-90de-1194cd9179f0': {
'given_name': 'Amelia',
'family_name': 'Earhart',
'email_address': '[email protected]',
'address': {
'address_line_1': '500 Electric Ave',
'address_line_2': 'Suite 600',
'locality': 'New York',
'administrative_district_level_1': 'NY',
'postal_code': '10003',
'country': 'US'
},
'phone_number': '+1-212-555-4240',
'reference_id': 'YOUR_REFERENCE_ID',
'note': 'a customer'
},
'd1689f23-b25d-4932-b2f0-aed00f5e2029': {
'given_name': 'Marie',
'family_name': 'Curie',
'email_address': '[email protected]',
'address': {
'address_line_1': '500 Electric Ave',
'address_line_2': 'Suite 601',
'locality': 'New York',
'administrative_district_level_1': 'NY',
'postal_code': '10003',
'country': 'US'
},
'phone_number': '+1-212-444-4240',
'reference_id': 'YOUR_REFERENCE_ID',
'note': 'another customer'
}
}
}
result = customers_api.bulk_create_customers(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Deletes multiple customer profiles.
The endpoint takes a list of customer IDs and returns a map of responses.
def bulk_delete_customers(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Bulk Delete Customers Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Bulk Delete Customers Response
.
body = {
'customer_ids': [
'8DDA5NZVBZFGAX0V3HPF81HHE0',
'N18CPRVXR5214XPBBA6BZQWF3C',
'2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
]
}
result = customers_api.bulk_delete_customers(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Retrieves multiple customer profiles.
This endpoint takes a list of customer IDs and returns a map of responses.
def bulk_retrieve_customers(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Bulk Retrieve Customers Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Bulk Retrieve Customers Response
.
body = {
'customer_ids': [
'8DDA5NZVBZFGAX0V3HPF81HHE0',
'N18CPRVXR5214XPBBA6BZQWF3C',
'2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
]
}
result = customers_api.bulk_retrieve_customers(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Updates multiple customer profiles.
This endpoint takes a map of individual update requests and returns a map of responses.
You cannot use this endpoint to change cards on file. To make changes, use the Cards API or Gift Cards API.
def bulk_update_customers(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Bulk Update Customers Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Bulk Update Customers Response
.
body = {
'customers': {
'8DDA5NZVBZFGAX0V3HPF81HHE0': {
'email_address': '[email protected]',
'phone_number': 'phone_number2',
'note': 'updated customer note',
'version': 2
},
'N18CPRVXR5214XPBBA6BZQWF3C': {
'given_name': 'Marie',
'family_name': 'Curie',
'version': 0
}
}
}
result = customers_api.bulk_update_customers(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Searches the customer profiles associated with a Square account using one or more supported query filters.
Calling SearchCustomers
without any explicit query filter returns all
customer profiles ordered alphabetically based on given_name
and
family_name
.
Under normal operating conditions, newly created or updated customer profiles become available for the search operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.
def search_customers(self,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
body |
Search Customers Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Search Customers Response
.
body = {
'limit': 2,
'query': {
'filter': {
'creation_source': {
'values': [
'THIRD_PARTY'
],
'rule': 'INCLUDE'
},
'created_at': {
'start_at': '2018-01-01T00:00:00-00:00',
'end_at': '2018-02-01T00:00:00-00:00'
},
'email_address': {
'fuzzy': 'example.com'
},
'group_ids': {
'all': [
'545AXB44B4XXWMVQ4W8SBT3HHF'
]
}
},
'sort': {
'field': 'CREATED_AT',
'order': 'ASC'
}
}
}
result = customers_api.search_customers(body)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Deletes a customer profile from a business. This operation also unlinks any associated cards on file.
To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
def delete_customer(self,
customer_id,
version=None)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer to delete. |
version |
long|int |
Query, Optional | 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. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Delete Customer Response
.
customer_id = 'customer_id8'
result = customers_api.delete_customer(customer_id)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Returns details for a single customer.
def retrieve_customer(self,
customer_id)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer to retrieve. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Retrieve Customer Response
.
customer_id = 'customer_id8'
result = customers_api.retrieve_customer(customer_id)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request.
To add or update a field, specify the new value. To remove a field, specify null
.
To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.
You cannot use this endpoint to change cards on file. To make changes, use the Cards API or Gift Cards API.
def update_customer(self,
customer_id,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer to update. |
body |
Update Customer Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Update Customer Response
.
customer_id = 'customer_id8'
body = {
'email_address': '[email protected]',
'phone_number': 'phone_number2',
'note': 'updated customer note',
'version': 2
}
result = customers_api.update_customer(
customer_id,
body
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
This endpoint is deprecated.
Adds a card on file to an existing customer.
As with charges, calls to CreateCustomerCard
are idempotent. Multiple
calls with the same card nonce return the same card record that was created
with the provided nonce during the first call.
def create_customer_card(self,
customer_id,
body)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The Square ID of the customer profile the card is linked to. |
body |
Create Customer Card Request |
Body, Required | An object containing the fields to POST for the request. See the corresponding object definition for field details. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Create Customer Card Response
.
customer_id = 'customer_id8'
body = {
'card_nonce': 'YOUR_CARD_NONCE',
'billing_address': {
'address_line_1': '500 Electric Ave',
'address_line_2': 'Suite 600',
'locality': 'New York',
'administrative_district_level_1': 'NY',
'postal_code': '10003',
'country': 'US'
},
'cardholder_name': 'Amelia Earhart'
}
result = customers_api.create_customer_card(
customer_id,
body
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
This endpoint is deprecated.
Removes a card on file from a customer.
def delete_customer_card(self,
customer_id,
card_id)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer that the card on file belongs to. |
card_id |
str |
Template, Required | The ID of the card on file to delete. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Delete Customer Card Response
.
customer_id = 'customer_id8'
card_id = 'card_id4'
result = customers_api.delete_customer_card(
customer_id,
card_id
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Removes a group membership from a customer.
The customer is identified by the customer_id
value
and the customer group is identified by the group_id
value.
def remove_group_from_customer(self,
customer_id,
group_id)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer to remove from the group. |
group_id |
str |
Template, Required | The ID of the customer group to remove the customer from. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Remove Group From Customer Response
.
customer_id = 'customer_id8'
group_id = 'group_id0'
result = customers_api.remove_group_from_customer(
customer_id,
group_id
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)
Adds a group membership to a customer.
The customer is identified by the customer_id
value
and the customer group is identified by the group_id
value.
def add_group_to_customer(self,
customer_id,
group_id)
Parameter | Type | Tags | Description |
---|---|---|---|
customer_id |
str |
Template, Required | The ID of the customer to add to a group. |
group_id |
str |
Template, Required | The ID of the customer group to add the customer to. |
This method returns a ApiResponse
instance. The body
property of this instance returns the response data which is of type Add Group to Customer Response
.
customer_id = 'customer_id8'
group_id = 'group_id0'
result = customers_api.add_group_to_customer(
customer_id,
group_id
)
if result.is_success():
print(result.body)
elif result.is_error():
print(result.errors)