Close a TPV service

In this article

Before you start

• The operator is signed in to Harbor Demo Group and Harbor Soho with effective `tpv:use` access for the location.
• An active `service_session` is loaded on the TPV floor, for example Soho lunch service.
• Every `ticket` in the service is already `paid`, `closed` or `void`.
• No `cash_register_session` with `status` `open` remains for that service, including cash registers opened on another terminal.
• If the business wants staff attribution, a staff member such as Olivia Hart is selected in the TPV before closing.

Instructions

1. 1.

   Open the TPV floor

   Go to the Harbor Soho TPV floor and confirm that the active service is visible. If no service is active, the close action is not available from this screen.

2. 2.

   Finish every ticket first

   Review the service tickets before closing. Any ticket that is still operationally pending must be paid, closed or voided before the service close can succeed.

3. 3.

   Close all cash registers for the service

   Close every cash register session linked to the active service. The TPV blocks service closure while any linked cash register is still open, even when it belongs to another terminal.

4. 4.

   Use Close service from the actions menu

   Open the TPV header actions menu and select `Close service`. There is no confirmation modal, so this should only be pressed when the service is ready to end.

5. 5.

   Confirm the closed service

   After the success message, review the service from service session history or the calendar view. The TPV refreshes service data and clears the selected employee and ticket context.

Validations and limits

• Do not document `tpv:close-service` alone as sufficient for the UI path; the current TPV page access still requires `tpv:use`.
• The close request sends `POST /api/app/{orgId}/{locationId}/service-sessions/{sessionId}/close` with `closed_by_staff_id` only when a staff member is selected.
• The backend close route accepts only `POST` and `PUT`, and it requires a decodable JSON body even when `closed_by_staff_id` is omitted.
• The service must belong to the active `locationId`; missing location context, an empty session id or a session from another location is treated as not found.
• Ticket status validation is enforced by the backend: every ticket must be exactly `paid`, `closed` or `void`.
• The backend rejects the close while any `cash_register_session` is still open for the same `service_session`.
• `closed_by_staff_id` is trimmed and copied when present, but the backend does not validate that it exists as a `staff` record.
• A successful close sets the `service_session` status to `closed`, records `closed_at` in UTC and logs `service_session_closed`; it does not close tickets or cash registers automatically.

Expected result

The active TPV service is closed and available in service session history or calendar views with its recalculated detail. The operator sees the success state and can continue from a clean TPV context.