Skip to main content
The Customers API allows you to create, retrieve, update, search, and delete customer profiles. It supports both individual operations and bulk operations for efficient customer management.

​
Client Initialization

Access the Customers client through the main Square client: 
import (
    "context"
    "github.com/square/square-go-sdk/v3"
)

client := square.NewClient(
    square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)

// Access the Customers API
customersClient := client.Customers

​
Core Methods

​
List

Retrieve a paginated list of customer profiles. 
request := &square.ListCustomersRequest{
    Cursor: square.String("cursor"),
    Limit: square.Int(100),
    SortField: square.CustomerSortFieldDefault.Ptr(),
    SortOrder: square.SortOrderAsc.Ptr(),
    Count: square.Bool(true),
}

response, err := client.Customers.List(context.TODO(), request)
if err != nil {
    // Handle error
}

for _, customer := range response.Customers {
    fmt.Printf("Customer: %s %s\n", 
        *customer.GivenName, 
        *customer.FamilyName)
}
​
cursor
*string
A pagination cursor returned by a previous call. Provide this to retrieve the next set of results.
​
limit
*int
Maximum number of results per page (1-100). Default is 100.
​
sortField
*square.CustomerSortField
Field to sort by. Default is DEFAULT.
​
sortOrder
*square.SortOrder
Sort order: ASC or DESC. Default is ASC.
​
count
*bool
Whether to return the total count of customers. Default is false.
​
customers
[]*square.Customer
Array of customer profile objects.
​
cursor
*string
Pagination cursor for the next page of results.
​
count
*int64
Total count of customers (if requested).

​
Create

Create a new customer profile. 
request := &square.CreateCustomerRequest{
    IdempotencyKey: square.String("unique-key-123"),
    GivenName: square.String("Amelia"),
    FamilyName: square.String("Earhart"),
    EmailAddress: square.String("[email protected]"),
    Address: &square.Address{
        AddressLine1: square.String("500 Electric Ave"),
        AddressLine2: square.String("Suite 600"),
        Locality: square.String("New York"),
        AdministrativeDistrictLevel1: square.String("NY"),
        PostalCode: square.String("10003"),
        Country: square.CountryUs.Ptr(),
    },
    PhoneNumber: square.String("+1-212-555-4240"),
    ReferenceID: square.String("YOUR_REFERENCE_ID"),
    Note: square.String("Premium customer"),
}

response, err := client.Customers.Create(context.TODO(), request)
if err != nil {
    // Handle error
}

fmt.Printf("Created customer ID: %s\n", *response.Customer.ID)
​
idempotencyKey
*string
Unique key for idempotent operations. See Idempotency.
​
givenName
*string
First name (max 300 characters).
​
familyName
*string
Last name (max 300 characters).
​
companyName
*string
Business name (max 500 characters).
​
emailAddress
*string
Email address (max 254 characters).
​
phoneNumber
*string
Phone number (9-16 digits with optional + prefix).
​
address
*square.Address
Physical address associated with the customer.
​
referenceID
*string
External reference ID (max 100 characters).
​
note
*string
Custom note about the customer.
​
birthday
*string
Birthday in YYYY-MM-DD or MM-DD format.
​
customer
*square.Customer
The newly created customer profile.

​
Get

Retrieve a single customer by ID. 
request := &square.GetCustomersRequest{
    CustomerID: "CUSTOMER_ID_HERE",
}

response, err := client.Customers.Get(context.TODO(), request)
if err != nil {
    // Handle error
}

fmt.Printf("Customer: %s\n", *response.Customer.EmailAddress)
​
customerID
string
required
The Square-assigned customer ID.
​
customer
*square.Customer
The requested customer profile.

​
Update

Update an existing customer profile. 
request := &square.UpdateCustomerRequest{
    CustomerID: "CUSTOMER_ID_HERE",
    EmailAddress: square.String("[email protected]"),
    PhoneNumber: square.String("+1-415-555-0000"),
    Note: square.String("Updated note"),
    Version: square.Int64(1), // For optimistic concurrency
}

response, err := client.Customers.Update(context.TODO(), request)
if err != nil {
    // Handle error
}
​
customerID
string
required
The ID of the customer to update.
​
version
*int64
Current version for optimistic concurrency control.

