com.squareup.square.api

Interface CustomersApi

All Known Implementing Classes:

DefaultCustomersApi

public interface CustomersApi

This interface lists all the endpoints of the group. This can be overridden for the mock calls.

Method Summary

Modifier and Type	Method and Description
AddGroupToCustomerResponse	addGroupToCustomer(String customerId, String groupId) Adds a group membership to a customer.
CompletableFuture<AddGroupToCustomerResponse>	addGroupToCustomerAsync(String customerId, String groupId) Adds a group membership to a customer.
CreateCustomerResponse	createCustomer(CreateCustomerRequest body) Creates a new customer for a business.
CompletableFuture<CreateCustomerResponse>	createCustomerAsync(CreateCustomerRequest body) Creates a new customer for a business.
CreateCustomerCardResponse	createCustomerCard(String customerId, CreateCustomerCardRequest body) Deprecated.
CompletableFuture<CreateCustomerCardResponse>	createCustomerCardAsync(String customerId, CreateCustomerCardRequest body) Deprecated.
DeleteCustomerResponse	deleteCustomer(String customerId, Long version) Deletes a customer profile from a business.
CompletableFuture<DeleteCustomerResponse>	deleteCustomerAsync(String customerId, Long version) Deletes a customer profile from a business.
DeleteCustomerCardResponse	deleteCustomerCard(String customerId, String cardId) Deprecated.
CompletableFuture<DeleteCustomerCardResponse>	deleteCustomerCardAsync(String customerId, String cardId) Deprecated.
ListCustomersResponse	listCustomers(String cursor, Integer limit, String sortField, String sortOrder) Lists customer profiles associated with a Square account.
CompletableFuture<ListCustomersResponse>	listCustomersAsync(String cursor, Integer limit, String sortField, String sortOrder) Lists customer profiles associated with a Square account.
RemoveGroupFromCustomerResponse	removeGroupFromCustomer(String customerId, String groupId) Removes a group membership from a customer.
CompletableFuture<RemoveGroupFromCustomerResponse>	removeGroupFromCustomerAsync(String customerId, String groupId) Removes a group membership from a customer.
RetrieveCustomerResponse	retrieveCustomer(String customerId) Returns details for a single customer.
CompletableFuture<RetrieveCustomerResponse>	retrieveCustomerAsync(String customerId) Returns details for a single customer.
SearchCustomersResponse	searchCustomers(SearchCustomersRequest body) Searches the customer profiles associated with a Square account using one or more supported query filters.
CompletableFuture<SearchCustomersResponse>	searchCustomersAsync(SearchCustomersRequest body) Searches the customer profiles associated with a Square account using one or more supported query filters.
UpdateCustomerResponse	updateCustomer(String customerId, UpdateCustomerRequest body) Updates a customer profile.
CompletableFuture<UpdateCustomerResponse>	updateCustomerAsync(String customerId, UpdateCustomerRequest body) Updates a customer profile.

Method Detail

listCustomers

ListCustomersResponse listCustomers(String cursor,
                                    Integer limit,
                                    String sortField,
                                    String sortOrder)
                             throws ApiException,
                                    IOException

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.

Parameters:

cursor - Optional parameter: 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

limit - Optional parameter: 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

sortField - Optional parameter: Indicates how customers should be sorted. The default value is `DEFAULT`.

sortOrder - Optional parameter: Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`.

Returns:

Returns the ListCustomersResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

listCustomersAsync

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

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.

Parameters:

cursor - Optional parameter: 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

limit - Optional parameter: 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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

sortField - Optional parameter: Indicates how customers should be sorted. The default value is `DEFAULT`.

sortOrder - Optional parameter: Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`.

Returns:

Returns the ListCustomersResponse response from the API call

createCustomer

CreateCustomerResponse createCustomer(CreateCustomerRequest body)
                               throws ApiException,
                                      IOException

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

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

createCustomerAsync

CompletableFuture<CreateCustomerResponse> createCustomerAsync(CreateCustomerRequest body)

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

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateCustomerResponse response from the API call

searchCustomers

SearchCustomersResponse searchCustomers(SearchCustomersRequest body)
                                 throws ApiException,
                                        IOException

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.

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the SearchCustomersResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

searchCustomersAsync

CompletableFuture<SearchCustomersResponse> searchCustomersAsync(SearchCustomersRequest body)

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.

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the SearchCustomersResponse response from the API call

deleteCustomer

DeleteCustomerResponse deleteCustomer(String customerId,
                                      Long version)
                               throws ApiException,
                                      IOException

Deletes a customer profile from a business. This operation also unlinks any associated cards on file. As a best practice, you should include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control. The value must be set to the current version of the customer profile. To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

