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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

Returns details for a single customer. retrieve.

Parameters:

  • customer_id (String) —

    Required parameter: The ID of the customer to

Returns:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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:) ⇒ ApiResponse

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:

  • (ApiResponse) —

    the complete http response with raw body and status code.



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