Gratuity

The Gratuity workspace manages tips and service charges from collection through employee distribution and settlement. It uses a source-and-allocation ledger: collected value is never silently overwritten, and every batch preserves the policy, eligibility, and allocation snapshot used at the time it was created.

Use it to distribute gratuities directly to employees or export them into an HR payroll run.

Before You Start

1. Configure a branch, eligible employees, attendance records, and an active earning-type payroll component.
2. Create an active Gratuity Policy for each branch and collection type you distribute.
3. Ensure gratuity collection sources exist. Tips and service-charge collections are recorded automatically from supported POS, invoice, and cash-movement workflows.
4. Enable gratuity writes in the application configuration. When writes are disabled, users may review data but cannot create, change, approve, cancel, or reverse policies and batches.

Workspace Areas

• Overview — shows collected, allocated, unsettled, and distributed gratuity value for the selected branch and period.
• Batches — creates and controls employee distribution batches.
• Collections — the read-only ledger of Tip and Service Charge source amounts.
• Policies — effective-dated distribution rules.

Gratuity Policies

A policy determines how a branch distributes one collection type over an effective date range. Only one active policy for the same branch and collection type may apply to a given date; overlapping active policies are rejected.

Field	Description
Branch	Branch the policy governs. It cannot be changed after creation.
Collection Type	Tip or Service Charge.
Distribution Method	Equal Share or Weighted Points.
Recipient Routing	Hybrid, Pool, or Direct.
Payroll Component	Active earning component used for payroll-export batches.
Effective From / To	Dates when the policy may be used. End date is optional.
Designation Weights	Optional points by designation for Weighted Points distributions.
Allow Manual Override	Allows a manually entered allocation, provided a reason is supplied.
Active	Determines whether the policy is available for new batches.

Distribution and Recipient Rules

Option	Behavior
Equal Share	Divides pooled value equally among eligible employees.
Weighted Points	Divides pooled value using designation points multiplied by worked minutes.
Direct	Requires a recipient on every selected collection; no pooling occurs.
Pool	Pools all selected collection value, including sources with a direct recipient.
Hybrid	Sends sources with a direct recipient to that employee and pools the remaining value.

Collections and Employee Eligibility

Collections are immutable source records. Each has a branch, currency, collection type, economic date, source reference, available balance, and, where applicable, a direct recipient employee.

When creating a batch, select sources from the eligible-sources list. A source must be available, match the selected branch, collection type, currency, and period, and cannot already be fully allocated or reserved in another active batch.

Eligible employees are active employees in the branch with qualifying attendance during the batch period. If no employees are selected, the system uses employees with worked time in the period. An employee with no qualifying work time needs a documented manual override to be included.

Create and Preview a Batch

1. Open Human Resources → Gratuity and select Create Batch.
2. Select the branch, collection type, policy, date range, distribution method, and recipient routing.
3. Choose one or more eligible collection sources.
4. Review or select eligible employees.
5. Choose the settlement destination:
   • Direct Payout — choose Cash, Card, Bank Transfer, or Mobile Wallet. For a cash payout, an open POS session may be selected.
   • Payroll Export — select a Draft payroll run and active earning payroll component.
6. If permitted by the policy, enter manual allocations that total exactly the available source value and provide a manual-override reason.
7. Enter the economic date and optional note, then use Preview to review server-calculated allocations.
8. Save the batch as Draft.

The preview does not reserve sources. Saving creates a Draft and freezes the selected policy, employee eligibility, source set, amounts, currency rate, and allocations.

Batch Lifecycle

Draft → Posted       (Direct Payout)
Draft → Approved     (Payroll Export)
Draft / Approved → Cancelled
Posted / Approved → Reversed

Status	Meaning
Draft	Editable. Sources and allocations are reserved, but no payout or payroll input has been created.
Posted	Direct payout was approved and completed. Allocations are marked paid.
Approved	Payroll-export batch was approved and its amounts were added to the selected Draft payroll run as inputs.
Cancelled	Draft, or an eligible Payroll Export batch, was cancelled and source value was released.
Reversed	A Posted Direct Payout or eligible Approved Payroll Export batch was reversed with a linked counter-entry.

Approve, Cancel, and Reverse

Approve

Approval revalidates the draft against current source balances and eligibility.

• For Direct Payout, it posts the payout. When a POS session is selected, it creates the corresponding tip-out cash movement. Allocations become Paid and the batch becomes Posted.
• For Payroll Export, it adds one payroll-run input per employee for the selected earning component. Allocations become Payroll Exported and the batch becomes Approved.

Approval uses an idempotency key supplied by the application to prevent accidental duplicate processing.

Cancel

Draft batches can be cancelled with a required reason, releasing their source allocations. A Payroll Export batch can also be cancelled only while its payroll run remains Draft; the related payroll inputs are removed. Direct payouts cannot be cancelled after posting.

Reverse

Use Reverse for a controlled correction of a Posted Direct Payout or an Approved Payroll Export batch. Provide an economic date, idempotency key, and required reason.

• A direct payout tied to a POS session can be reversed only while that session is still open; the matching tip-out is reversed.
• A payroll-export batch can be reversed only while the target payroll run is still Draft; the related payroll inputs are removed.

The original and its reversal remain in the audit trail, while source amounts are released for reprocessing.

Controls and Best Practices

• Review the Overview and Collections before creating a batch; do not distribute unverified source value.
• Use Hybrid routing when only some tips belong to named employees and the remainder should be pooled.
• Choose Weighted Points only after designation weights have been reviewed for the branch.
• Use manual overrides sparingly and always record the reason.
• Approve Direct Payout batches only after the actual payout method and, for cash, POS session are confirmed.
• Export to payroll only while the target payroll run is Draft. Complete the normal payroll workflow after the gratuity inputs are added.
• Correct settled batches through Reverse, never by editing or deleting historical allocations.