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
 
# 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::SANDBOX,
    method: "POST",
    path: "v2/catalog/batch-delete",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::BatchDeleteCatalogObjectsResponse.load(_response.body)
  end

  raise _response.body
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:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/square/catalog/client.rb', line 50

def batch_get(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/batch-retrieve",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::BatchGetCatalogObjectsResponse.load(_response.body)
  end

  raise _response.body
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:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/square/catalog/client.rb', line 80

def batch_upsert(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/batch-upsert",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::BatchUpsertCatalogObjectsResponse.load(_response.body)
  end

  raise _response.body
end

#images ⇒ Square::Images::Client

Returns:

  • (Square::Images::Client) 


237
238
239
 
# File 'lib/square/catalog/client.rb', line 237

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:



99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/square/catalog/client.rb', line 99

def info(request_options: {}, **_params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "GET",
    path: "v2/catalog/info"
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::CatalogInfoResponse.load(_response.body)
  end

  raise _response.body
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:



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

def list(request_options: {}, **params)
  _query_param_names = %w[cursor types catalog_version]
  _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::SANDBOX,
    method: "GET",
    path: "v2/catalog/list",
    query: _query
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::ListCatalogResponse.load(_response.body)
  end

  raise _response.body
end

#object ⇒ Square::Object_::Client

Returns:

  • (Square::Object_::Client) 


242
243
244
 
# File 'lib/square/catalog/client.rb', line 242

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:



154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/square/catalog/client.rb', line 154

def search(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/search",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::SearchCatalogObjectsResponse.load(_response.body)
  end

  raise _response.body
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:



181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/square/catalog/client.rb', line 181

def search_items(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/search-catalog-items",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::SearchCatalogItemsResponse.load(_response.body)
  end

  raise _response.body
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:



201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/square/catalog/client.rb', line 201

def update_item_modifier_lists(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/update-item-modifier-lists",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::UpdateItemModifierListsResponse.load(_response.body)
  end

  raise _response.body
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:



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

def update_item_taxes(request_options: {}, **params)
  _request = Square::Internal::JSON::Request.new(
    base_url: request_options[:base_url] || Square::Environment::SANDBOX,
    method: "POST",
    path: "v2/catalog/update-item-taxes",
    body: params
  )
  _response = @client.send(_request)
  if _response.code >= "200" && _response.code < "300"
    return Square::Types::UpdateItemTaxesResponse.load(_response.body)
  end

  raise _response.body
end