Skip to content
This repository was archived by the owner on Apr 23, 2021. It is now read-only.

Latest commit

 

History

History
450 lines (326 loc) · 16.3 KB

CustomersApi.md

File metadata and controls

450 lines (326 loc) · 16.3 KB

CustomersApi

All URIs are relative to https://connect.squareup.com

Method HTTP request Description
createCustomer POST /v2/customers CreateCustomer
createCustomerCard POST /v2/customers/{customer_id}/cards CreateCustomerCard
deleteCustomer DELETE /v2/customers/{customer_id} DeleteCustomer
deleteCustomerCard DELETE /v2/customers/{customer_id}/cards/{card_id} DeleteCustomerCard
listCustomers GET /v2/customers ListCustomers
retrieveCustomer GET /v2/customers/{customer_id} RetrieveCustomer
searchCustomers POST /v2/customers/search SearchCustomers
updateCustomer PUT /v2/customers/{customer_id} UpdateCustomer

createCustomer

CreateCustomerResponse createCustomer(body)

CreateCustomer

Creates a new customer for a business, which can have associated cards on file. 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`

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
CreateCustomerRequest body = new CreateCustomerRequest(); // CreateCustomerRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.
try {
    CreateCustomerResponse result = apiInstance.createCustomer(body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#createCustomer");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
body CreateCustomerRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

CreateCustomerResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

createCustomerCard

CreateCustomerCardResponse createCustomerCard(customerId, body)

CreateCustomerCard

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. Cards on file are automatically updated on a monthly basis to confirm they are still valid and can be charged.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String customerId = "customerId_example"; // String | The Square ID of the customer profile the card is linked to.
CreateCustomerCardRequest body = new CreateCustomerCardRequest(); // CreateCustomerCardRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.
try {
    CreateCustomerCardResponse result = apiInstance.createCustomerCard(customerId, body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#createCustomerCard");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
customerId String The Square ID of the customer profile the card is linked to.
body CreateCustomerCardRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

CreateCustomerCardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

deleteCustomer

DeleteCustomerResponse deleteCustomer(customerId)

DeleteCustomer

Deletes a customer from a business, along with any linked cards on file. When two profiles are merged into a single profile, that profile is assigned a new `customer_id`. You must use the new `customer_id` to delete merged profiles.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String customerId = "customerId_example"; // String | The ID of the customer to delete.
try {
    DeleteCustomerResponse result = apiInstance.deleteCustomer(customerId);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#deleteCustomer");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
customerId String The ID of the customer to delete.

Return type

DeleteCustomerResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

deleteCustomerCard

DeleteCustomerCardResponse deleteCustomerCard(customerId, cardId)

DeleteCustomerCard

Removes a card on file from a customer.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String customerId = "customerId_example"; // String | The ID of the customer that the card on file belongs to.
String cardId = "cardId_example"; // String | The ID of the card on file to delete.
try {
    DeleteCustomerCardResponse result = apiInstance.deleteCustomerCard(customerId, cardId);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#deleteCustomerCard");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
customerId String The ID of the customer that the card on file belongs to.
cardId String The ID of the card on file to delete.

Return type

DeleteCustomerCardResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

listCustomers

ListCustomersResponse listCustomers(cursor, sortField, sortOrder)

ListCustomers

Lists a business's customers.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String cursor = "cursor_example"; // String | A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.  See [Pagination](/basics/api101/pagination) for more information.
String sortField = "sortField_example"; // String | Indicates how Customers should be sorted. Default: `DEFAULT`.
String sortOrder = "sortOrder_example"; // String | Indicates whether Customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. Default: `ASC`.
try {
    ListCustomersResponse result = apiInstance.listCustomers(cursor, sortField, sortOrder);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#listCustomers");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
cursor String A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Pagination for more information. [optional]
sortField String Indicates how Customers should be sorted. Default: `DEFAULT`. [optional] [enum: DEFAULT, CREATED_AT]
sortOrder String Indicates whether Customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. Default: `ASC`. [optional] [enum: DESC, ASC]

Return type

ListCustomersResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

retrieveCustomer

RetrieveCustomerResponse retrieveCustomer(customerId)

RetrieveCustomer

Returns details for a single customer.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String customerId = "customerId_example"; // String | The ID of the customer to retrieve.
try {
    RetrieveCustomerResponse result = apiInstance.retrieveCustomer(customerId);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#retrieveCustomer");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
customerId String The ID of the customer to retrieve.

Return type

RetrieveCustomerResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

searchCustomers

SearchCustomersResponse searchCustomers(body)

SearchCustomers

Searches the customer profiles associated with a Square account. Calling SearchCustomers without an explicit query parameter returns all customer profiles ordered alphabetically based on `given_name` and `family_name`.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
SearchCustomersRequest body = new SearchCustomersRequest(); // SearchCustomersRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.
try {
    SearchCustomersResponse result = apiInstance.searchCustomers(body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#searchCustomers");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
body SearchCustomersRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

SearchCustomersResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

updateCustomer

UpdateCustomerResponse updateCustomer(customerId, body)

UpdateCustomer

Updates the details of an existing customer. When two profiles are merged into a single profile, that profile is assigned a new `customer_id`. You must use the new `customer_id` to update merged profiles. You cannot edit a customer's cards on file with this endpoint. To make changes to a card on file, you must delete the existing card on file with the DeleteCustomerCard endpoint, then create a new one with the CreateCustomerCard endpoint.

Example

// Import classes:
//import com.squareup.connect.ApiClient;
//import com.squareup.connect.ApiException;
//import com.squareup.connect.Configuration;
//import com.squareup.connect.auth.*;
//import com.squareup.connect.api.CustomersApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth2
OAuth oauth2 = (OAuth) defaultClient.getAuthentication("oauth2");
oauth2.setAccessToken("YOUR ACCESS TOKEN");

CustomersApi apiInstance = new CustomersApi();
String customerId = "customerId_example"; // String | The ID of the customer to update.
UpdateCustomerRequest body = new UpdateCustomerRequest(); // UpdateCustomerRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.
try {
    UpdateCustomerResponse result = apiInstance.updateCustomer(customerId, body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling CustomersApi#updateCustomer");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
customerId String The ID of the customer to update.
body UpdateCustomerRequest An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

UpdateCustomerResponse

Authorization

oauth2

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json