Cash Drawer Shifts API

Use the Cash Drawer Shifts API

Get Cash Drawer Shift data to create bookkeeping reports for cash drawer activity on a Square Point of Sale device paired with a cash drawer.

The Square Cash Drawer Shifts API is a reporting API for businesses that use a cash drawer with their Square Point of Sale terminals. The API allows you to get filtered and paged lists of cash drawer shifts and their related shift events for a given location. It replaces the deprecated Connect v1 Cash Drawer Shifts API.

This guide explains how to complete the following essential Cash Drawer Shifts API tasks:

  • Get a paged list of cash drawer shift summaries

  • Retrieve a single cash drawer shift

  • Get a paged list of CashDrawerShiftEvent entries on a cash drawer shift by location and shift.

Before you call the API
Permalink Get a link to this section

To use the Cash Drawers Shifts API, you need the following:

  • You have a valid Square Account. To create a Square account in minutes, visit squareup.com/signup.

  • You have cash management turned on in Square Point of Sale and have created and opened a cash drawer in a Square Point of Sale tablet application.

  • You have an access token and location ID to get cash drawer shifts and events. Read Create and Authorize a Sandbox Test Account to learn about getting sandbox access tokens.

Note: You should do your testing and development of the Cash Drawer Shifts API in production if you need to test against production data. The API has only read-only operations so you cannot update any production data with it.

If you are using OAuth tokens, add the CASH_DRAWER_READ permission.

To learn more about how to code the OAuth flow in Sandbox and production, read Build with OAuth API.

Get a personal access token
Permalink Get a link to this section

  1. Open the Developer Dashboard and select an application. The Credentials page for the selected app is shown.

  2. Set the dashboard mode to Production Settings for a production environment access token or Sandbox Settings for a sandbox environment access token.

  3. Copy the Access Token in the Credentials section of the page.


Store the copied personal access token in a secure location. Any developer can use that token in their own app to get full API access to your Square account.

Did you know?

For more secure access to your Square account, use an OAuth token. The OAuth flow enforces security in 2 ways:

  • Challenges a user to identify themselves before granting access to a Square account.

  • Limits the scope of access to a Square account and only after the authenticated user authorizes access.

Get your location ID
Permalink Get a link to this section

All employee cash drawer shifts processed with the Cash Drawer Shifts API must be associated with a valid location ID for the associated Square account. Use the Locations API to find your location ID:

To see a cURL example showing how to get a specific location, read the Retrieve a specific location code example. To get started quickly:

  1. Go to the Locations setting page of your Square Application.

  2. Copy the ID of the location you want to use.

Alternatively, you can call the ListLocations operation with the following cURL command:

curl https://connect.squareup.com/v2/locations          \
  -H 'Authorization: Bearer ACCESS_TOKEN'

In the list of locations that is returned, select the id that corresponds to the location you want cash drawers from.

List Cash Drawer Shifts
Permalink Get a link to this section

In order to get information on what cash drawer shifts are opened at a location, issue a GET request to /v2/cash-drawers/shifts. You have the following options for query parameters.

Query Parameters
Permalink Get a link to this section

NameTypeDescription
sort_order SortOrderThe order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC
begin_timestringThe inclusive start time of the query on opened_at, in ISO 8601 format. Example: 2019-11-01T00:00:00-08:00
end_timestringThe exclusive end date of the query on opened_at, in ISO 8601 format. Example: 2019-11-30T00:00:00-08:00
limitintegerMaximum size of a page of results
cursorstringCursor for fetching the next page
location_idstringThe ID of the location to list cash drawer shifts for.

Command Line
Permalink Get a link to this section

Use the following cURL command to get cash drawers for a given time period.

curl -X GET \
'https://connect.squareup.com/v2/cash-drawers/shifts?begin_time=2019-11-01T00:00:00-08:00&end_time=2019-11-30T00:00:00-08:00&location_id={{YOUR_LOCATION_TOKEN}}&limit=100&sort_order=ASC' \
  -H 'Accept-Encoding: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response carries an array of CashDrawerShiftSummary

{
    "item": [
        {
            "id": "DCC99978-09A6-4926-849F-300BE9C5793A",
            "state": "CLOSED",
            "opened_at": "2019-11-22T00:42:54.000Z",
            "ended_at": "2019-11-22T00:44:49.000Z",
            "closed_at": "2019-11-22T00:44:49.000Z",
            "description": "We lost a lot of cash",
            "opened_cash_money": {
                "amount": 10000,
                "currency": "USD"
            },
            "expected_cash_money": {
                "amount": 10000,
                "currency": "USD"
            },
            "closed_cash_money": {
                "amount": 100,
                "currency": "USD"
            }
        }
    ]
}

