Learn how to use the RetrieveOrder
and BatchRetrieveOrders
endpoints to retrieve one or more orders. For an order line item that is a catalog item, you learn how to use the Catalog API to access additional catalog attributes.
You can retrieve a single order or a set of orders using their IDs and the following endpoints. These endpoints return orders regardless of how or when they entered the Square ecosystem (Square Point of Sale, Invoices, or the Orders API).
Use the
RetrieveOrder
endpoint to retrieve an order. You only provide an order ID in the request. The endpoint returns the order regardless of the business location where the order was created.Retrieve order
Use the
BatchRetrieveOrders
endpoint to retrieve a set of orders (within the scope of the current authorization's merchant ID). In the request, you provide a list of order IDs and an optional business location ID.- Location ID is specified - The endpoint returns only the orders in the specified list that are associated with the location.
- Location ID isn't specified - The endpoint returns all orders specified in the list.
Batch retrieve orders
When you create an order, a line item in the order can be a catalog item or an ad hoc item (see Create line items). For a catalog item, the resulting Order
object stores the catalog_object_id
and catalog_version
of the item. You can use this information to access other catalog attributes using the Catalog API (RetrieveCatalogObject endpoint).
For illustration, sku
and category_name
information of the line item are retrieved. These attributes are part of CatalogObject as follows:
sku
is now part of aCatalogObject
of theITEM_VARIATION
type.category_name
now appears as thename
field of theCatalogObject
of theCATEGORY
type.
You can access these CatalogObjects using the RetrieveCatalogObject endpoint (Catalog API) using the following steps:
Make sure you have the
catalog_object_id
andcatalog_version
of the line item from yourOrder
object.Call RetrieveCatalogObject by providing:
catalog_object_id
as theobject_id
path parameter value.catalog_version
as the query parameter value. If thecatalog_version
isn't specified, the latest version is assumed.
Retrieve catalog object
In response, you get a
Catalog
object of theITEM
type. The following is an example response. Theitem_variation_data
provides thesku
.{ "object": { "type": "ITEM", "id": "WWCAXYB6EEA5WT4PYXREV262", ... "item_data": { "name": "Hamburger", "category_id": "WBV5YL4R3DCHXVDFDQ22KPVU", "variations": [ { "type": "ITEM_VARIATION", "id": "RA43EL3Z3JWI52PCD4DPCV7B", ... "item_variation_data": { "item_id": "WWCAXYB6EEA5WT4PYXREV262", "name": "Regular", "sku": "burgerSKU1", "price_money": { "amount": 500, "currency": "USD" }, } } ], ... } } }Note that the
Catalog
object in the response also provides thecategory_id
of the object. You can use it to access the category name of the line item in the next RetrieveCatalogObject call.Call RetrieveCatalogObject by providing:
category_id
as theobject_id
path parameter value (a category is also aCatalog
object). Therefore, you specify the category ID as the ID of theCatalog
object to retrieve.catalog_version
as the query parameter value.
An example is shown:
Retrieve catalog object
In response, you get a
Catalog
object of theCATEGORY
type. The following is an example response. Thecategory_data
provides thename
of the category of your line item in the order.{ "object": { "type": "CATEGORY", "id": "WBV5YL4R3DCHXVDFDQ22KPVU", "updated_at": "2021-07-12T19:02:57.355Z", "version": 1626116577355, "is_deleted": false, "present_at_all_locations": true, "category_data": { "name": "Burgers" } } }