Class: Square::Catalog::Client

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

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ void

Parameters:



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

def initialize(client:)
  @client = client
end

Instance Method Details

#batch_delete(request_options: {}, **params) ⇒ Square::Types::BatchDeleteCatalogObjectsResponse

Deletes a set of [CatalogItem](entity:CatalogItem)s based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its [CatalogItemVariation](entity:CatalogItemVariation) children.

‘BatchDeleteCatalogObjects` succeeds even if only a portion of the targeted IDs can be deleted. The response will only include IDs that were actually deleted.

To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the ‘429` error code.

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:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/square/catalog/client.rb', line 37

def batch_delete(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/catalog/batch-delete",
    body: Square::Catalog::Types::BatchDeleteCatalogObjectsRequest.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::BatchDeleteCatalogObjectsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#batch_get(request_options: {}, **params) ⇒ Square::Types::BatchGetCatalogObjectsResponse

Returns a set of objects based on the provided ID. Each [CatalogItem](entity:CatalogItem) returned in the set includes all of its child information including: all of its [CatalogItemVariation](entity:CatalogItemVariation) objects, references to its [CatalogModifierList](entity:CatalogModifierList) objects, and the ids of any [CatalogTax](entity:CatalogTax) objects that apply to it.

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:



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/square/catalog/client.rb', line 76

def batch_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: "POST",
    path: "v2/catalog/batch-retrieve",
    body: Square::Catalog::Types::BatchGetCatalogObjectsRequest.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::BatchGetCatalogObjectsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#batch_upsert(request_options: {}, **params) ⇒ Square::Types::BatchUpsertCatalogObjectsResponse

Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.

To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the ‘429` error code.

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:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/square/catalog/client.rb', line 122

def batch_upsert(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/catalog/batch-upsert",
    body: Square::Catalog::Types::BatchUpsertCatalogObjectsRequest.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::BatchUpsertCatalogObjectsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#images ⇒ Square::Images::Client

Returns:

  • (Square::Images::Client) 


406
407
408
 
# File 'lib/square/catalog/client.rb', line 406

def images
  @images ||= Square::Catalog::Images::Client.new(client: @client)
end

#info(request_options: {}, **params) ⇒ Square::Types::CatalogInfoResponse

Retrieves information about the Square Catalog API, such as batch size limits that can be used by the ‘BatchUpsertCatalogObjects` endpoint.

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)

Returns:



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/square/catalog/client.rb', line 157

def info(request_options: {}, **params)
  Square::Internal::Types::Utils.normalize_keys(params)
  request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "v2/catalog/info",
    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::CatalogInfoResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

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

Returns a list of all [CatalogObject](entity:CatalogObject)s of the specified types in the catalog.

The ‘types` parameter is specified as a comma-separated list of the [CatalogObjectType](entity:CatalogObjectType) values, for example, “`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`, `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`”.

Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) and set the ‘include_deleted_objects` attribute value to `true`.

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

  • :cursor (String, nil)
  • :types (String, nil)
  • :catalog_version (Integer, nil)

Returns:



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/square/catalog/client.rb', line 201

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

  Square::Internal::CursorItemIterator.new(
    cursor_field: :cursor,
    item_field: :objects,
    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/catalog/list",
      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::ListCatalogResponse.load(response.body)
    else
      error_class = Square::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#object ⇒ Square::Object_::Client

Returns:

  • (Square::Object_::Client) 


411
412
413
 
# File 'lib/square/catalog/client.rb', line 411

def object
  @object ||= Square::Catalog::Object_::Client.new(client: @client)
end

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

Searches for [CatalogObject](entity:CatalogObject) of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters.

This (‘SearchCatalogObjects`) endpoint differs from the [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint in the following aspects:

  • ‘SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search

for any type of catalog objects.

  • ‘SearchCatalogItems` supports the custom attribute query filters to return items or item variations that

contain custom attribute values, where ‘SearchCatalogObjects` does not.

  • ‘SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item

variations, whereas ‘SearchCatalogObjects` does.

  • The both endpoints have different call conventions, including the query filter formats.

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:



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/square/catalog/client.rb', line 263

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/catalog/search",
    body: Square::Catalog::Types::SearchCatalogObjectsRequest.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::SearchCatalogObjectsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#search_items(request_options: {}, **params) ⇒ Square::Types::SearchCatalogItemsResponse

Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters.

This (‘SearchCatalogItems`) endpoint differs from the [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects) endpoint in the following aspects:

  • ‘SearchCatalogItems` can only search for items or item variations, whereas `SearchCatalogObjects` can search

for any type of catalog objects.

  • ‘SearchCatalogItems` supports the custom attribute query filters to return items or item variations that

contain custom attribute values, where ‘SearchCatalogObjects` does not.

  • ‘SearchCatalogItems` does not support the `include_deleted_objects` filter to search for deleted items or item

variations, whereas ‘SearchCatalogObjects` does.

  • The both endpoints use different call conventions, including the query filter formats.

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:



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/square/catalog/client.rb', line 310

def search_items(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/catalog/search-catalog-items",
    body: Square::Catalog::Types::SearchCatalogItemsRequest.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::SearchCatalogItemsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#update_item_modifier_lists(request_options: {}, **params) ⇒ Square::Types::UpdateItemModifierListsResponse

Updates the [CatalogModifierList](entity:CatalogModifierList) objects that apply to the targeted [CatalogItem](entity:CatalogItem) without having to perform an upsert on the entire item.

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:



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

def update_item_modifier_lists(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/catalog/update-item-modifier-lists",
    body: Square::Catalog::Types::UpdateItemModifierListsRequest.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::UpdateItemModifierListsResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#update_item_taxes(request_options: {}, **params) ⇒ Square::Types::UpdateItemTaxesResponse

Updates the [CatalogTax](entity:CatalogTax) objects that apply to the targeted [CatalogItem](entity:CatalogItem) without having to perform an upsert on the entire item.

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:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# File 'lib/square/catalog/client.rb', line 382

def update_item_taxes(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/catalog/update-item-taxes",
    body: Square::Catalog::Types::UpdateItemTaxesRequest.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::UpdateItemTaxesResponse.load(response.body)
  else
    error_class = Square::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end