Customers

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

function listCustomers(
    ?string $cursor = null,
    ?int $limit = null,
    ?string $sortField = null,
    ?string $sortOrder = null,
    ?bool $count = false
): ApiResponse

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`	`?int`	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(CustomerSortField)`	Query, Optional	Indicates how customers should be sorted. The default value is `DEFAULT`.
`sortOrder`	`?string(SortOrder)`	Query, Optional	Indicates whether customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`.
`count`	`?bool`	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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type ListCustomersResponse.

Example Usage

$count = false;

$apiResponse = $customersApi->listCustomers(
    null,
    null,
    null,
    null,
    $count
);

if ($apiResponse->isSuccess()) {
    $listCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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

function createCustomer(CreateCustomerRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type CreateCustomerResponse.

Example Usage

$body = CreateCustomerRequestBuilder::init()
    ->givenName('Amelia')
    ->familyName('Earhart')
    ->emailAddress('Amelia.Earhart@example.com')
    ->address(
        AddressBuilder::init()
            ->addressLine1('500 Electric Ave')
            ->addressLine2('Suite 600')
            ->locality('New York')
            ->administrativeDistrictLevel1('NY')
            ->postalCode('10003')
            ->country(Country::US)
            ->build()
    )
    ->phoneNumber('+1-212-555-4240')
    ->referenceId('YOUR_REFERENCE_ID')
    ->note('a customer')
    ->build();

$apiResponse = $customersApi->createCustomer($body);

if ($apiResponse->isSuccess()) {
    $createCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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

function bulkCreateCustomers(BulkCreateCustomersRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type BulkCreateCustomersResponse.

Example Usage

$body = BulkCreateCustomersRequestBuilder::init(
    [
        '8bb76c4f-e35d-4c5b-90de-1194cd9179f0' => BulkCreateCustomerDataBuilder::init()
            ->givenName('Amelia')
            ->familyName('Earhart')
            ->emailAddress('Amelia.Earhart@example.com')
            ->address(
                AddressBuilder::init()
                    ->addressLine1('500 Electric Ave')
                    ->addressLine2('Suite 600')
                    ->locality('New York')
                    ->administrativeDistrictLevel1('NY')
                    ->postalCode('10003')
                    ->country(Country::US)
                    ->build()
            )
            ->phoneNumber('+1-212-555-4240')
            ->referenceId('YOUR_REFERENCE_ID')
            ->note('a customer')
            ->build(),
        'd1689f23-b25d-4932-b2f0-aed00f5e2029' => BulkCreateCustomerDataBuilder::init()
            ->givenName('Marie')
            ->familyName('Curie')
            ->emailAddress('Marie.Curie@example.com')
            ->address(
                AddressBuilder::init()
                    ->addressLine1('500 Electric Ave')
                    ->addressLine2('Suite 601')
                    ->locality('New York')
                    ->administrativeDistrictLevel1('NY')
                    ->postalCode('10003')
                    ->country(Country::US)
                    ->build()
            )
            ->phoneNumber('+1-212-444-4240')
            ->referenceId('YOUR_REFERENCE_ID')
            ->note('another customer')
            ->build()
    ]
)->build();

$apiResponse = $customersApi->bulkCreateCustomers($body);

if ($apiResponse->isSuccess()) {
    $bulkCreateCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Bulk Delete Customers

Deletes multiple customer profiles.

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

function bulkDeleteCustomers(BulkDeleteCustomersRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type BulkDeleteCustomersResponse.

Example Usage

$body = BulkDeleteCustomersRequestBuilder::init(
    [
        '8DDA5NZVBZFGAX0V3HPF81HHE0',
        'N18CPRVXR5214XPBBA6BZQWF3C',
        '2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
    ]
)->build();

$apiResponse = $customersApi->bulkDeleteCustomers($body);

if ($apiResponse->isSuccess()) {
    $bulkDeleteCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Bulk Retrieve Customers

Retrieves multiple customer profiles.

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

function bulkRetrieveCustomers(BulkRetrieveCustomersRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type BulkRetrieveCustomersResponse.

Example Usage

$body = BulkRetrieveCustomersRequestBuilder::init(
    [
        '8DDA5NZVBZFGAX0V3HPF81HHE0',
        'N18CPRVXR5214XPBBA6BZQWF3C',
        '2GYD7WNXF7BJZW1PMGNXZ3Y8M8'
    ]
)->build();

$apiResponse = $customersApi->bulkRetrieveCustomers($body);

if ($apiResponse->isSuccess()) {
    $bulkRetrieveCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function bulkUpdateCustomers(BulkUpdateCustomersRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type BulkUpdateCustomersResponse.

Example Usage

$body = BulkUpdateCustomersRequestBuilder::init(
    [
        '8DDA5NZVBZFGAX0V3HPF81HHE0' => BulkUpdateCustomerDataBuilder::init()
            ->emailAddress('New.Amelia.Earhart@example.com')
            ->phoneNumber('phone_number2')
            ->note('updated customer note')
            ->version(2)
            ->build(),
        'N18CPRVXR5214XPBBA6BZQWF3C' => BulkUpdateCustomerDataBuilder::init()
            ->givenName('Marie')
            ->familyName('Curie')
            ->version(0)
            ->build()
    ]
)->build();

$apiResponse = $customersApi->bulkUpdateCustomers($body);

if ($apiResponse->isSuccess()) {
    $bulkUpdateCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function searchCustomers(SearchCustomersRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type SearchCustomersResponse.

Example Usage

$body = SearchCustomersRequestBuilder::init()
    ->limit(2)
    ->query(
        CustomerQueryBuilder::init()
            ->filter(
                CustomerFilterBuilder::init()
                    ->creationSource(
                        CustomerCreationSourceFilterBuilder::init()
                            ->values(
                                [
                                    CustomerCreationSource::THIRD_PARTY
                                ]
                            )
                            ->rule(CustomerInclusionExclusion::INCLUDE_)
                            ->build()
                    )
                    ->createdAt(
                        TimeRangeBuilder::init()
                            ->startAt('2018-01-01T00:00:00-00:00')
                            ->endAt('2018-02-01T00:00:00-00:00')
                            ->build()
                    )
                    ->emailAddress(
                        CustomerTextFilterBuilder::init()
                            ->fuzzy('example.com')
                            ->build()
                    )
                    ->groupIds(
                        FilterValueBuilder::init()
                            ->all(
                                [
                                    '545AXB44B4XXWMVQ4W8SBT3HHF'
                                ]
                            )
                            ->build()
                    )
                    ->build()
            )
            ->sort(
                CustomerSortBuilder::init()
                    ->field(CustomerSortField::CREATED_AT)
                    ->order(SortOrder::ASC)
                    ->build()
            )
            ->build()
    )
    ->build();

$apiResponse = $customersApi->searchCustomers($body);

if ($apiResponse->isSuccess()) {
    $searchCustomersResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function deleteCustomer(string $customerId, ?int $version = null): ApiResponse

Parameters

Parameter	Type	Tags	Description
`customerId`	`string`	Template, Required	The ID of the customer to delete.
`version`	`?int`	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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type DeleteCustomerResponse.

Example Usage

$customerId = 'customer_id8';

$apiResponse = $customersApi->deleteCustomer($customerId);

if ($apiResponse->isSuccess()) {
    $deleteCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Retrieve Customer

Returns details for a single customer.

function retrieveCustomer(string $customerId): ApiResponse

Parameters

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

Response Type

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type RetrieveCustomerResponse.

Example Usage

$customerId = 'customer_id8';

$apiResponse = $customersApi->retrieveCustomer($customerId);

if ($apiResponse->isSuccess()) {
    $retrieveCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function updateCustomer(string $customerId, UpdateCustomerRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type UpdateCustomerResponse.

Example Usage

$customerId = 'customer_id8';

$body = UpdateCustomerRequestBuilder::init()
    ->emailAddress('New.Amelia.Earhart@example.com')
    ->phoneNumber('phone_number2')
    ->note('updated customer note')
    ->version(2)
    ->build();

$apiResponse = $customersApi->updateCustomer(
    $customerId,
    $body
);

if ($apiResponse->isSuccess()) {
    $updateCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function createCustomerCard(string $customerId, CreateCustomerCardRequest $body): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type CreateCustomerCardResponse.

Example Usage

$customerId = 'customer_id8';

$body = CreateCustomerCardRequestBuilder::init(
    'YOUR_CARD_NONCE'
)
    ->billingAddress(
        AddressBuilder::init()
            ->addressLine1('500 Electric Ave')
            ->addressLine2('Suite 600')
            ->locality('New York')
            ->administrativeDistrictLevel1('NY')
            ->postalCode('10003')
            ->country(Country::US)
            ->build()
    )
    ->cardholderName('Amelia Earhart')
    ->build();

$apiResponse = $customersApi->createCustomerCard(
    $customerId,
    $body
);

if ($apiResponse->isSuccess()) {
    $createCustomerCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Delete Customer Card

This endpoint is deprecated.

Removes a card on file from a customer.

function deleteCustomerCard(string $customerId, string $cardId): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type DeleteCustomerCardResponse.

Example Usage

$customerId = 'customer_id8';

$cardId = 'card_id4';

$apiResponse = $customersApi->deleteCustomerCard(
    $customerId,
    $cardId
);

if ($apiResponse->isSuccess()) {
    $deleteCustomerCardResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function removeGroupFromCustomer(string $customerId, string $groupId): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type RemoveGroupFromCustomerResponse.

Example Usage

$customerId = 'customer_id8';

$groupId = 'group_id0';

$apiResponse = $customersApi->removeGroupFromCustomer(
    $customerId,
    $groupId
);

if ($apiResponse->isSuccess()) {
    $removeGroupFromCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

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.

function addGroupToCustomer(string $customerId, string $groupId): ApiResponse

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

This method returns a Square\Utils\ApiResponse instance. The getResult() method on this instance returns the response data which is of type AddGroupToCustomerResponse.

Example Usage

$customerId = 'customer_id8';

$groupId = 'group_id0';

$apiResponse = $customersApi->addGroupToCustomer(
    $customerId,
    $groupId
);

if ($apiResponse->isSuccess()) {
    $addGroupToCustomerResponse = $apiResponse->getResult();
} else {
    $errors = $apiResponse->getErrors();
}

// Getting more response information
var_dump($apiResponse->getStatusCode());
var_dump($apiResponse->getHeaders());

Files

customers.md

Latest commit

History

customers.md

File metadata and controls

Customers

Class Name

Methods

List Customers

Parameters

Response Type

Example Usage

Create Customer

Parameters

Response Type

Example Usage

Bulk Create Customers

Parameters

Response Type

Example Usage

Bulk Delete Customers

Parameters

Response Type

Example Usage

Bulk Retrieve Customers

Parameters

Response Type

Example Usage

Bulk Update Customers

Parameters

Response Type

Example Usage

Search Customers

Parameters

Response Type

Example Usage

Delete Customer

Parameters

Response Type

Example Usage

Retrieve Customer

Parameters

Response Type

Example Usage

Update Customer

Parameters

Response Type

Example Usage

Create Customer Card

Parameters

Response Type

Example Usage

Delete Customer Card

Parameters

Response Type

Example Usage

Remove Group From Customer

Parameters

Response Type

Example Usage

Add Group to Customer

Parameters

Response Type

Example Usage