Cash Drawer Shifts API

Learn about the Cash Drawer Shifts API and how to report on cash drawer activity by seller and location.

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.

The Square Cash Drawer Shifts API is a reporting API for businesses that use a cash drawer with their Square Point of Sale terminals. You can use the API to get filtered and paged lists of cash drawer shift data for a given location.

The operations described in this topic can be used to:

Get a filtered and paged list of cash drawer shift summaries.
Retrieve details about a specific cash drawer shift.
Get a paged list of events 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:

A Square account and an application. If you don't have a Square account, see Get Started to learn how to create an account and an application.
The Cash Management feature enabled in Square Point of Sale and a cash drawer that was created and opened in a Square Point of Sale tablet application. For more information, see Cash Drawer Management.
An access token and location ID. All calls to Square APIs require an access token. All calls to the Cash Drawer Shifts API additionally require a valid location ID for the associated Square account.
When testing with your own Square account, you can get your personal access token from the Developer Console:
1. Sign in to the Developer Console and open an application.
2. At the top of the Credentials page, choose Production to get your production access token or Sandbox to get your Sandbox access token.
3. In the Production Access token or Sandbox Access token box, choose Show and then copy the access token.
  Store the access token in a secure location. The token provides full API access to your Square account.
Link to section
Using OAuth access tokens
Your application should use OAuth access tokens when working with resources in a seller's account. 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.
The CASH_DRAWER_READ permission is required to call the Cash Drawer Shifts API. To learn more about the OAuth flow in the Sandbox and production, see Test Authorization with a Web Server.
When testing with your own Square account, you can get a location ID from the Developer Console:
1. In the Developer Console, open the Locations page for your application.
2. Copy the ID of the location you want to use.
Alternatively, your application can get a location ID using the Locations API:
- To retrieve all locations for a seller, call ListLocations:
  List locations
  In the list of returned locations, select the ID that corresponds to the location that has the cash drawer shifts or events you want to retrieve.
- To get the ID of the seller's main location, call RetrieveLocation using the main keyword:
  Retrieve location

Link to section

List cash drawer shifts

To get summary information about the cash drawer shifts opened at a location, call ListCashDrawerShifts and provide the location ID. The following example gets cash drawer shifts for a specific time period:

List cash drawer shifts

ListCashDrawerShifts supports the following optional 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 number of results to return in a single paged response. The default is 200 and the maximum is 1000.
`cursor`	`string`	The cursor returned in the paged response from the previous request. Provide this cursor to retrieve the next page of results.

Note

For more information about paging through response data using the limit and cursor parameters, see Pagination.

The response returns an array of CashDrawerShiftSummary objects, as shown in the following example:

{
    "cash_drawer_shifts": [
        {
            "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

To retrieve detailed information about a cash drawer shift, call RetrieveCashDrawerShift and provide the shift ID and location ID:

Retrieve cash drawer shift

The response returns a CashDrawerShift object, as shown in the following example:

{
    "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, call ListCashDrawerShiftEvents and provide the shift ID and the location ID. The following example gets cash drawer shift events for a specific time period:

List cash drawer shift events

ListCashDrawerShiftEvents supports the following optional query parameters:

Name	Type	Description
`limit`	`integer`	The maximum number of results to return in a single paged response. The default is 200 and the maximum is 1000.
`cursor`	`string`	The cursor returned in the paged response from the previous request. Provide this cursor to retrieve the next page of results.

Note

For more information about paging through response data using the limit and cursor parameters, see Pagination.

The response returns an array of CashDrawerShiftEvent objects, as shown in the following example:

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

Docs

Cash Drawer Shifts API

On this page

Overview

Before you call the API

Get your personal access token

Using OAuth access tokens

Get your location ID

List cash drawer shifts

Note

Retrieve a cash drawer shift

List cash drawer shift events

Note

On this page