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

• 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

  cURL

• 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

  cURL

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 a CatalogObject of the ITEM_VARIATION type.
• category_name now appears as the name field of the CatalogObject of the CATEGORY type.

You can access these CatalogObjects using the RetrieveCatalogObject endpoint (Catalog API) using 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 latest version is assumed.

   Retrieve catalog object

   cURL

   In response, you get a Catalog object of the ITEM type. The following is an example response. The item_variation_data provides the sku.

   {
     "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 the category_id of the object. You can use it to access the category name of the line item in the next RetrieveCatalogObject call.

3. Call RetrieveCatalogObject by providing:

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

   An example is shown:

   Retrieve catalog object

   cURL

   In response, you get a Catalog object of the CATEGORY type. The following is an example response. The category_data provides the name 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"
       }
     }
   }

When an order is paid, an order.tenders list is populated with a Tender object that provides details about the payment and refers to the Payment object that records the actual payment.

The following example shows the tenders field in an order with a single payment of $1.19. It was captured with a credit card. The details of the capture are recorded in a Payment 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-HVUClygOr_JBE8Gkh_EtOTe0A"
        },
        "entry_method": "KEYED"
      },
      "payment_id": "DXjUoKXdD1WPl19Gq52e3BQr4cMZY"
    }
   ]
}

To get the payment, call the GetPayment endpoint 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 - 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.

The response carries the Payment object. In the following example, the payment was taken on a Square Point of Sale that the seller named "Counter Terminal 1".

{
  "payment": {
    "id": "DXjUoKXdD1WPl19Gq52e3BQr4cMZY",
    "created_at": "2022-10-03T21:46:58.409Z",
    "updated_at": "2022-10-03T21:47:01.912Z",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "MASTERCARD",
        "last_4": "6952",
        "exp_month": 12,
        "exp_year": 2028,
        "fingerprint": "sq-1-HVUCWbGnS2LZgjiLMYlhxCSvr7KlbFqvVM_HHh8zyMolulygOr_JBE8Gkh_EtOTe0A",
        "card_type": "CREDIT",
        "bin": "512081"
      },
      "entry_method": "KEYED",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "DkpIUm",
      "statement_description": "SQ *MY BUSINESS GOSQ.COM",
      "card_payment_timeline": {
        "authorized_at": "2022-10-03T21:46:58.557Z",
        "captured_at": "2022-10-03T21:46:59.662Z"
      }
    },
    "location_id": "90A9W5RRYD2GQ",
    "order_id": "hITuEXBNk3ipAknWv2jdEl2IUl6YY",
    "processing_fee": [
      {
        "effective_at": "2022-10-03T23:47:00.000Z",
        "type": "INITIAL",
        "amount_money": {
          "amount": 19,
          "currency": "USD"
        }
      }
    ],
    "customer_id": "KW9QGDM6YS7G5BREP6DSVNPFWC",
    "total_money": {
      "amount": 100,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 100,
      "currency": "USD"
    },
    "employee_id": "bxrMsKrMAMzWgYGGo8BL",
    "receipt_number": "DXjU",
    "receipt_url": "https://squareup.com/receipt/preview/DXjUcMZY",
    "delay_action": "CANCEL",
    "delayed_until": "2022-10-10T21:46:58.409Z",
    "team_member_id": "bxrMsKrMAMzWgYGGo8BL",
    "device_details": {
      "device_name": "Counter Terminal 1",
      "device_installation_id": "sq0ids-Pw67AZAlLVB7hsRmwlJPuA",
      "device_id": "6F217C17C2P-11G5-4662-A63A-7B025E372447"
    },    
    "application_details": {
      "square_product": "SQUARE_POS",
      "application_id": "sq0ids-Pw67AZAlLVB7hsRmwlJPuA"
    },
    "version_token": "qWeotSPKuw0jhqJlUV8Gt9ODv4zMzG1v8DkmwFhnI2G6o"
  }
}

• Create Orders
• Pay for Orders