Class: Square::Customers::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/square/customers/client.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ void

Parameters:



9
10
11
 
# File 'lib/square/customers/client.rb', line 9

def initialize(client:)
  @client = client
end

Instance Method Details

#batch_create(request_options: {}, **params) ⇒ Square::Types::BulkCreateCustomersResponse

Creates multiple [customer profiles](entity: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`

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/square/customers/client.rb', line 136

def batch_create(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers/bulk-create",
    body: Square::Customers::Types::BulkCreateCustomersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::BulkCreateCustomersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#bulk_delete_customers(request_options: {}, **params) ⇒ Square::Types::BulkDeleteCustomersResponse

Deletes multiple customer profiles.

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

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/square/customers/client.rb', line 172

def bulk_delete_customers(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers/bulk-delete",
    body: Square::Customers::Types::BulkDeleteCustomersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::BulkDeleteCustomersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#bulk_retrieve_customers(request_options: {}, **params) ⇒ Square::Types::BulkRetrieveCustomersResponse

Retrieves multiple customer profiles.

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

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/square/customers/client.rb', line 208

def bulk_retrieve_customers(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers/bulk-retrieve",
    body: Square::Customers::Types::BulkRetrieveCustomersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::BulkRetrieveCustomersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#bulk_update_customers(request_options: {}, **params) ⇒ Square::Types::BulkUpdateCustomersResponse

Updates multiple customer profiles.

This endpoint takes a map of individual update requests and returns a map of responses.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/square/customers/client.rb', line 244

def bulk_update_customers(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers/bulk-update",
    body: Square::Customers::Types::BulkUpdateCustomersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::BulkUpdateCustomersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#cards ⇒ Square::Cards::Client

Returns:



447
448
449
 
# File 'lib/square/customers/client.rb', line 447

def cards
  @cards ||= Square::Customers::Cards::Client.new(client: @client)
end

#create(request_options: {}, **params) ⇒ Square::Types::CreateCustomerResponse

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`

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/square/customers/client.rb', line 92

def create(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers",
    body: Square::Customers::Types::CreateCustomerRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::CreateCustomerResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#custom_attribute_definitions ⇒ Square::CustomAttributeDefinitions::Client

Returns:

  • (Square::CustomAttributeDefinitions::Client) 


432
433
434
 
# File 'lib/square/customers/client.rb', line 432

def custom_attribute_definitions
  @custom_attribute_definitions ||= Square::Customers::CustomAttributeDefinitions::Client.new(client: @client)
end

#custom_attributes ⇒ Square::CustomAttributes::Client

Returns:

  • (Square::CustomAttributes::Client) 


452
453
454
 
# File 'lib/square/customers/client.rb', line 452

def custom_attributes
  @custom_attributes ||= Square::Customers::CustomAttributes::Client.new(client: @client)
end

#delete(request_options: {}, **params) ⇒ Square::Types::DeleteCustomerResponse

Deletes a customer profile from a business.

To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :customer_id (String)
  • :version (Integer, nil)

Returns:



403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/square/customers/client.rb', line 403

def delete(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  query_param_names = %i[version]
  query_params = {}
  query_params["version"] = params[:version] if params.key?(:version)
  params = params.except(*query_param_names)

  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "DELETE",
    path: "v2/customers/#{params[:customer_id]}",
    query: query_params,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::DeleteCustomerResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#get(request_options: {}, **params) ⇒ Square::Types::GetCustomerResponse

Returns details for a single customer.

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :customer_id (String)

Returns:



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/square/customers/client.rb', line 321

def get(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v2/customers/#{params[:customer_id]}",
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::GetCustomerResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#groups ⇒ Square::Groups::Client

Returns:

  • (Square::Groups::Client) 


437
438
439
 
# File 'lib/square/customers/client.rb', line 437

def groups
  @groups ||= Square::Customers::Groups::Client.new(client: @client)
end

#list(request_options: {}, **params) ⇒ Square::Types::ListCustomersResponse

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.

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

Returns:



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
68
69
70
 
# File 'lib/square/customers/client.rb', line 33

def list(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  query_param_names = %i[cursor limit sort_field sort_order count]
  query_params = {}
  query_params["cursor"] = params[:cursor] if params.key?(:cursor)
  query_params["limit"] = params[:limit] if params.key?(:limit)
  query_params["sort_field"] = params[:sort_field] if params.key?(:sort_field)
  query_params["sort_order"] = params[:sort_order] if params.key?(:sort_order)
  query_params["count"] = params[:count] if params.key?(:count)
  params.except(*query_param_names)

  Square::Internal::CursorItemIterator.new(
    cursor_field: :cursor,
    item_field: :customers,
    initial_cursor: query_params[:cursor]
  ) do |next_cursor|
    query_params[:cursor] = next_cursor
    request = Square::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "v2/customers",
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise Square::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      Square::Types::ListCustomersResponse.load(response.body)
    else
      error_class = Square::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#search(request_options: {}, **params) ⇒ Square::Types::SearchCustomersResponse

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.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



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

def search(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "v2/customers/search",
    body: Square::Customers::Types::SearchCustomersRequest.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::SearchCustomersResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#segments ⇒ Square::Segments::Client

Returns:

  • (Square::Segments::Client) 


442
443
444
 
# File 'lib/square/customers/client.rb', line 442

def segments
  @segments ||= Square::Customers::Segments::Client.new(client: @client)
end

#update(request_options: {}, **params) ⇒ Square::Types::UpdateCustomerResponse

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.

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :customer_id (String)

Returns:



360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/square/customers/client.rb', line 360

def update(request_options: {}, **params)
  params = Square::Internal::Types::Utils.normalize_keys(params)
  request_data = Square::Customers::Types::UpdateCustomerRequest.new(params).to_h
  non_body_param_names = ["customer_id"]
  body = request_data.except(*non_body_param_names)

  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PUT",
    path: "v2/customers/#{params[:customer_id]}",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Square::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Square::Types::UpdateCustomerResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end