customers.md

Customers

CustomersApi customersApi = client.getCustomersApi();

Class Name

CustomersApi

Methods

• List Customers
• Create Customer
• Bulk Create Customers
• Bulk Delete Customers
• Bulk Retrieve Customers
• Bulk Update Customers
• Search Customers
• Delete Customer
• Retrieve Customer
• Update Customer
• Create Customer Card
• Delete Customer Card
• Remove Group From Customer
• Add Group to Customer

List Customers

Lists customer profiles associated with a Square account.

Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

CompletableFuture<ListCustomersResponse> listCustomersAsync(
    final String cursor,
    final Integer limit,
    final String sortField,
    final String sortOrder,
    final Boolean count)

Parameters

Parameter	Type	Tags	Description
cursor	String	Query, Optional	A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
limit	Integer	Query, Optional	The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100. For more information, see Pagination.
sortField	String	Query, Optional	Indicates how customers should be sorted. The default value is DEFAULT.
sortOrder	String	Query, Optional	Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order. The default value is ASC.
count	Boolean	Query, Optional	Indicates whether to return the total count of customers in the count field of the response. The default value is false.

Response Type

ListCustomersResponse

Example Usage

Boolean count = false;

customersApi.listCustomersAsync(null, null, null, null, count).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Create Customer

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

• given_name
• family_name
• company_name
• email_address
• phone_number

CompletableFuture<CreateCustomerResponse> createCustomerAsync(
    final CreateCustomerRequest body)

Parameters

Parameter	Type	Tags	Description
body	CreateCustomerRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

CreateCustomerResponse

Example Usage

CreateCustomerRequest body = new CreateCustomerRequest.Builder()
    .givenName("Amelia")
    .familyName("Earhart")
    .emailAddress("Amelia.Earhart@example.com")
    .address(new Address.Builder()
        .addressLine1("500 Electric Ave")
        .addressLine2("Suite 600")
        .locality("New York")
        .administrativeDistrictLevel1("NY")
        .postalCode("10003")
        .country("US")
        .build())
    .phoneNumber("+1-212-555-4240")
    .referenceId("YOUR_REFERENCE_ID")
    .note("a customer")
    .build();

customersApi.createCustomerAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Bulk Create Customers

Creates multiple customer profiles for a business.

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

You must provide at least one of the following values in each create request:

• given_name
• family_name
• company_name
• email_address
• phone_number

CompletableFuture<BulkCreateCustomersResponse> bulkCreateCustomersAsync(
    final BulkCreateCustomersRequest body)

Parameters

Parameter	Type	Tags	Description
body	BulkCreateCustomersRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

BulkCreateCustomersResponse

Example Usage

BulkCreateCustomersRequest body = new BulkCreateCustomersRequest.Builder(
    new LinkedHashMap<String, BulkCreateCustomerData>() {{
        put("8bb76c4f-e35d-4c5b-90de-1194cd9179f0", new BulkCreateCustomerData.Builder()
            .givenName("Amelia")
            .familyName("Earhart")
            .emailAddress("Amelia.Earhart@example.com")
            .address(new Address.Builder()
                .addressLine1("500 Electric Ave")
                .addressLine2("Suite 600")
                .locality("New York")
                .administrativeDistrictLevel1("NY")
                .postalCode("10003")
                .country("US")
                .build())
            .phoneNumber("+1-212-555-4240")
            .referenceId("YOUR_REFERENCE_ID")
            .note("a customer")
            .build());
        put("d1689f23-b25d-4932-b2f0-aed00f5e2029", new BulkCreateCustomerData.Builder()
            .givenName("Marie")
            .familyName("Curie")
            .emailAddress("Marie.Curie@example.com")
            .address(new Address.Builder()
                .addressLine1("500 Electric Ave")
                .addressLine2("Suite 601")
                .locality("New York")
                .administrativeDistrictLevel1("NY")
                .postalCode("10003")
                .country("US")
                .build())
            .phoneNumber("+1-212-444-4240")
            .referenceId("YOUR_REFERENCE_ID")
            .note("another customer")
            .build());
    }}
)
.build();

customersApi.bulkCreateCustomersAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Bulk Delete Customers

Deletes multiple customer profiles.

The endpoint takes a list of customer IDs and returns a map of responses.

