Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Customers

  • List customers

  • Create customer

  • Bulk create customers

  • Bulk delete customers

  • Bulk retrieve customers

  • Bulk update customers

  • Search customers

  • Delete customer

  • Retrieve customer

  • Update customer

  • Remove group from customer

  • Add group to customer

  • Webhooks

  • customer.created

  • customer.deleted

  • customer.updated

<- Customers API

Customers API

All versions ->

Bulk update customers

POST

 /v2/customers/bulk-update

Updates multiple customer profiles.

This endpoint takes a map of individual update requests and returns a map of responses.

Permissions:CUSTOMERS_WRITE

Guide

Update customer profiles

Try in API Explorer
Link to section

Request body

Example code

Link to section

customers

Required

A map of 1 to 100 individual update requests, represented by customer ID: { customer data } key-value pairs.

Each key is the ID of the customer profile to update. To update a customer profile that was created by merging existing profiles, provide the ID of the newly created profile.

Each value contains the updated customer data. Only new or changed fields are required. To add or update a field, specify the new value. To remove a field, specify null.

Link to section

Response fields

Link to section

responses

A map of responses that correspond to individual update requests, represented by key-value pairs.

Each key is the customer ID that was specified for an update request and each value is the corresponding response. If the request succeeds, the value is the updated customer profile. If the request fails, the value contains any errors that occurred during the request.

Link to section

errors

Any top-level errors that prevented the bulk operation from running.

Link to section

Examples

All versions ->

POST /v2/customers/bulk-update
curl https://connect.squareup.com/v2/customers/bulk-update \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "customers": { "8DDA5NZVBZFGAX0V3HPF81HHE0": { "phone_number": null, "email_address": "[email protected]", "note": "updated customer note", "version": 2 }, "N18CPRVXR5214XPBBA6BZQWF3C": { "given_name": "Marie", "family_name": "Curie", "version": 0 } } }'

Response JSON

{ "responses": { "8DDA5NZVBZFGAX0V3HPF81HHE0": { "customer": { "id": "8DDA5NZVBZFGAX0V3HPF81HHE0", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Amelia", "family_name": "Earhart", "email_address": "[email protected]", "note": "updated customer note", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "birthday": "1897-07-24", "version": 3 } }, "N18CPRVXR5214XPBBA6BZQWF3C": { "customer": { "id": "N18CPRVXR5214XPBBA6BZQWF3C", "created_at": "2024-01-19T00:27:54.59Z", "updated_at": "2024-01-19T00:38:06Z", "given_name": "Marie", "family_name": "Curie", "preferences": { "email_unsubscribed": false }, "creation_source": "THIRD_PARTY", "version": 1 } } } }