Keep Customer Records
To keep records of customers for a Square seller, you create a customer profile and make timely updates when the customer contact information changes. You can also delete a profile if the customer is considered inactive or wants to be removed from the seller's Customer Directory.
Create a customer profile
To create a customer profile, use the CreateCustomer endpoint. The customer profile is added to the seller's Customer Directory.
Before creating a customer profile, you need to collect at least one of the following customer attributes:
given_name
. The customer's first name.family_name
. The customer's last name.company_name
. The name of the customer's workplace.email_address
. The customer's email address.phone_number
. The customer's phone number.
In a web application, you can present these and other customer attributes as input text fields in a web form. Before creating a customer profile, make sure to explicitly ask the customer for permission to store the information you collect. For more information, see Best Practices for Collecting Information.
Note
The CreateCustomer
endpoint permits creating duplicate customer profiles. Before creating a new customer profile, you should call the SearchCustomers endpoint to search by phone number, email address, or reference ID to determine whether a profile for the customer already exists.
The following is an example CreateCustomer
request:
When the customer profile is successfully created, you receive a 200
response similar to the following:
The creation_source
attribute represents how the customer profile was created. This example is set to THIRD_PARTY
because it was created by an application calling the API. Customer profiles that sellers create in the Square Seller Dashboard or Square Point of Sale application have a DIRECTORY
creation source. If two profiles are merged, the resulting profile has a MERGED
creation source. For the list of sources that create customer profiles, see CustomerCreationSource.
The version
attribute is the current version of the customer profile. For more information, see Customer profile versions and optimistic concurrency support.
After a customer profile is created, you can retrieve it using the Customers API. For more information, see Retrieve Customer Profiles and Search for Customer Profiles.
Note
To create or manage custom attributes for customer profiles, use the Customer Custom Attributes API. For more information, see Custom Attributes for Customer Profiles.
Update a customer profile
To update a customer profile, call the UpdateCustomer endpoint. To help ensure that you provide seamless experiences in customer interactions and communications, you should keep customer profiles up to date. You can update the following attributes: phone_number
, email_address
, address
, birthday
, company_name
, family_name
, given_name
, nickname
, note
, and reference_id
.
You must provide the customer ID when you call UpdateCustomer
, as shown in the following example request. You can get the ID by calling ListCustomers or SearchCustomers.
The example request makes the following changes:
Sets the customer's birthday to January 13 (without the year) by specifying
0000-01-13
.Clears the customer's address by specifying an empty object.
Clears the customer's nickname by specifying an empty string.
The example request also includes the recommended version
attribute, which must be set to the current version of the customer profile if included in the request. Doing so allows the operation to succeed only if the current version of the customer profile matches the version specified in the request. Otherwise, the request fails with a CONFLICT
error. Each time a customer profile is updated, the version is incremented. For more information, see Customer profile versions and optimistic concurrency support.
Note
To make any changes to an address, you must provide the complete Address object. Sparse updates are not supported for this object, so any fields that are undefined in the request are removed from the object.
You cannot use UpdateCustomer
to change a card on file, change group membership, or update a custom attribute value.
To update a card on file, use the Cards API Overview or Gift Cards API Overview.
To change group membership, call AddGroupToCustomer or RemoveGroupFromCustomer.
To work with custom attributes, use the Customer Custom Attributes API. For more information, see Custom Attributes for Customer Profiles.
Delete a customer profile
To delete a customer profile from the seller's Customer Directory, call the DeleteCustomer endpoint. You might want to delete a customer profile when a customer is inactive for a specified period of time or when the customer makes an explicit request to be removed from the customer base.
You must provide the customer ID when you call DeleteCustomer
, as shown in the following example request. You can get the ID by calling ListCustomers or SearchCustomers.
The example request also includes the recommended version
attribute, which must be set to the current version of the customer profile if included in the request. Doing so allows the operation to succeed only if the current version of the customer profile matches the version specified in the request. Otherwise, the request fails with a CONFLICT
error. For more information, see Customer profile versions and optimistic concurrency support.
Related topics
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.