CompletableFuture<BulkDeleteCustomersResponse> bulkDeleteCustomersAsync(
    final BulkDeleteCustomersRequest body)

Parameters

Parameter	Type	Tags	Description
body	BulkDeleteCustomersRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

BulkDeleteCustomersResponse

Example Usage

BulkDeleteCustomersRequest body = new BulkDeleteCustomersRequest.Builder(
    Arrays.asList(
        "8DDA5NZVBZFGAX0V3HPF81HHE0",
        "N18CPRVXR5214XPBBA6BZQWF3C",
        "2GYD7WNXF7BJZW1PMGNXZ3Y8M8"
    )
)
.build();

customersApi.bulkDeleteCustomersAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Bulk Retrieve Customers

Retrieves multiple customer profiles.

This endpoint takes a list of customer IDs and returns a map of responses.

CompletableFuture<BulkRetrieveCustomersResponse> bulkRetrieveCustomersAsync(
    final BulkRetrieveCustomersRequest body)

Parameters

Parameter	Type	Tags	Description
body	BulkRetrieveCustomersRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

BulkRetrieveCustomersResponse

Example Usage

BulkRetrieveCustomersRequest body = new BulkRetrieveCustomersRequest.Builder(
    Arrays.asList(
        "8DDA5NZVBZFGAX0V3HPF81HHE0",
        "N18CPRVXR5214XPBBA6BZQWF3C",
        "2GYD7WNXF7BJZW1PMGNXZ3Y8M8"
    )
)
.build();

customersApi.bulkRetrieveCustomersAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Bulk Update Customers

Updates multiple customer profiles.

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

You cannot use this endpoint to change cards on file. To make changes, use the Cards API or Gift Cards API.

CompletableFuture<BulkUpdateCustomersResponse> bulkUpdateCustomersAsync(
    final BulkUpdateCustomersRequest body)

Parameters

Parameter	Type	Tags	Description
body	BulkUpdateCustomersRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

BulkUpdateCustomersResponse

Example Usage

BulkUpdateCustomersRequest body = new BulkUpdateCustomersRequest.Builder(
    new LinkedHashMap<String, BulkUpdateCustomerData>() {{
        put("8DDA5NZVBZFGAX0V3HPF81HHE0", new BulkUpdateCustomerData.Builder()
            .emailAddress("New.Amelia.Earhart@example.com")
            .phoneNumber("phone_number2")
            .note("updated customer note")
            .version(2L)
            .build());
        put("N18CPRVXR5214XPBBA6BZQWF3C", new BulkUpdateCustomerData.Builder()
            .givenName("Marie")
            .familyName("Curie")
            .version(0L)
            .build());
    }}
)
.build();

customersApi.bulkUpdateCustomersAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Search Customers

Searches the customer profiles associated with a Square account using one or more supported query filters.

Calling SearchCustomers without any explicit query filter returns all customer profiles ordered alphabetically based on given_name and family_name.

Under normal operating conditions, newly created or updated customer profiles become available for the search operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

CompletableFuture<SearchCustomersResponse> searchCustomersAsync(
    final SearchCustomersRequest body)

Parameters

Parameter	Type	Tags	Description
body	SearchCustomersRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

SearchCustomersResponse

Example Usage

SearchCustomersRequest body = new SearchCustomersRequest.Builder()
    .limit(2L)
    .query(new CustomerQuery.Builder()
        .filter(new CustomerFilter.Builder()
            .creationSource(new CustomerCreationSourceFilter.Builder()
                .values(Arrays.asList(
                    "THIRD_PARTY"
                ))
                .rule("INCLUDE")
                .build())
            .createdAt(new TimeRange.Builder()
                .startAt("2018-01-01T00:00:00-00:00")
                .endAt("2018-02-01T00:00:00-00:00")
                .build())
            .emailAddress(new CustomerTextFilter.Builder()
                .fuzzy("example.com")
                .build())
            .groupIds(new FilterValue.Builder()
                .all(Arrays.asList(
                    "545AXB44B4XXWMVQ4W8SBT3HHF"
                ))
                .build())
            .build())
        .sort(new CustomerSort.Builder()
            .field("CREATED_AT")
            .order("ASC")
            .build())
        .build())
    .build();

