Cashier

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
cashier_user_idstring · required
counter_idstring · required
currencystring · required
opened_atstring (date-time) · required
closed_atstring (date-time) · optional
opening_float_minorinteger (int64) · required
total_cash_collected_minorinteger (int64) · required
total_pos_card_minorinteger (int64) · required
physical_cash_counted_minorinteger (int64) · optional
cash_variance_minorinteger (int64) · optional
statusstring · required

one of open, closed, reconciled

supervisor_user_idstring · optional
reconciled_atstring (date-time) · optional
notesstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "cashier_user_id": "cas_2lLSOpTOoH9i2pBYWFnyGRHEoT7",
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "currency": "MZN",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z",
  "opening_float_minor": 1,
  "total_cash_collected_minor": 125000,
  "total_pos_card_minor": 125000,
  "physical_cash_counted_minor": 1,
  "cash_variance_minor": 1,
  "status": "open",
  "supervisor_user_id": "sup_2Ss1vcYf3QW1jQEDvEChTaUlN6A",
  "reconciled_at": "2026-11-19T09:30:00Z",
  "notes": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List cashier shifts

Logs

GET /cashier/shifts

Returns a paginated list of cashier shifts in the tenant, filterable by cashier_user_id, counter_id and status (open, closed or reconciled). Each shift carries its opening float, cash collected, counted cash and variance once closed, and the supervisor who reconciled it. Requires cashier:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions cashier:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Open a shift for the authenticated cashier and counter

Logs

POST /cashier/shifts/open

Opens a shift for the calling user at the given counter with an opening cash float, in the tenant currency, and returns it with 201. counter_id is required and opening_float_minor must not be negative; only one open shift per cashier and counter is allowed, so a second one returns 409. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe; a reused key with a different request is rejected. A cashier.shift.opened event is emitted. Requires cashier:write.

Parameters

Idempotency-Keystring · header · optional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Body application/json

counter_idstring · optional
opening_float_minorinteger · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions cashier:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/open" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "opening_float_minor": 1
}'
Response 200

Success

Count the drawer and close the shift

Logs

POST /cashier/shifts/close

Count the drawer and close the shift; variance = counted - (float + cash)

Closes a shift by recording the physical cash counted in the drawer; the variance is computed as counted minus (opening float + cash collected). Without shift_id the caller's own open shift is closed. A shift that is not open returns 409, and no open shift returns 404. Send an Idempotency-Key header (1 to 255 visible ASCII characters) so a retry returns the stored result instead of failing; a cashier.shift.closed event is emitted. Requires cashier:write.

Parameters

Idempotency-Keystring · header · optional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Body application/json

shift_idstring · optional
physical_cash_counted_minorinteger · optional
notesstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions cashier:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/close" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "shift_id": "shi_2YyDVSEZlsg7D4aHDGavnEgbPcU",
  "physical_cash_counted_minor": 1,
  "notes": "Leitura confirmada no local."
}'
Response 200

Success

The caller's open shift

Logs

GET /cashier/shifts/current

Returns the calling user's open shift, optionally at one counter given by counter_id. When the caller has no open shift the response is 200 with a null body, not 404, so a till application can decide whether to prompt for opening a shift. Requires cashier:read.

Returns

200 The caller's open shift, or null when no shift is open

Show attributes
idstring · required
tenant_idstring · required
cashier_user_idstring · required
counter_idstring · required
currencystring · required
opened_atstring (date-time) · required
closed_atstring (date-time) · optional
opening_float_minorinteger (int64) · required
total_cash_collected_minorinteger (int64) · required
total_pos_card_minorinteger (int64) · required
physical_cash_counted_minorinteger (int64) · optional
cash_variance_minorinteger (int64) · optional
statusstring · required

one of open, closed, reconciled

supervisor_user_idstring · optional
reconciled_atstring (date-time) · optional
notesstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 403

Permissions cashier:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts/current" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "idx_2xBW8Tr0oR5YsrNoIdzQO7t4Gjn",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "cashier_user_id": "cas_2lLSOpTOoH9i2pBYWFnyGRHEoT7",
  "counter_id": "cou_2uw1pq0Jt8ANJccnPIcJ9Ae7RIk",
  "currency": "MZN",
  "opened_at": "2026-11-19T09:30:00Z",
  "closed_at": "2026-11-19T09:30:00Z",
  "opening_float_minor": 1,
  "total_cash_collected_minor": 125000,
  "total_pos_card_minor": 125000,
  "physical_cash_counted_minor": 1,
  "cash_variance_minor": 1,
  "status": "open",
  "supervisor_user_id": "sup_2Ss1vcYf3QW1jQEDvEChTaUlN6A",
  "reconciled_at": "2026-11-19T09:30:00Z",
  "notes": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a shift

Logs

GET /cashier/shifts/{id}

Returns one cashier shift with its counter, cashier, opening float, cash collected, counted cash, variance, notes and its open, close and reconcile timestamps. Returns 404 when the shift is not in this tenant. Requires cashier:read.

Parameters

idstring · path · required

Id of the cashier shift (prefix shf).

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions cashier:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/cashier/shifts/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Success

Supervisor sign-off of a closed shift

Logs

POST /cashier/shifts/{id}/reconcile

Supervisor sign-off of a closed shift: sets its status to reconciled, records the caller as supervisor with a timestamp, and appends any notes to the shift notes. Only a closed shift can be reconciled; any other status returns 409. Supports an Idempotency-Key header for safe retries. Requires the cashier:supervise permission.

Parameters

idstring · path · required

Id of the closed cashier shift to reconcile (prefix shf).

Idempotency-Keystring · header · optional

Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.

Body application/json

notesstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions cashier:supervise · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/cashier/shifts/{id}/reconcile" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Leitura confirmada no local."
}'
Response 200

Success