SquareConnect::CatalogApi

June 12, 2019 · View on GitHub

All URIs are relative to https://connect.squareup.com

Method	HTTP request	Description
batch_delete_catalog_objects	POST /v2/catalog/batch-delete	BatchDeleteCatalogObjects
batch_retrieve_catalog_objects	POST /v2/catalog/batch-retrieve	BatchRetrieveCatalogObjects
batch_upsert_catalog_objects	POST /v2/catalog/batch-upsert	BatchUpsertCatalogObjects
catalog_info	GET /v2/catalog/info	CatalogInfo
delete_catalog_object	DELETE /v2/catalog/object/{object_id}	DeleteCatalogObject
list_catalog	GET /v2/catalog/list	ListCatalog
retrieve_catalog_object	GET /v2/catalog/object/{object_id}	RetrieveCatalogObject
search_catalog_objects	POST /v2/catalog/search	SearchCatalogObjects
update_item_modifier_lists	POST /v2/catalog/update-item-modifier-lists	UpdateItemModifierLists
update_item_taxes	POST /v2/catalog/update-item-taxes	UpdateItemTaxes
upsert_catalog_object	POST /v2/catalog/object	UpsertCatalogObject

batch_delete_catalog_objects

BatchDeleteCatalogObjectsResponse batch_delete_catalog_objects(body)

BatchDeleteCatalogObjects