Parameters:

customerId - Required parameter: The ID of the customer to delete.

version - Optional parameter: The current version of the customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).

Returns:

Returns the DeleteCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

deleteCustomerAsync

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

Deletes a customer profile from a business. This operation also unlinks any associated cards on file. As a best practice, you should include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control. The value must be set to the current version of the customer profile. To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

Parameters:

customerId - Required parameter: The ID of the customer to delete.

version - Optional parameter: The current version of the customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).

Returns:

Returns the DeleteCustomerResponse response from the API call

retrieveCustomer

RetrieveCustomerResponse retrieveCustomer(String customerId)
                                   throws ApiException,
                                          IOException

Returns details for a single customer.

Parameters:

customerId - Required parameter: The ID of the customer to retrieve.

Returns:

Returns the RetrieveCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

retrieveCustomerAsync

CompletableFuture<RetrieveCustomerResponse> retrieveCustomerAsync(String customerId)

Returns details for a single customer.

Parameters:

customerId - Required parameter: The ID of the customer to retrieve.

Returns:

Returns the RetrieveCustomerResponse response from the API call

updateCustomer

UpdateCustomerResponse updateCustomer(String customerId,
                                      UpdateCustomerRequest body)
                               throws ApiException,
                                      IOException

Updates a customer profile. To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object. As a best practice, you should include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control. The value must be set to the current version of the customer profile. 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]($e/Cards) or [Gift Cards API]($e/GiftCards).

Parameters:

customerId - Required parameter: The ID of the customer to update.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the UpdateCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

updateCustomerAsync

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

Updates a customer profile. To change an attribute, specify the new value. To remove an attribute, specify the value as an empty string or empty object. As a best practice, you should include the `version` field in the request to enable [optimistic concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency) control. The value must be set to the current version of the customer profile. 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]($e/Cards) or [Gift Cards API]($e/GiftCards).

Parameters:

customerId - Required parameter: The ID of the customer to update.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the UpdateCustomerResponse response from the API call

createCustomerCard

@Deprecated
CreateCustomerCardResponse createCustomerCard(String customerId,
                                                          CreateCustomerCardRequest body)
                                                   throws ApiException,
                                                          IOException

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.

Parameters:

customerId - Required parameter: The Square ID of the customer profile the card is linked to.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateCustomerCardResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

createCustomerCardAsync

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

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.

Parameters:

customerId - Required parameter: The Square ID of the customer profile the card is linked to.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateCustomerCardResponse response from the API call

deleteCustomerCard

@Deprecated
DeleteCustomerCardResponse deleteCustomerCard(String customerId,
                                                          String cardId)
                                                   throws ApiException,
                                                          IOException

Deprecated.

Removes a card on file from a customer.

Parameters:

customerId - Required parameter: The ID of the customer that the card on file belongs to.

cardId - Required parameter: The ID of the card on file to delete.

Returns:

Returns the DeleteCustomerCardResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

deleteCustomerCardAsync

@Deprecated
CompletableFuture<DeleteCustomerCardResponse> deleteCustomerCardAsync(String customerId,
                                                                                  String cardId)

Deprecated.

Removes a card on file from a customer.

Parameters:

customerId - Required parameter: The ID of the customer that the card on file belongs to.

cardId - Required parameter: The ID of the card on file to delete.

Returns:

Returns the DeleteCustomerCardResponse response from the API call

removeGroupFromCustomer

RemoveGroupFromCustomerResponse removeGroupFromCustomer(String customerId,
                                                        String groupId)
                                                 throws ApiException,
                                                        IOException

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.

Parameters:

customerId - Required parameter: The ID of the customer to remove from the group.

groupId - Required parameter: The ID of the customer group to remove the customer from.

Returns:

Returns the RemoveGroupFromCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

removeGroupFromCustomerAsync

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

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.

Parameters:

customerId - Required parameter: The ID of the customer to remove from the group.

groupId - Required parameter: The ID of the customer group to remove the customer from.

Returns:

Returns the RemoveGroupFromCustomerResponse response from the API call

addGroupToCustomer

AddGroupToCustomerResponse addGroupToCustomer(String customerId,
                                              String groupId)
                                       throws ApiException,
                                              IOException

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.

Parameters:

customerId - Required parameter: The ID of the customer to add to a group.

groupId - Required parameter: The ID of the customer group to add the customer to.

Returns:

Returns the AddGroupToCustomerResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

addGroupToCustomerAsync

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

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.

Parameters:

customerId - Required parameter: The ID of the customer to add to a group.

groupId - Required parameter: The ID of the customer group to add the customer to.

Returns:

Returns the AddGroupToCustomerResponse response from the API call