Applies to: Orders API
Learn how to retrieve orders, catalog attributes, and payments made on an order.
Learn how to use the RetrieveOrder
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
Retrieve order
A BatchRetrieveOrders
BatchRetrieveOrders
is useful when you've retrieved a set of PaymentPayment.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:
Batch retrieve orders
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.
Did you know?
If a seller is using inventory tracking, an inventory adjustment record is created each time a catalog item is sold. You can use that order.line_items[].catalog_object_id
when calling BatchRetrieveInventoryChangesSOLD
.
The order stores the line_items[].
catalog_object_id
For example, you want to get the sku
and category_name
properties of a line item. These are properties of CatalogObject
sku
is an optional property of CatalogItemVariationCatalogItemVariation .category_name
is thename
property of CatalogCategoryCatalogCategory . You can retrieve theCatalogCategory
from the CatalogItem.reporting_categoryCatalogItem.reporting_category .
You can access these Catalog
objects using the RetrieveCatalogObject
Make sure you have the
catalog_object_id
andcatalog_version
of the line item from yourOrder
object.Call RetrieveCatalogObject
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 current version is assumed.include_related_objects
with atrue
value so that the parentCatalogItem
is returned with the item variation.
Retrieve catalog object
Call RetrieveCatalogObject
RetrieveCatalogObject by providing:reporting_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.
This example gets a category at the specified version:
Retrieve catalog object
When an order is paid, an order.tenders[]
list is populated with Tenderorder.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 GetPaymentpayment_id
value from the tender
object.
Get payment
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
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.