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.

The following is an example CreateCustomer request:

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "ACME Inc.",
    "email_address": "john.doe.jr@acme.com",
    "family_name": "Doe",
    "given_name": "John",
    "nickname": "Junior",
    "idempotency_key": "59973bb6-75ae-497a-a006-b2490example",
    "phone_number": "+1 (206) 222-3456"
  }'

When the customer profile is successfully created, you 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 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.

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.

curl https://connect.squareupsandbox.com/v2/customers/{customer_id} \
  -X PUT \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "birthday": "0000-01-13",
    "address": {},
    "nickname": "",
    "version": 0
  }'

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, 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.

curl https://connect.squareupsandbox.com/v2/customers/{customer_id}?version=2 \
  -X DELETE \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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

• Retrieve Customer Profiles

• Search for Customer Profiles

• Custom Attributes for Customer Profiles