Applies to: Catalog API | Orders API
Learn how to use the Catalog API to get specific Square catalog objects by their IDs and versions.
In the lifecycle of a catalog, a catalog object version represents a snapshot of the object at a particular time. The current version of any catalog object is available through the Catalog API. Earlier object versions are also available when your application uses the Orders API.
When a seller creates an Order and includes a catalog item variation, Square saves the version number of that variation at the time the order is created. If you later retrieve the order, you can view the item variations as they were when the order was created.
Did you know?
Order discounts, service charges, and taxes are also Catalog based and can be retrieved by the ID and version number stored in an Order.
If you have the ID of an object, RetrieveCatalogObject lets you return the specified Catalog object. If the object has multiple versions (that is, they're created or updated at different times), you can specify an Order.line_items[].catalog_version value to get the catalog item variation in its state at the time the order was created.
To get a catalog object by ID and version, an object with that ID and version must exist. If that combination of values doesn't exist, an error is returned.
The following example retrieves a catalog object by ID and version:
Retrieve catalog object
An Order that references catalog objects has a snapshot of those catalog objects at the time the order is created. If a seller updates their catalog items frequently, older orders are likely to reference the previous versions of those catalog items.
To retrieve catalog objects from an Order, such as in Order.taxes, use the Order.taxes[].catalog_object_id and Order.taxes[].catalog_version values in your request. This returns the catalog tax object at that version, which might not be the current version. To get the current version, omit the catalog_version value in your next retrieve request.
"taxes": [
{
"uid": "266ecbe5-51e1-4109-8c02-f6ae9a30c020",
"catalog_object_id": "VS7Z2Z3ABXCDB7DUB57BA4W2",
"catalog_version": 1715632004035,
"name": "10PCTax",
"percentage": "10.0",
"type": "ADDITIVE",
"applied_money": {
"amount": 30,
"currency": "USD"
},
"scope": "LINE_ITEM",
"auto_applied": true
}
]If you have multiple object IDs, BatchRetrieveCatalogObjects lets you return the specified objects in a single call. If the objects have multiple versions, you can specify a version to filter the results.
For example, if you request multiple catalog objects and specify version 1598467546497, only the objects that match that version or older versions are returned. For example, if one object is at version 1598467546497 and another is at version 2198467546497, only the object at version 1598467546497 is returned.
The following cURL request shows how to retrieve two items at the catalog version of 1598467546497:
Batch retrieve catalog objects
In a Square catalog, an object references other objects by their IDs. To retrieve the referenced objects with their properties, set the include_related_objects query parameter to true when calling RetrieveCatalogObject or its batch variant.
For example, a CatalogPricingRule object can reference a CatalogDiscount, CatalogProductSet, CatalogTax, and others. When calling RetrieveCatalogObject, specifying the ID of a pricing rule object and using defaults for all other input options, you get a compact result as follows:
{
"object": {
"type": "PRICING_RULE",
"id": "DYOXHWTDIGV75BPSRY7E7FOD",
"updated_at": "2021-04-23T04:36:33.649Z",
"version": 1619152593649,
"is_deleted": false,
"present_at_all_locations": true,
"pricing_rule_data": {
"discount_id": "E3GXIY42XBSI7LRLFF42DYTS",
"match_products_id": "FQAZS2FAPQKOXK5OUW3B7FXU",
"exclude_products_id": "F4W3VBGEMPEPSI6Z27E5MT3F",
"exclude_strategy": "MOST_EXPENSIVE",
"application_mode": "AUTOMATIC",
"discount_target_scope": "LINE_ITEM"
}
}
}The following example shows include_related_objects being explicitly set to true:
Retrieve catalog object
When a call to the ListCatalog endpoint is expected to return a large set of objects, you might need to use pagination to retrieve the results page by page.
Did you know?
When you call CreateOrder with a line item that includes a catalog variation ID and catalog_version, the order uses the catalog object values from that specified version, not the current version. For instance, it uses the item variation price from the specified version instead of the current price.
To retrieve a catalog object without its ID, use ListCatalog to get a paged list of all objects created up to the time of the call. If you have specific information about the catalog objects, use SearchCatalogObjects to filter and get a list based on that information.
The following cURL example returns all the objects of any version in a (small) catalog:
List catalog
By specifying a catalog version as an input to the ListCatalog endpoint, you can determine all changes made at a particular point of time throughout the history of the catalog.
To inspect what is added to or changed in the catalog, you can call ListCatalog with a specific catalog version as a query parameter to get only those objects of the specified version as well as those of earlier versions.
The following cURL example returns CatalogItem objects at the catalog version of 1598467546497:
List catalog