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



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/square/api/customers_api.rb', line 401

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

#bulk_create_customers(body:) ⇒ BulkCreateCustomersResponse Hash

Creates multiple [customer profiles]($m/Customer) 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`

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

Parameters:

  • body (BulkCreateCustomersRequest) —

    Required parameter: An object

Returns:

  • (BulkCreateCustomersResponse Hash) —

    response from the API call



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

def bulk_create_customers(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/bulk-create',
                                 '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

#bulk_delete_customers(body:) ⇒ BulkDeleteCustomersResponse Hash

Deletes multiple customer profiles. The endpoint takes a list of customer IDs and returns a map of responses. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • body (BulkDeleteCustomersRequest) —

    Required parameter: An object

Returns:

  • (BulkDeleteCustomersResponse Hash) —

    response from the API call



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/square/api/customers_api.rb', line 123

def bulk_delete_customers(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/bulk-delete',
                                 '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

#bulk_retrieve_customers(body:) ⇒ BulkRetrieveCustomersResponse Hash

Retrieves multiple customer profiles. This endpoint takes a list of customer IDs and returns a map of responses. containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • body (BulkRetrieveCustomersRequest) —

    Required parameter: An object

Returns:

  • (BulkRetrieveCustomersResponse Hash) —

    response from the API call



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/square/api/customers_api.rb', line 146

def bulk_retrieve_customers(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/bulk-retrieve',
                                 '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

#bulk_update_customers(body:) ⇒ BulkUpdateCustomersResponse Hash

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]($e/Cards) or [Gift Cards API]($e/GiftCards). containing the fields to POST for the request. See the corresponding object definition for field details.

Parameters:

  • body (BulkUpdateCustomersRequest) —

    Required parameter: An object

Returns:

  • (BulkUpdateCustomersResponse Hash) —

    response from the API call



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/square/api/customers_api.rb', line 172

def bulk_update_customers(body:)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/v2/customers/bulk-update',
                                 '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(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



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/square/api/customers_api.rb', line 319

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



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/square/api/customers_api.rb', line 236

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



346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/square/api/customers_api.rb', line 346

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



374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/square/api/customers_api.rb', line 374

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



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

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



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/square/api/customers_api.rb', line 204

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



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/square/api/customers_api.rb', line 288

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