Deletes a set of CatalogItems 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 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.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::BatchDeleteCatalogObjectsRequest.new # BatchDeleteCatalogObjectsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #BatchDeleteCatalogObjects
  result = api_instance.batch_delete_catalog_objects(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->batch_delete_catalog_objects: #{e}"
end

Parameters

Name	Type	Description	Notes
body	BatchDeleteCatalogObjectsRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

BatchDeleteCatalogObjectsResponse

Authorization

oauth2

HTTP request headers

Content-Type: application/json
Accept: application/json

batch_retrieve_catalog_objects

BatchRetrieveCatalogObjectsResponse batch_retrieve_catalog_objects(body)

BatchRetrieveCatalogObjects

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

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::BatchRetrieveCatalogObjectsRequest.new # BatchRetrieveCatalogObjectsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #BatchRetrieveCatalogObjects
  result = api_instance.batch_retrieve_catalog_objects(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->batch_retrieve_catalog_objects: #{e}"
end

Parameters

Name	Type	Description	Notes
body	BatchRetrieveCatalogObjectsRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

BatchRetrieveCatalogObjectsResponse

Authorization

oauth2

HTTP request headers

Content-Type: application/json
Accept: application/json

batch_upsert_catalog_objects

BatchUpsertCatalogObjectsResponse batch_upsert_catalog_objects(body)

BatchUpsertCatalogObjects

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.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::BatchUpsertCatalogObjectsRequest.new # BatchUpsertCatalogObjectsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #BatchUpsertCatalogObjects
  result = api_instance.batch_upsert_catalog_objects(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->batch_upsert_catalog_objects: #{e}"
end

Parameters

Name	Type	Description	Notes
body	BatchUpsertCatalogObjectsRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Return type

BatchUpsertCatalogObjectsResponse

Authorization

oauth2

HTTP request headers

Content-Type: application/json
Accept: application/json

catalog_info

CatalogInfoResponse catalog_info

CatalogInfo

Returns information about the Square Catalog API, such as batch size limits for BatchUpsertCatalogObjects.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

begin
  #CatalogInfo
  result = api_instance.catalog_info
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->catalog_info: #{e}"
end

Parameters

This endpoint does not need any parameter.

Return type

CatalogInfoResponse

Authorization

oauth2

HTTP request headers

Content-Type: application/json
Accept: application/json

delete_catalog_object

DeleteCatalogObjectResponse delete_catalog_object(object_id)

DeleteCatalogObject

Deletes a single CatalogObject based on the provided ID and returns the 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 children.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

object_id = "object_id_example" # String | The ID of the [CatalogObject](#type-catalogobject) to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a [CatalogItem](#type-catalogitem) will delete its [CatalogItemVariation](#type-catalogitemvariation)s).


begin
  #DeleteCatalogObject
  result = api_instance.delete_catalog_object(object_id)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->delete_catalog_object: #{e}"
end

Parameters

Name	Type	Description	Notes
object_id	String	The ID of the CatalogObject to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariations).

Return type

DeleteCatalogObjectResponse

Authorization

oauth2

HTTP request headers

Content-Type: application/json
Accept: application/json

list_catalog

ListCatalogResponse list_catalog(opts)

ListCatalog

Returns a list of CatalogObjects that includes all objects of a set of desired types (for example, all CatalogItem and CatalogTax objects) in the catalog. The types parameter is specified as a comma-separated list of valid CatalogObject types: ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY, DISCOUNT, TAX. Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use SearchCatalogObjects and set include_deleted_objects to true.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

opts = { 
  cursor: "cursor_example", # String | The pagination cursor returned in the previous response. Leave unset for an initial request. See [Pagination](/basics/api101/pagination) for more information.
  types: "types_example" # String | An optional case-insensitive, comma-separated list of object types to retrieve, for example `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`.  The legal values are taken from the [CatalogObjectType](#type-catalogobjecttype) enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.
}

begin
  #ListCatalog
  result = api_instance.list_catalog(opts)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->list_catalog: #{e}"
end

Parameters

Name	Type	Description	Notes
cursor	String	The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.	[optional]
types	String	An optional case-insensitive, comma-separated list of object types to retrieve, for example `ITEM,ITEM_VARIATION,CATEGORY,IMAGE`. The legal values are taken from the CatalogObjectType enumeration, namely `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`, `MODIFIER`, `MODIFIER_LIST`, or `IMAGE`.	[optional]

Content-Type: application/json
Accept: application/json

retrieve_catalog_object

RetrieveCatalogObjectResponse retrieve_catalog_object(object_id, opts)

RetrieveCatalogObject

Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

object_id = "object_id_example" # String | The object ID of any type of [CatalogObject](#type-catalogobject)s to be retrieved.

opts = { 
  include_related_objects: true # BOOLEAN | If `true`, the response will include additional objects that are related to the requested object, as follows:  If the `object` field of the response contains a [CatalogItem](#type-catalogitem), its associated [CatalogCategory](#type-catalogcategory), [CatalogTax](#type-catalogtax)es, [CatalogImage](#type-catalogimage)s and [CatalogModifierList](#type-catalogmodifierlist)s will be returned in the `related_objects` field of the response. If the `object` field of the response contains a [CatalogItemVariation](#type-catalogitemvariation), its parent [CatalogItem](#type-catalogitem) will be returned in the `related_objects` field of  the response.  Default value: `false`
}

begin
  #RetrieveCatalogObject
  result = api_instance.retrieve_catalog_object(object_id, opts)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->retrieve_catalog_object: #{e}"
end

Parameters

Name	Type	Description	Notes
object_id	String	The object ID of any type of CatalogObjects to be retrieved.
include_related_objects	BOOLEAN	If `true`, the response will include additional objects that are related to the requested object, as follows: If the `object` field of the response contains a CatalogItem, its associated CatalogCategory, CatalogTaxes, CatalogImages and CatalogModifierLists will be returned in the `related_objects` field of the response. If the `object` field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the `related_objects` field of the response. Default value: `false`	[optional]

Content-Type: application/json
Accept: application/json

search_catalog_objects

SearchCatalogObjectsResponse search_catalog_objects(body)

SearchCatalogObjects

Queries the targeted catalog using a variety of query types: CatalogQuerySortedAttribute, CatalogQueryExact, CatalogQueryRange, CatalogQueryText, CatalogQueryItemsForTax, and CatalogQueryItemsForModifierList.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::SearchCatalogObjectsRequest.new # SearchCatalogObjectsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #SearchCatalogObjects
  result = api_instance.search_catalog_objects(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->search_catalog_objects: #{e}"
end

Parameters

Name	Type	Description	Notes
body	SearchCatalogObjectsRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Content-Type: application/json
Accept: application/json

update_item_modifier_lists

UpdateItemModifierListsResponse update_item_modifier_lists(body)

UpdateItemModifierLists

Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::UpdateItemModifierListsRequest.new # UpdateItemModifierListsRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #UpdateItemModifierLists
  result = api_instance.update_item_modifier_lists(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->update_item_modifier_lists: #{e}"
end

Parameters

Name	Type	Description	Notes
body	UpdateItemModifierListsRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Content-Type: application/json
Accept: application/json

update_item_taxes

UpdateItemTaxesResponse update_item_taxes(body)

UpdateItemTaxes

Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::UpdateItemTaxesRequest.new # UpdateItemTaxesRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #UpdateItemTaxes
  result = api_instance.update_item_taxes(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->update_item_taxes: #{e}"
end

Parameters

Name	Type	Description	Notes
body	UpdateItemTaxesRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Content-Type: application/json
Accept: application/json

upsert_catalog_object

UpsertCatalogObjectResponse upsert_catalog_object(body)

UpsertCatalogObject

Creates or updates the target CatalogObject.

Example

# load the gem
require 'square_connect'
# setup authorization
SquareConnect.configure do |config|
  # Configure OAuth2 access token for authorization: oauth2
  config.access_token = 'YOUR ACCESS TOKEN'
end

api_instance = SquareConnect::CatalogApi.new

body = SquareConnect::UpsertCatalogObjectRequest.new # UpsertCatalogObjectRequest | An object containing the fields to POST for the request.  See the corresponding object definition for field details.


begin
  #UpsertCatalogObject
  result = api_instance.upsert_catalog_object(body)
  p result
rescue SquareConnect::ApiError => e
  puts "Exception when calling CatalogApi->upsert_catalog_object: #{e}"
end

Parameters

Name	Type	Description	Notes
body	UpsertCatalogObjectRequest	An object containing the fields to POST for the request. See the corresponding object definition for field details.

Content-Type: application/json
Accept: application/json