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

#execute_request, #validate_parameters

Constructor Details

#initialize(config, http_call_back: nil) ⇒ CustomersApi

Returns a new instance of CustomersApi.



4
5
6
 
# File 'lib/square/api/customers_api.rb', line 4

def initialize(config, http_call_back: nil)
  super(config, http_call_back: http_call_back)
end

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



432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
 
# File 'lib/square/api/customers_api.rb', line 432

def add_group_to_customer(customer_id:,
                          group_id:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}/groups/{group_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true },
    'group_id' => { 'value' => group_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.put(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/square/api/customers_api.rb', line 82

def create_customer(body:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers'
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'content-type' => 'application/json; charset=utf-8'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.post(
    _query_url,
    headers: _headers,
    parameters: body.to_json
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/square/api/customers_api.rb', line 308

def create_customer_card(customer_id:,
                         body:)
  warn 'Endpoint create_customer_card in CustomersApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}/cards'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'content-type' => 'application/json; charset=utf-8'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.post(
    _query_url,
    headers: _headers,
    parameters: body.to_json
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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, you should include the `version` field in the request to enable [optimistic concurrency](developer.squareup.com/docs/working-with-apis/optimis tic-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. delete. customer profile. As a best practice, you should include this parameter to enable [optimistic concurrency](developer.squareup.com/docs/working-with-apis/optimis tic-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 (Long) (defaults to: nil) —

    Optional parameter: The current version of the

Returns:

  • (DeleteCustomerResponse Hash) —

    response from the API call



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/square/api/customers_api.rb', line 174

def delete_customer(customer_id:,
                    version: nil)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true }
  )
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'version' => version
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.delete(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/square/api/customers_api.rb', line 349

def delete_customer_card(customer_id:,
                         card_id:)
  warn 'Endpoint delete_customer_card in CustomersApi is deprecated'
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}/cards/{card_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true },
    'card_id' => { 'value' => card_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.delete(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
end

#list_customers(cursor: nil, limit: nil, sort_field: nil, sort_order: nil) ⇒ 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/working-with-apis/paginat ion). to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 100. The default value is 100. For more information, see [Pagination](developer.squareup.com/docs/working-with-apis/paginat ion). 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`.

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

Returns:

  • (ListCustomersResponse Hash) —

    response from the API call



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/square/api/customers_api.rb', line 32

def list_customers(cursor: nil,
                   limit: nil,
                   sort_field: nil,
                   sort_order: nil)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers'
  _query_builder = APIHelper.append_url_with_query_parameters(
    _query_builder,
    'cursor' => cursor,
    'limit' => limit,
    'sort_field' => sort_field,
    'sort_order' => sort_order
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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



391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/square/api/customers_api.rb', line 391

def remove_group_from_customer(customer_id:,
                               group_id:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}/groups/{group_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true },
    'group_id' => { 'value' => group_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.delete(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
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



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/square/api/customers_api.rb', line 214

def retrieve_customer(customer_id:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.get(
    _query_url,
    headers: _headers
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
end

#search_customers(body:) ⇒ SearchCustomersResponse Hash

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



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/square/api/customers_api.rb', line 126

def search_customers(body:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/search'
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'content-type' => 'application/json; charset=utf-8'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.post(
    _query_url,
    headers: _headers,
    parameters: body.to_json
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
end

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

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](developer.squareup.com/docs/working-with-apis/optimis tic-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). 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



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/square/api/customers_api.rb', line 263

def update_customer(customer_id:,
                    body:)
  # Prepare query url.
  _query_builder = config.get_base_uri
  _query_builder << '/v2/customers/{customer_id}'
  _query_builder = APIHelper.append_url_with_template_parameters(
    _query_builder,
    'customer_id' => { 'value' => customer_id, 'encode' => true }
  )
  _query_url = APIHelper.clean_url _query_builder

  # Prepare headers.
  _headers = {
    'accept' => 'application/json',
    'content-type' => 'application/json; charset=utf-8'
  }

  # Prepare and execute HttpRequest.
  _request = config.http_client.put(
    _query_url,
    headers: _headers,
    parameters: body.to_json
  )
  OAuth2.apply(config, _request)
  _response = execute_request(_request)

  # Return appropriate response type.
  decoded = APIHelper.json_deserialize(_response.raw_body)
  _errors = APIHelper.map_response(decoded, ['errors'])
  ApiResponse.new(
    _response, data: decoded, errors: _errors
  )
end