​
Delete

Delete a customer profile permanently. 
request := &square.DeleteCustomersRequest{
    CustomerID: "CUSTOMER_ID_HERE",
    Version: square.Int64(1),
}

response, err := client.Customers.Delete(context.TODO(), request)
if err != nil {
    // Handle error
}
​
customerID
string
required
The ID of the customer to delete.
​
version
*int64
Current version for optimistic concurrency control.
Search for customers using filters and queries. 
request := &square.SearchCustomersRequest{
    Query: &square.CustomerQuery{
        Filter: &square.CustomerFilter{
            EmailAddress: &square.CustomerTextFilter{
                Exact: square.String("[email protected]"),
            },
        },
        Sort: &square.CustomerSort{
            Field: square.CustomerSortFieldCreatedAt.Ptr(),
            Order: square.SortOrderDesc.Ptr(),
        },
    },
    Limit: square.Int64(10),
}

response, err := client.Customers.Search(context.TODO(), request)
if err != nil {
    // Handle error
}

for _, customer := range response.Customers {
    fmt.Printf("Found: %s\n", *customer.EmailAddress)
}
​
query
*square.CustomerQuery
Search query with filters and sorting options.
​
limit
*int64
Maximum number of results (default 100).
​
cursor
*string
Pagination cursor from a previous search.

​
Bulk Operations

​
BatchCreate

Create multiple customers in a single request. 
request := &square.BulkCreateCustomersRequest{
    Customers: map[string]*square.BulkCreateCustomerData{
        "idempotency-key-1": {
            GivenName: square.String("Amelia"),
            FamilyName: square.String("Earhart"),
            EmailAddress: square.String("[email protected]"),
        },
        "idempotency-key-2": {
            GivenName: square.String("Marie"),
            FamilyName: square.String("Curie"),
            EmailAddress: square.String("[email protected]"),
        },
    },
}

response, err := client.Customers.BatchCreate(context.TODO(), request)
if err != nil {
    // Handle error
}

for key, result := range response.Responses {
    if result.Customer != nil {
        fmt.Printf("%s: Created %s\n", key, *result.Customer.ID)
    }
}

​
BatchRetrieve

Retrieve multiple customers by their IDs. 
request := &square.BulkRetrieveCustomersRequest{
    CustomerIDs: []string{
        "CUSTOMER_ID_1",
        "CUSTOMER_ID_2",
    },
}

response, err := client.Customers.BatchRetrieve(context.TODO(), request)
if err != nil {
    // Handle error
}

​
BatchUpdate

Update multiple customers in a single request. 
request := &square.BulkUpdateCustomersRequest{
    Customers: map[string]*square.BulkUpdateCustomerData{
        "CUSTOMER_ID_1": {
            EmailAddress: square.String("[email protected]"),
            Version: square.Int64(1),
        },
        "CUSTOMER_ID_2": {
            PhoneNumber: square.String("+1-555-0000"),
            Version: square.Int64(1),
        },
    },
}

response, err := client.Customers.BatchUpdate(context.TODO(), request)

​
BatchDelete

Delete multiple customers in a single request. 
request := &square.BulkDeleteCustomersRequest{
    CustomerIDs: []string{
        "CUSTOMER_ID_1",
        "CUSTOMER_ID_2",
    },
}

response, err := client.Customers.BatchDelete(context.TODO(), request)

​
Types

​
Customer

The main customer profile object. 
type Customer struct {
    ID           *string
    CreatedAt    *string
    UpdatedAt    *string
    GivenName    *string
    FamilyName   *string
    EmailAddress *string
    PhoneNumber  *string
    CompanyName  *string
    Nickname     *string
    Address      *Address
    Birthday     *string
    ReferenceID  *string
    Note         *string
    Version      *int64
    TaxIDs       *CustomerTaxIDs
}

​
Best Practices

Always provide idempotency keys for create operations to prevent duplicate customers if requests are retried.
Include the version field when updating or deleting customers to prevent conflicts from concurrent modifications.
Use bulk endpoints when working with multiple customers to reduce API calls and improve performance.
Provide at least one of: given_name, family_name, company_name, email_address, or phone_number when creating customers.

Build docs developers (and LLMs) love

Get started for freeTalk to us