com.squareup.square.api

Class DefaultCustomersApi

java.lang.Object

com.squareup.square.api.BaseApi

com.squareup.square.api.DefaultCustomersApi

All Implemented Interfaces:

CustomersApi

public final class DefaultCustomersApi
extends BaseApi
implements CustomersApi

This class lists all the endpoints of the groups.

Nested Class Summary

Nested classes/interfaces inherited from class com.squareup.square.api.BaseApi

BaseApi.RequestExecutor, BaseApi.RequestSupplier, BaseApi.ResponseHandler<T>

Field Summary

Fields inherited from class com.squareup.square.api.BaseApi

authManagers, config, httpCallback, internalUserAgent

Constructor Summary

Constructors

Constructor and Description
DefaultCustomersApi(Configuration config, HttpClient httpClient, Map<String,AuthManager> authManagers) Initializes the controller.
DefaultCustomersApi(Configuration config, HttpClient httpClient, Map<String,AuthManager> authManagers, HttpCallback httpCallback) Initializes the controller with HTTPCallback.

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 a supported query filter.
CompletableFuture<SearchCustomersResponse>	searchCustomersAsync(SearchCustomersRequest body) Searches the customer profiles associated with a Square account using a supported query filter.
UpdateCustomerResponse	updateCustomer(String customerId, UpdateCustomerRequest body) Updates a customer profile.
CompletableFuture<UpdateCustomerResponse>	updateCustomerAsync(String customerId, UpdateCustomerRequest body) Updates a customer profile.

Methods inherited from class com.squareup.square.api.BaseApi

getClientInstance, getHttpCallback, makeHttpCallAsync, validateResponse

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultCustomersApi

public DefaultCustomersApi(Configuration config,
                           HttpClient httpClient,
                           Map<String,AuthManager> authManagers)

Initializes the controller.

Parameters:

config - Configurations added in client.

httpClient - Send HTTP requests and read the responses.

authManagers - Apply authorization to requests.

DefaultCustomersApi

public DefaultCustomersApi(Configuration config,
                           HttpClient httpClient,
                           Map<String,AuthManager> authManagers,
                           HttpCallback httpCallback)

Initializes the controller with HTTPCallback.

Parameters:

config - Configurations added in client.

httpClient - Send HTTP requests and read the responses.

authManagers - Apply authorization to requests.

httpCallback - Callback to be called before and after the HTTP call.

Method Detail

listCustomers

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

Specified by:

listCustomers in interface CustomersApi

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

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

Specified by:

listCustomersAsync in interface CustomersApi

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

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

Specified by:

createCustomer in interface CustomersApi

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

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

Specified by:

createCustomerAsync in interface CustomersApi

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

public SearchCustomersResponse searchCustomers(SearchCustomersRequest body)
                                        throws ApiException,
                                               IOException

Searches the customer profiles associated with a Square account using a supported query filter. 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.

Specified by:

searchCustomers in interface CustomersApi

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

public CompletableFuture<SearchCustomersResponse> searchCustomersAsync(SearchCustomersRequest body)

Searches the customer profiles associated with a Square account using a supported query filter. 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.

Specified by:

searchCustomersAsync in interface CustomersApi

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

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

Specified by:

deleteCustomer in interface CustomersApi

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

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

Specified by:

deleteCustomerAsync in interface CustomersApi

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

public RetrieveCustomerResponse retrieveCustomer(String customerId)
                                          throws ApiException,
                                                 IOException

Returns details for a single customer.

Specified by:

retrieveCustomer in interface CustomersApi

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

public CompletableFuture<RetrieveCustomerResponse> retrieveCustomerAsync(String customerId)

Returns details for a single customer.

Specified by:

retrieveCustomerAsync in interface CustomersApi

Parameters:

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

Returns:

Returns the RetrieveCustomerResponse response from the API call

updateCustomer

public 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).

Specified by:

updateCustomer in interface CustomersApi

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

public 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).

Specified by:

updateCustomerAsync in interface CustomersApi

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

Specified by:

createCustomerCard in interface CustomersApi

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

Specified by:

createCustomerCardAsync in interface CustomersApi

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
public DeleteCustomerCardResponse deleteCustomerCard(String customerId,
                                                                 String cardId)
                                                          throws ApiException,
                                                                 IOException

Deprecated.

Removes a card on file from a customer.

Specified by:

deleteCustomerCard in interface CustomersApi

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
public CompletableFuture<DeleteCustomerCardResponse> deleteCustomerCardAsync(String customerId,
                                                                                         String cardId)

Deprecated.

Removes a card on file from a customer.

Specified by:

deleteCustomerCardAsync in interface CustomersApi

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

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

Specified by:

removeGroupFromCustomer in interface CustomersApi

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

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

Specified by:

removeGroupFromCustomerAsync in interface CustomersApi

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

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

Specified by:

addGroupToCustomer in interface CustomersApi

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

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

Specified by:

addGroupToCustomerAsync in interface CustomersApi

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