Retrieve Orders

Applies to: Orders API | Catalog API | Payments API

Learn how to retrieve orders, catalog attributes, and payments made on an order.

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).

A RetrieveOrder request retrieves a single order. Provide the ID of the order you want to get. The endpoint returns that order regardless of the business location where the order was created.

A BatchRetrieveOrders request retrieves a set of orders. In the request, provide a list of order IDs regardless of seller locations. If you need to limit the response to the orders in that list to a single location, add a location ID. This scopes the returned orders from the global list to those that were opened at the specified location.

BatchRetrieveOrders is useful when you've retrieved a set of Payment objects and want to get the associated order for each payment. You add the Payment.order_id for each payment to the list of order IDs in the BatchRetrieveOrders request.

Let's say you're building a transaction report with section breaks by seller location. You might load all the payment order IDs into a BatchRetrieveOrders request and call the endpoint once for each location, putting that location's ID in the request. With each call, you get back only the orders for the location's report section.

In the following example, the request asks for eight orders and limits the response to a single location:

The response returns only those orders from location X9XWRESTK1CZ1. In this case, 1iFbiC2iFbilandL4PLS7sMF and 2bORnot2bodmQCXwftwJftMF are returned.

The details about what is being purchased in an order are contained in order line items. If a line item refers to a catalog item variation, the item isn't ad hoc and exists in the seller's item library (catalog). The catalog has more information about the item than is stored in the order. For example, the item's availability, description, SKU, or category can be retrieved from the catalog with one or two API calls. Developers creating a sales activity report usually need to retrieve these attributes.

The order stores the line_items[].catalog_object_id and catalog_version of the item variation. Use the object ID to retrieve item variation properties by calling RetrieveCatalogObject on the Catalog API.

For example, you want to get the sku and category_name properties of a line item. These are properties of CatalogObject subtypes:

• sku is an optional property of CatalogItemVariation.
• category_name is the name property of CatalogCategory. You can retrieve the CatalogCategory from the CatalogItem.reporting_category.

You can access these Catalog objects using the RetrieveCatalogObject endpoint with the following steps:

1. Make sure you have the catalog_object_id and catalog_version of the line item from your Order object.

2. Call RetrieveCatalogObject by providing:

   • catalog_object_id as the object_id path parameter value.
   • catalog_version as the query parameter value. If the catalog_version isn't specified, the current version is assumed.
   • include_related_objects with a true value so that the parent CatalogItem is returned with the item variation.
   Request

   Response

   Retrieve catalog object

   cURL

3. Call RetrieveCatalogObject by providing:

   • reporting_category.id as the object_id path parameter value (a category is also a Catalog object). Therefore, you specify the category ID as the ID of the Catalog object to retrieve.
   • catalog_version as the query parameter value.
   Request

   Response

   This example gets a category at the specified version:

   Retrieve catalog object

   cURL

When an order is paid, an order.tenders[] list is populated with Tender objects that provide details about all payments on the order. They refer to Payment objects that record the actual payments. Normally, there's only one item in an order.tenders[], but in the case of a split payment on an order, there's a tender for each split payment.

The following example shows the tenders property in an order with a single payment of $1.19, which is captured with a credit card. The details of the capture are recorded in a Payment object whose ID is DXjUoKXdD1WPl19Gq52e3BQr4cMZY.

{
   "tenders": [
    {
      "id": "DXjUoKXdD1WPl19Gq52e3BQr4cMZY",
      "location_id": "[LOCATION_ID]",
      "transaction_id": "hITuEXBNk3ipAknWv2jdEl2IUl6YY",
      "created_at": "2022-10-03T21:46:58Z",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "processing_fee_money": {
        "amount": 19,
        "currency": "USD"
      },
      "type": "CARD",
      "card_details": {
        "status": "CAPTURED",
        "card": {
          "card_brand": "MASTERCARD",
          "last_4": "6952",
          "fingerprint": "sq-1-HVU...BE8Gkh_EtOTe0A"
        },
        "entry_method": "KEYED"
      },
      "payment_id": "DXjUoKXdD1WPl19Gq52e3BQr4cMZY"
    }
   ]
}

To get the payment, call GetPayment using the payment_id value from the tender object.

Among the properties of a Payment object, you can find relevant payment information, such as the following:

• Payment card details - For example, the time when the payment was authorized and then captured. If delayed capture is enabled for the payment, you can see the gap between authorization and capture. For a food and beverage business, this lets you know whether a server is closing tickets in a timely manner.
• TeamMember - The person who took the payment. This is usually the team member who was using the hardware that read the buyer's payment card to create the payment.
• Card reader details - The device_details about the hardware (such as Square Terminal, Square Register, or a seller's mobile device) that read the payment card and created the payment.
• Application details - Lets you know whether your application took the payment. The application ID in this sub-object should be compared with the application ID for the application you created in the Developer Console.
• Customer - The payment.customer_id value is used to retrieve details about the buyer who paid for the order. This is usually the same person.

• Create Orders
• Pay for Orders