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)

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:

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -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-b2490fc56cab",
    "phone_number": "+1 (206) 222-3456"
  }'

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"
  }
}

The creation_source attribute of the newly created customer profile has the value of THIRD_PARTY because it is created by an application calling the API. If you created the customer profile in the Square Seller Dashboard, the creation_source attribute has the value of DIRECTORY. When two profiles are merged, the resultant profile has MERGED assigned to the creation_source attribute.

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

After a customer profile is created, the customer profile should be updated whenever any customer attributes change. This helps ensure that you can continuously provide productive experiences in customer interactions and communications.

For example, when a customer moves to a new address or uses a new inbox to receive emails, you need to update the address attribute and the email_address attribute, respectively. When the customer switches to a new phone number, you need to update the phone_number attribute value. Other updatable customer attributes include birthday, company_name, family_name, given_name, nickname, note, and reference_id.

You cannot call the UpdateCustomer endpoint to modify a card on file. To update an existing card on file, call DeleteCustomerCard to remove the existing card on file and then call CreateCustomerCard to create a new card on file.

To call the UpdateCustomer endpoint to update the customer profile, you must first obtain the customer ID. The following example request updates a customer's birthday to 0000-01-13, which is January 13 (without the year). The customer is identified by the ID value of TNQC0TYTWMRSFFQ157KK4V7MVR.

curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157KK4V7MVR \
  -X PUT \
  -H 'Square-Version: 2021-01-21' \
  -H 'Authorization: Bearer {SQUARE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "birthday": "0000-01-13"
  }'

Delete a customer profile

When a customer becomes inactive for a specified period of time, or when the customer makes an explicit request to be removed from your customer base, you might want to delete the customer profile from the associated Square account.

To call the DeleteCustomer endpoint to delete a customer profile, you need to obtain the customer's ID and then submit the request similar to the following example:

curl https://connect.squareupsandbox.com/v2/customers/TNQC0TYTWMRSFFQ157KK4V7MVR \
  -X DELETE \
  -H 'Square-Version: 2021-01-21' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Content-Type: application/json'