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.
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 Dashboard:
Sign in to the Developer Dashboard and open an application.
At the top of the Credentials page, choose Production to get your production access token or Sandbox to get your Sandbox access token.
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.
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_READpermission is required to call the Cash Drawer Shifts API. To learn more about the OAuth flow in the Sandbox and production, see OAuth Walkthrough: Test Authorization with a Web Server.When testing with your own Square account, you can get a location ID from the Developer Dashboard:
- In the Developer Dashboard, open the Locations page for your application.
- 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
mainkeyword:Retrieve location
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"
}
}
]
}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"
}
}
}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"
}
]
}