Class: Square::Catalog::Client

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

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Square::Catalog::Client 



7
8
9
 
# File 'lib/square/catalog/client.rb', line 7

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.

Returns:



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/square/catalog/client.rb', line 27

def batch_delete(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/batch-delete",
    body: params
  )
  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.

Returns:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/square/catalog/client.rb', line 56

def batch_get(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/batch-retrieve",
    body: params
  )
  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.

Returns:



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

def batch_upsert(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/batch-upsert",
    body: params
  )
  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) 


294
295
296
 
# File 'lib/square/catalog/client.rb', line 294

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.

Returns:



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/square/catalog/client.rb', line 117

def info(request_options: {}, **_params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "GET",
    path: "v2/catalog/info"
  )
  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`.

Returns:



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/square/catalog/client.rb', line 147

def list(request_options: {}, **params)
  _query_param_names = [
    %w[cursor types catalog_version],
    %i[cursor types catalog_version]
  ].flatten
  _query = params.slice(*_query_param_names)
  params.except(*_query_param_names)

  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "GET",
    path: "v2/catalog/list",
    query: _query
  )
  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

#object ⇒ Square::Object_::Client

Returns:

  • (Square::Object_::Client) 


299
300
301
 
# File 'lib/square/catalog/client.rb', line 299

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.

Returns:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/square/catalog/client.rb', line 187

def search(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/search",
    body: params
  )
  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.

Returns:



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/square/catalog/client.rb', line 220

def search_items(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/search-catalog-items",
    body: params
  )
  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.

Returns:



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

def update_item_modifier_lists(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/update-item-modifier-lists",
    body: params
  )
  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.

Returns:



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/square/catalog/client.rb', line 272

def update_item_taxes(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::PRODUCTION,
    method: "POST",
    path: "v2/catalog/update-item-taxes",
    body: params
  )
  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