customersApi.searchCustomersAsync(body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Delete Customer

Deletes a customer profile from a business. This operation also unlinks any associated cards on file.

To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

CompletableFuture<DeleteCustomerResponse> deleteCustomerAsync(
    final String customerId,
    final Long version)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer to delete.
version	Long	Query, Optional	The current version of the customer profile. As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile.

Response Type

DeleteCustomerResponse

Example Usage

String customerId = "customer_id8";

customersApi.deleteCustomerAsync(customerId, null).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Retrieve Customer

Returns details for a single customer.

CompletableFuture<RetrieveCustomerResponse> retrieveCustomerAsync(
    final String customerId)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer to retrieve.

Response Type

RetrieveCustomerResponse

Example Usage

String customerId = "customer_id8";

customersApi.retrieveCustomerAsync(customerId).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Update Customer

Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. To add or update a field, specify the new value. To remove a field, specify null.

To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

You cannot use this endpoint to change cards on file. To make changes, use the Cards API or Gift Cards API.

CompletableFuture<UpdateCustomerResponse> updateCustomerAsync(
    final String customerId,
    final UpdateCustomerRequest body)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer to update.
body	UpdateCustomerRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

UpdateCustomerResponse

Example Usage

String customerId = "customer_id8";
UpdateCustomerRequest body = new UpdateCustomerRequest.Builder()
    .emailAddress("New.Amelia.Earhart@example.com")
    .phoneNumber("phone_number2")
    .note("updated customer note")
    .version(2L)
    .build();

customersApi.updateCustomerAsync(customerId, body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Create Customer Card

This endpoint is deprecated.

Adds a card on file to an existing customer.

As with charges, calls to CreateCustomerCard are idempotent. Multiple calls with the same card nonce return the same card record that was created with the provided nonce during the first call.

CompletableFuture<CreateCustomerCardResponse> createCustomerCardAsync(
    final String customerId,
    final CreateCustomerCardRequest body)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The Square ID of the customer profile the card is linked to.
body	CreateCustomerCardRequest	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Response Type

CreateCustomerCardResponse

Example Usage

String customerId = "customer_id8";
CreateCustomerCardRequest body = new CreateCustomerCardRequest.Builder(
    "YOUR_CARD_NONCE"
)
.billingAddress(new Address.Builder()
        .addressLine1("500 Electric Ave")
        .addressLine2("Suite 600")
        .locality("New York")
        .administrativeDistrictLevel1("NY")
        .postalCode("10003")
        .country("US")
        .build())
.cardholderName("Amelia Earhart")
.build();

customersApi.createCustomerCardAsync(customerId, body).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Delete Customer Card

This endpoint is deprecated.

Removes a card on file from a customer.

CompletableFuture<DeleteCustomerCardResponse> deleteCustomerCardAsync(
    final String customerId,
    final String cardId)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer that the card on file belongs to.
cardId	String	Template, Required	The ID of the card on file to delete.

Response Type

DeleteCustomerCardResponse

Example Usage

String customerId = "customer_id8";
String cardId = "card_id4";

customersApi.deleteCustomerCardAsync(customerId, cardId).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Remove Group From Customer

Removes a group membership from a customer.

The customer is identified by the customer_id value and the customer group is identified by the group_id value.

CompletableFuture<RemoveGroupFromCustomerResponse> removeGroupFromCustomerAsync(
    final String customerId,
    final String groupId)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer to remove from the group.
groupId	String	Template, Required	The ID of the customer group to remove the customer from.

Response Type

RemoveGroupFromCustomerResponse

Example Usage

String customerId = "customer_id8";
String groupId = "group_id0";

customersApi.removeGroupFromCustomerAsync(customerId, groupId).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});

Add Group to Customer

Adds a group membership to a customer.

The customer is identified by the customer_id value and the customer group is identified by the group_id value.

CompletableFuture<AddGroupToCustomerResponse> addGroupToCustomerAsync(
    final String customerId,
    final String groupId)

Parameters

Parameter	Type	Tags	Description
customerId	String	Template, Required	The ID of the customer to add to a group.
groupId	String	Template, Required	The ID of the customer group to add the customer to.

Response Type

AddGroupToCustomerResponse

Example Usage

String customerId = "customer_id8";
String groupId = "group_id0";

customersApi.addGroupToCustomerAsync(customerId, groupId).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    exception.printStackTrace();
    return null;
});