Keep Records of Customer Profiles
To keep records of customer profiles in a Square account, you create a profile for a customer and then make timely updates when the customer contact information changes or when duplicated profiles are detected. The update can include deleting the profile whenever a customer wants to be removed or is otherwise no longer deemed as active.
Create a customer profile
To create a customer profile, you can use the Square Seller Dashboard, a Square Point of Sale (POS) device or application, or the Customers API. The Seller Dashboard and POS system provide interactive user interfaces to guide you through the process. To use the API, use the following instructions.
Before creating a customer profile, you need to collect at least one of the following customer attributes:
The customer's first name (
given_name)The customer's last name (
family_name)The customer's workplace (
company_name)The customer's email address (
email_address)The customer's phone number (
phone_number)
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.
In a web application, you can present these and other customer attributes in a web form as the respective input text fields. Before creating a customer profile, make sure to explicitly ask the customer for permission to store the customer information in the Square account.
To use the Customers API to create a customer profile, call the CreateCustomer endpoint as shown in the following example request:
When the customer profile is successfully created, you should receive a 200 response similar to the following:
{
"customer": {
"id": "GSA67K1YGCSQQ47KSW7J7WX53M",
"created_at": "2020-05-27T01:06:18.682Z",
"updated_at": "2020-05-27T01:06:18Z",
"given_name": "John",
"family_name": "Doe",
"nickname": "Junior",
"company_name": "ACME Inc.",
"email_address": "john.doe.jr@acme.com",
"phone_number": "+1 (206) 222-3456",
"preferences": {
"email_unsubscribed": false
},
"creation_source": "THIRD_PARTY",
"version": 0
}
}
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 created in the Square Seller Dashboard have a DIRECTORY creation source. When two profiles are merged, the resultant 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.
In addition to viewing the created customer profile in the Square Seller Dashboard or a Square POS system, you can use the Customers API to retrieve the profile to view the customer information. This is discussed in Retrieve Customer Profiles, where you learn how to retrieve a customer profile by its ID and to search for a customer profile by one or more supported query filters.
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.
You cannot use UpdateCustomer to change a card on file or change group membership.
To update a card on file, use the Cards API or Gift Cards API.
To change group membership, call AddGroupToCustomer or RemoveGroupFromCustomer.
Delete a customer profile
To delete a customer profile from the associated Square account, 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.