Retrieve a Cash Drawer Shift
Permalink Get a link to this section

Once you get a cash drawer shift and you want more information on it, you can retrieve more details by using a GET request to /v2/cash-drawers/shifts/{{SHIFT_ID}}. You have the following options for query parameters.

NameTypeDescription
location_idstringThe ID of the location to list cash drawer shifts for
shift_idstringThe shift’s ID
curl -X GET \
  'https://connect.squareup.com/v2/cash-drawers/shifts/DCC99978-09A6-4926-849F-300BE9C5793A?location_id={{YOUR_LOCATION_ID}}' \
  -H 'Accept-Encoding: application/json' \
  -H 'Authorization: Bearer {{BEARER_TOKEN}}' 

The response carries a CashDrawerShift

{
    "cash_drawer_shift": {
        "id": "DCC99978-09A6-4926-849F-300BE9C5793A",
        "state": "CLOSED",
        "opened_at": "2019-11-22T00:42:54.000Z",
        "ended_at": "2019-11-22T00:44:49.000Z",
        "closed_at": "2019-11-22T00:44:49.000Z",
        "opening_employee_id": "",
        "ending_employee_id": "",
        "closing_employee_id": "",
        "description": "We lost a lot of cash",
        "opened_cash_money": {
            "amount": 10000,
            "currency": "USD"
        },
        "cash_payment_money": {
            "amount": 100,
            "currency": "USD"
        },
        "cash_refunds_money": {
            "amount": -100,
            "currency": "USD"
        },
        "cash_paid_in_money": {
            "amount": 10000,
            "currency": "USD"
        },
        "cash_paid_out_money": {
            "amount": -10000,
            "currency": "USD"
        },
        "expected_cash_money": {
            "amount": 10000,
            "currency": "USD"
        },
        "closed_cash_money": {
            "amount": 100,
            "currency": "USD"
        },
        "device": {
            "name": "My iPad"
        }
    }
}

List Cash Drawer Shift Events
Permalink Get a link to this section

In order to get the events on a cash drawer shift, you will issue a GET request to /v2/cash-drawers/shifts/{{SHIFT_ID}}/events. You have the following options for query parameters.

Query Parameters
Permalink Get a link to this section

NameTypeDescription
limitintegerNumber of resources in a page (200 by default, 1000 max)
cursorstringOpaque cursor for fetching the next page
location_idstringThe ID of the location to list cash drawer shifts for
shift_idstringThe shift’s ID

Command Line
Permalink Get a link to this section

Use the following cURL command to get cash drawers for a given time period.

curl -X GET \ 'https://connect.squareup.com/v2/cash-drawers/shifts/DCC99978-09A6-4926-849F-300BE9C5793A/events?location_id={{YOUR_LOCATION_ID}}' \
  -H 'Accept-Encoding: application/json' \
  -H 'Authorization: Bearer {{BEARER_TOKEN}}' 

The response carries an array of CashDrawerShiftEvent

{
    "events": [
        {
            "id": "9F07DB01-D85A-4B77-88C3-D5C64CEB5155",
            "event_type": "CASH_TENDER_PAYMENT",
            "event_money": {
                "amount": 100,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:43:02.000Z",
            "description": ""
        },
        {
            "id": "B2854CEA-A781-49B3-8F31-C64558231F48",
            "event_type": "CASH_TENDER_PAYMENT",
            "event_money": {
                "amount": 250,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:43:12.000Z",
            "description": ""
        },
        {
            "id": "B5FB7F72-95CD-44A3-974D-26C41064D042",
            "event_type": "CASH_TENDER_CANCELLED_PAYMENT",
            "event_money": {
                "amount": 250,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:43:23.000Z",
            "description": ""
        },
        {
            "id": "0B425480-8504-40B4-A867-37B23543931B",
            "event_type": "CASH_TENDER_REFUND",
            "event_money": {
                "amount": 100,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:43:46.000Z",
            "description": ""
        },
        {
            "id": "8C66E60E-FDCF-4EEF-A98D-3B14B7ED5CBE",
            "event_type": "PAID_IN",
            "event_money": {
                "amount": 10000,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:44:18.000Z",
            "description": "Transfer from another drawer"
        },
        {
            "id": "D5ACA7FE-C64D-4ADA-8BC8-82118A2DAE4F",
            "event_type": "PAID_OUT",
            "event_money": {
                "amount": 10000,
                "currency": "USD"
            },
            "created_at": "2019-11-22T00:44:29.000Z",
            "description": "Transfer out to another drawer"
        }
    ]
}