Cash Drawer Shifts API

Cash Drawer Shifts API Overview

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.

Before you call the API
List cash drawer shifts
Retrieve a cash drawer shift
List cash drawer shift events

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 for a cash drawer shift by location and shift.

Link to section
Before you call the API

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. To learn about getting Sandbox access tokens, see Square Sandbox.

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 only has read-only operations so you cannot update any production data with it.

If you are using OAuth tokens, add CASH_DRAWER_READ permission.

To learn more about how to code the OAuth flow in the Sandbox and production, see OAuth Walkthrough: Test Authorization with a Web Server.

Link to section
Get a personal access token

Open the Developer Dashboard and select an application. The Credentials page for the selected application appears.
Set the dashboard mode to Production for a production environment access token or Sandbox for a Sandbox environment access token.
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 application to get full API access to your Square account.

For more secure access to your Square account, use an OAuth token. The OAuth flow enforces security in two 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.

Link to section
Get your location ID

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, see the Retrieve a specific location code example. To get started quickly:

Go to the Locations page of your Square application in the Developer Dashboard.
Copy the ID of the location you want to use.

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

List Locations

curl https://connect.squareupsandbox.com/v2/locations \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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

Link to section
List cash drawer shifts

To get information about 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.

Link to section
Query parameters

Name	Type	Description
`sort_order`	SortOrder	The order in which cash drawer shifts are listed in the response, based on their `opened_at` field. The default value is ASC.
`begin_time`	`string`	The inclusive start time of the query on `opened_at`, in ISO 8601 format. For example, 2019-11-01T00:00:00-08:00.
`end_time`.	`string`	The exclusive end date of the query on `opened_at`, in ISO 8601 format. For example, 2019-11-30T00:00:00-08:00.
`limit`	`integer`	The maximum size of a page of results.
`cursor`	`string`	The cursor for fetching the next page.
`location_id`	`string`	The ID of the location to list cash drawer shifts for.

Link to section
Command line

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

List Cash Drawer Shifts

curl https://connect.squareupsandbox.com/v2/cash-drawers/shifts?begin_time=2019-11-01T00%3A00%3A00-08%3A00&end_time=2019-11-30T00%3A00%3A00-08%3A00&location_id=YOUR_LOCATION_TOKEN&limit=100&sort_order=ASC \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following response carries an array of CashDrawerShiftSummary:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
    "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"
            }
        }
    ]
}

Link to section
Retrieve a cash drawer shift

When you get a cash drawer shift and want more information about 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:

Name	Type	Description
`location_id`	`string`	The ID of the location to list cash drawer shifts for.
`shift_id`	`string`	The shift’s ID.

Retrieve Cash Drawer Shift

curl https://connect.squareupsandbox.com/v2/cash-drawers/shifts/CC99978-09A6-4926-849F-300BE9C5793A?location_id=YOUR_LOCATION_ID \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following response carries a CashDrawerShift:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
    "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",
        "employee_ids": [
            "YWHZ5NXEWheVH6iRie7B"
        ],
        "opening_employee_id": "YWHZ5NXEWheVH6iRie7B",
        "ending_employee_id": "YWHZ5NXEWheVH6iRie7B",
        "closing_employee_id": "YWHZ5NXEWheVH6iRie7B",
        "description": "Cash drawer came up short",
        "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": 9000,
            "currency": "USD"
        },
        "device": {
            "name": "My iPad"
        }
    }
}

Link to section
List cash drawer shift events

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

Link to section
Query parameters

Name	Type	Description
`limit`	`integer`	The number of resources on a page (with 200 being the default and 1000 being the maximum.)
`cursor`	`string`	The opaque cursor for fetching the next page.
`location_id`	`string`	The ID of the location to list cash drawer shifts for.
`shift_id`	`string`	The shift’s ID.

Link to section
Command line

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

List Cash Drawer Shift Events

curl https://connect.squareupsandbox.com/v2/cash-drawers/shifts/DCC99978-09A6-4926-849F-300BE9C5793A/events?location_id=YOUR_LOCATION_ID \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following response carries an array of CashDrawerShiftEvent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

{
    "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"
        }
    ]
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Cash Drawer Shifts API Overview

On this page

Link to section
Before you call the API

Note

Link to section
Get a personal access token

Did you know?

Link to section
Get your location ID

Link to section
List cash drawer shifts

Link to section
Query parameters

Link to section
Command line

Link to section
Retrieve a cash drawer shift

Link to section
List cash drawer shift events

Link to section
Query parameters

Link to section
Command line

On this page

Docs

Cash Drawer Shifts API Overview

On this page

Link to section Before you call the API

Note

Link to section Get a personal access token

Did you know?

Link to section Get your location ID

Link to section List cash drawer shifts

Link to section Query parameters

Link to section Command line

Link to section Retrieve a cash drawer shift

Link to section List cash drawer shift events

Link to section Query parameters

Link to section Command line

On this page

Link to section
Before you call the API

Link to section
Get a personal access token

Link to section
Get your location ID

Link to section
List cash drawer shifts

Link to section
Query parameters

Link to section
Command line

Link to section
Retrieve a cash drawer shift

Link to section
List cash drawer shift events

Link to section
Query parameters

Link to section
Command line