Class: Square::CustomersApi

Inherits:
BaseApi
  • Object
show all
Defined in:
lib/square/api/customers_api.rb

Overview

CustomersApi

Instance Attribute Summary

Attributes inherited from BaseApi

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseApi

#initialize, #new_api_call_builder, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from Square::BaseApi

Instance Method Details

#add_group_to_customer(customer_id:, group_id:) ⇒ AddGroupToCustomerResponse Hash

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. add to a group. to add the customer to.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

  • group_id (String) —

    Required parameter: The ID of the customer group

Returns:

  • (AddGroupToCustomerResponse Hash) —

    response from the API call



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/square/api/customers_api.rb', line 311

def add_group_to_customer(customer_id:,
                          group_id:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/v2/customers/{customer_id}/groups/{group_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .template_param(new_parameter(group_id, key: 'group_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#create_customer(body:) ⇒ CreateCustomerResponse Hash

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`

containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • body (CreateCustomerRequest) —

    Required parameter: An object

Returns:

  • (CreateCustomerResponse Hash) —

    response from the API call



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/square/api/customers_api.rb', line 69

def create_customer(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers',
                                 'default')
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#create_customer_card(customer_id:, body:) ⇒ CreateCustomerCardResponse Hash

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. customer profile the card is linked to. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • customer_id (String) —

    Required parameter: The Square ID of the

  • body (CreateCustomerCardRequest) —

    Required parameter: An object

Returns:

  • (CreateCustomerCardResponse Hash) —

    response from the API call



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/square/api/customers_api.rb', line 229

def create_customer_card(customer_id:,
                         body:)
  warn 'Endpoint create_customer_card in CustomersApi is deprecated'
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/{customer_id}/cards',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#delete_customer(customer_id:, version: nil) ⇒ DeleteCustomerResponse Hash

Deletes a customer profile from a business. This operation also unlinks any associated cards on file. As a best practice, include the ‘version` field in the request to enable [optimistic concurrency](developer.squareup.com/docs/build-basics/common-api-p atterns/optimistic-concurrency) control. If included, 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. delete. customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](developer.squareup.com/docs/build-basics/common-api-p atterns/optimistic-concurrency) control. For more information, see [Delete a customer profile](developer.squareup.com/docs/customers-api/use-the-api/kee p-records#delete-customer-profile).

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

  • version (Integer) (defaults to: nil) —

    Optional parameter: The current version of the

Returns:

  • (DeleteCustomerResponse Hash) —

    response from the API call



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/square/api/customers_api.rb', line 139

def delete_customer(customer_id:,
                    version: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/v2/customers/{customer_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .query_param(new_parameter(version, key: 'version'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#delete_customer_card(customer_id:, card_id:) ⇒ DeleteCustomerCardResponse Hash

Removes a card on file from a customer. that the card on file belongs to. delete.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer

  • card_id (String) —

    Required parameter: The ID of the card on file to

Returns:

  • (DeleteCustomerCardResponse Hash) —

    response from the API call



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/square/api/customers_api.rb', line 256

def delete_customer_card(customer_id:,
                         card_id:)
  warn 'Endpoint delete_customer_card in CustomersApi is deprecated'
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/v2/customers/{customer_id}/cards/{card_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .template_param(new_parameter(card_id, key: 'card_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#list_customers(cursor: nil, limit: nil, sort_field: nil, sort_order: nil, count: false) ⇒ ListCustomersResponse Hash

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. 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](developer.squareup.com/docs/build-basics/common-api-p atterns/pagination). 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](developer.squareup.com/docs/build-basics/common-api-p atterns/pagination). customers should be sorted. The default value is `DEFAULT`. customers should be sorted in ascending (`ASC`) or descending (`DESC`) order. The default value is `ASC`. whether to return the total count of customers in the `count` field of the response. The default value is `false`.

Parameters:

  • cursor (String) (defaults to: nil) —

    Optional parameter: A pagination cursor returned by

  • limit (Integer) (defaults to: nil) —

    Optional parameter: The maximum number of results

  • sort_field (CustomerSortField) (defaults to: nil) —

    Optional parameter: Indicates how

  • sort_order (SortOrder) (defaults to: nil) —

    Optional parameter: Indicates whether

  • count (TrueClass | FalseClass) (defaults to: false) —

    Optional parameter: Indicates

Returns:

  • (ListCustomersResponse Hash) —

    response from the API call



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/square/api/customers_api.rb', line 33

def list_customers(cursor: nil,
                   limit: nil,
                   sort_field: nil,
                   sort_order: nil,
                   count: false)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/v2/customers',
                                 'default')
               .query_param(new_parameter(cursor, key: 'cursor'))
               .query_param(new_parameter(limit, key: 'limit'))
               .query_param(new_parameter(sort_field, key: 'sort_field'))
               .query_param(new_parameter(sort_order, key: 'sort_order'))
               .query_param(new_parameter(count, key: 'count'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#remove_group_from_customer(customer_id:, group_id:) ⇒ RemoveGroupFromCustomerResponse Hash

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. remove from the group. to remove the customer from.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

  • group_id (String) —

    Required parameter: The ID of the customer group

Returns:

  • (RemoveGroupFromCustomerResponse Hash) —

    response from the API call



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/square/api/customers_api.rb', line 284

def remove_group_from_customer(customer_id:,
                               group_id:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/v2/customers/{customer_id}/groups/{group_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .template_param(new_parameter(group_id, key: 'group_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#retrieve_customer(customer_id:) ⇒ RetrieveCustomerResponse Hash

Returns details for a single customer. retrieve.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

Returns:

  • (RetrieveCustomerResponse Hash) —

    response from the API call



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/square/api/customers_api.rb', line 161

def retrieve_customer(customer_id:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/v2/customers/{customer_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#search_customers(body:) ⇒ SearchCustomersResponse Hash

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. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • body (SearchCustomersRequest) —

    Required parameter: An object

Returns:

  • (SearchCustomersResponse Hash) —

    response from the API call



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/square/api/customers_api.rb', line 101

def search_customers(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/search',
                                 'default')
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end

#update_customer(customer_id:, body:) ⇒ UpdateCustomerResponse Hash

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` and include the `X-Clear-Null` header set to `true` (recommended) or specify an empty string (string fields only). As a best practice, include the `version` field in the request to enable [optimistic concurrency](developer.squareup.com/docs/build-basics/common-api-p atterns/optimistic-concurrency) control. If included, 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). update. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

  • body (UpdateCustomerRequest) —

    Required parameter: An object

Returns:

  • (UpdateCustomerResponse Hash) —

    response from the API call



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/square/api/customers_api.rb', line 198

def update_customer(customer_id:,
                    body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/v2/customers/{customer_id}',
                                 'default')
               .template_param(new_parameter(customer_id, key: 'customer_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('global')))
    .response(new_response_handler
               .deserializer(APIHelper.method(:json_deserialize))
               .is_api_response(true)
               .convertor(ApiResponse.method(:create)))
    .execute
end