Cashbox session

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.

POST /cashbox-session/open

Open a cashier shift (cashbox session) on a cashbox with a declared opening balance. The acting cashier is resolved from the integration token (the optional user_id header, else the tenant owner).

Request body

Field	Type	Required	Description
organization_id	string	Yes	Organization ObjectId the session belongs to
cashbox_id	string	Yes	Cashbox (till) ObjectId to open a shift on
opened_balance	object[]	Yes	Opening balance per payment method
opened_balance[].currency_id	string	Yes	Currency ObjectId
opened_balance[].payment_method_id	string	Yes	Payment-method ObjectId
opened_balance[].expected	number	Yes	Declared expected amount for this payment method
opened_at	string (date-time)	No	Optional shift open time (ISO 8601); defaults to now
open_note	string	No	Optional free-text note

{
  "organization_id": "string",
  "cashbox_id": "string",
  "opened_balance": [
    {
      "currency_id": "string",
      "payment_method_id": "string",
      "expected": 0
    }
  ],
  "opened_at": "2025-05-01T12:00:00Z",
  "open_note": "string"
}

Response

Field	Type	Description
_id	string
session_uuid	string
state	string	One of: open, closed, resolved, flagged
organization_id	string
cashbox_id	string
user_id	string
opened_at	string (date-time)
closed_at	string (date-time)
opened_balance	object[]
opened_balance[].currency_id	string
opened_balance[].payment_method_id	string
opened_balance[].expected	number
opened_balance[].actual	number
closed_balance	object[]
closed_balance[].currency_id	string
closed_balance[].payment_method_id	string
closed_balance[].expected	number
closed_balance[].actual	number
has_diff_on_open	boolean
has_diff_on_close	boolean
open_note	string
close_note	string

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "session_uuid": "string",
    "state": "open",
    "organization_id": "string",
    "cashbox_id": "string",
    "user_id": "string",
    "opened_at": "2025-05-01T12:00:00Z",
    "closed_at": "2025-05-01T12:00:00Z",
    "opened_balance": [
      {
        "currency_id": "string",
        "payment_method_id": "string",
        "expected": 0,
        "actual": 0
      }
    ],
    "closed_balance": [
      {
        "currency_id": "string",
        "payment_method_id": "string",
        "expected": 0,
        "actual": 0
      }
    ],
    "has_diff_on_open": false,
    "has_diff_on_close": false,
    "open_note": "string",
    "close_note": "string"
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /cashbox-session/close

Close an open shift, reconciling the declared closing balance against the expected totals.

Request body

Field	Type	Required	Description
_id	string	Yes	Cashbox-session ObjectId to close
closed_balance	object[]	Yes	Counted closing balance per payment method
closed_balance[].currency_id	string	Yes	Currency ObjectId
closed_balance[].payment_method_id	string	Yes	Payment-method ObjectId
closed_balance[].expected	number	Yes	Declared expected amount for this payment method
close_note	string	No	Optional free-text note

{
  "_id": "string",
  "closed_balance": [
    {
      "currency_id": "string",
      "payment_method_id": "string",
      "expected": 0
    }
  ],
  "close_note": "string"
}

Response

Same response shape as POST /cashbox-session/open.

POST /cashbox-session/get-paging

Paginated list of cashbox sessions, filterable by organization, cashbox, cashier, state, and discrepancy.

Request body

Field	Type	Required	Description
page	number	Yes	Default: 1
limit	number	Yes	Default: 20
organization_id	string	No	Filter by organization ObjectId
cashbox_id	string	No	Filter by cashbox ObjectId
user_id	string	No	Filter by cashier (user) ObjectId
state	string	No	Filter by session state. One of: open, closed, resolved, flagged
has_diff	boolean	No	Filter sessions that closed with a discrepancy

{
  "page": 1,
  "limit": 20,
  "organization_id": "string",
  "cashbox_id": "string",
  "user_id": "string",
  "state": "open",
  "has_diff": false
}

Response

Field	Type	Description
total	number
list	object[]
list[]._id	string
list[].session_uuid	string
list[].state	string	One of: open, closed, resolved, flagged
list[].organization_id	string
list[].cashbox_id	string
list[].user_id	string
list[].opened_at	string (date-time)
list[].closed_at	string (date-time)
list[].opened_balance	object[]
list[].opened_balance[].currency_id	string
list[].opened_balance[].payment_method_id	string
list[].opened_balance[].expected	number
list[].opened_balance[].actual	number
list[].closed_balance	object[]
list[].closed_balance[].currency_id	string
list[].closed_balance[].payment_method_id	string
list[].closed_balance[].expected	number
list[].closed_balance[].actual	number
list[].has_diff_on_open	boolean
list[].has_diff_on_close	boolean
list[].open_note	string
list[].close_note	string

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": [
      {
        "_id": "string",
        "session_uuid": "string",
        "state": "open",
        "organization_id": "string",
        "cashbox_id": "string",
        "user_id": "string",
        "opened_at": "2025-05-01T12:00:00Z",
        "closed_at": "2025-05-01T12:00:00Z",
        "opened_balance": [],
        "closed_balance": [],
        "has_diff_on_open": false,
        "has_diff_on_close": false,
        "open_note": "string",
        "close_note": "string"
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

GET /cashbox-session/get-by-id/{id}

Fetch a single cashbox session by ObjectId.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Cashbox-session ObjectId

Request body

No request body.

Response

Same response shape as POST /cashbox-session/open.

POST /cashbox-session/get-active

Return the caller's active (open) session in the given organization, if any.

Request body

Field	Type	Required	Description
organization_id	string	Yes	Organization ObjectId to find the caller's active session in

{
  "organization_id": "string"
}

Response

Same response shape as POST /cashbox-session/open.

---

This page is generated from the OpenAPI spec.