> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centsless.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and distribute tip pools

> Aggregate tips across multiple transactions into a pool, then distribute them using equal, weighted, or hours-based methods. All pool operations are recorded in the audit trail.

Tip pools let you collect tips from multiple transactions and distribute them among a group of eligible employees at the end of a shift or period. Centsless supports three distribution methods: equal split, weighted by contribution, and proportional to hours worked. All pool operations are recorded in the audit trail.

## Authentication

All requests require an `x-api-key` header.

***

## POST /tip/pool/create — Create a tip pool

Create a new tip pool from a set of recorded tips and define how the total will be distributed among participants.

```
POST https://api.centsless.org/api/v1/tip/pool/create
```

### Request body

<ParamField body="pool_name" type="string" required>
  A name for this tip pool. Example: `Sunday Lunch Pool`
</ParamField>

<ParamField body="tip_ids" type="array" required>
  An array of tip IDs to include in the pool.

  ```json theme={null}
  ["TIP-00123", "TIP-00124", "TIP-00125"]
  ```
</ParamField>

<ParamField body="distribution_method" type="string" required>
  How the pooled total will be split among participants. One of: `equal`, `weighted`, `hours_based`
</ParamField>

<ParamField body="participants" type="array" required>
  An array of employees eligible to receive a share. Each entry requires `employeeId` and `employeeName`.

  ```json theme={null}
  [
    { "employeeId": "EMP-001", "employeeName": "Jordan Smith" },
    { "employeeId": "EMP-002", "employeeName": "Alex Rivera" }
  ]
  ```
</ParamField>

### Code example

```bash theme={null}
curl -X POST https://api.centsless.org/api/v1/tip/pool/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_name": "Sunday Lunch Pool",
    "tip_ids": ["TIP-00123", "TIP-00124", "TIP-00125"],
    "distribution_method": "equal",
    "participants": [
      { "employeeId": "EMP-001", "employeeName": "Jordan Smith" },
      { "employeeId": "EMP-002", "employeeName": "Alex Rivera" }
    ]
  }'
```

***

## POST /tip/pool/distribute — Distribute a tip pool

Trigger distribution of a previously created tip pool. The engine calculates each participant's share using the distribution method defined at pool creation and records individual payouts in the audit trail.

```
POST https://api.centsless.org/api/v1/tip/pool/distribute
```

### Request body

<ParamField body="pool_id" type="string" required>
  The ID of the tip pool to distribute. Returned when the pool was created.
</ParamField>

### Code example

```bash theme={null}
curl -X POST https://api.centsless.org/api/v1/tip/pool/distribute \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_id": "POOL-00042"
  }'
```

The response includes each participant's calculated share and the total distributed. Any fractional cents are rounded in the employees' favor (FLSA ceiling rounding).