Batch retrieve orders

POST

/v2/orders/batch-retrieve

Retrieves a set of orders by their IDs.

If a given order ID does not exist, the ID is ignored instead of generating an error.

Permissions:ORDERS_READ

Guide

Retrieve orders

Try in API Explorer

Link to section

Request body

Example code

Link to section

location_id

string

The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID.

Link to section

order_ids

string [ ]

Required

The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.

Link to section

Response fields

Link to section

orders

The requested orders. This will omit any requested orders that do not exist.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/orders/batch-retrieve

curl https://connect.squareup.com/v2/orders/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2025-06-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "057P5VYJ4A5X1",
    "order_ids": [
      "CAISEM82RcpmcFBM0TfOyiHV3es",
      "CAISENgvlJ6jLWAzERDzjyHVybY"
    ]
  }'

Response JSON

{
  "orders": [
    {
      "id": "CAISEM82RcpmcFBM0TfOyiHV3es",
      "location_id": "057P5VYJ4A5X1",
      "reference_id": "my-order-001",
      "line_items": [
        {
          "uid": "945986d1-9586-11e6-ad5a-28cfe92138cf",
          "name": "Awesome product",
          "quantity": "1",
          "base_price_money": {
            "amount": 1599,
            "currency": "USD"
          },
          "total_money": {
            "amount": 1599,
            "currency": "USD"
          }
        },
        {
          "uid": "a8f4168c-9586-11e6-bdf0-28cfe92138cf",
          "name": "Another awesome product",
          "quantity": "3",
          "base_price_money": {
            "amount": 2000,
            "currency": "USD"
          },
          "total_money": {
            "amount": 6000,
            "currency": "USD"
          }
        }
      ],
      "total_money": {
        "amount": 7599,
        "currency": "USD"
      }
    }
  ]
}