Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Tips API

Manage tips, configure tip pooling, handle distribution, and generate tip reports for payroll.

Authentication Required

All endpoints require a valid Bearer token. Tip pool and distribution endpoints require the tips:manage scope. See Authentication for details.

Overview

Attribute	Value
Base Path	`/api/v1/tips`
Authentication	Bearer Token
Required Roles	`staff`, `finance`, `restaurant_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Tip Collection

Record Tips

POST /api/v1/tips

Request Body

{
  "order_id": "ord_12345",
  "employee_id": "emp_001",
  "tips": [
    {
      "type": "credit_card",
      "amount": 12.50,
      "payment_id": "pay_abc123"
    },
    {
      "type": "cash",
      "amount": 5.00,
      "declared": true
    }
  ],
  "location_id": "loc_123",
  "shift_date": "2026-01-24"
}

Response

{
  "tip_id": "tip_001",
  "order_id": "ord_12345",
  "employee_id": "emp_001",
  "total_tips": 17.50,
  "breakdown": {
    "credit_card": 12.50,
    "cash": 5.00
  },
  "pool_contribution": {
    "amount": 3.50,
    "pool_id": "pool_001",
    "percentage": 20
  },
  "net_tips": 14.00,
  "recorded_at": "2026-01-24T19:30:00Z"
}

Get Tip Details

GET /api/v1/tips/{tip_id}

Response

{
  "tip_id": "tip_001",
  "order_id": "ord_12345",
  "employee_id": "emp_001",
  "employee_name": "Sarah Johnson",
  "location_id": "loc_123",
  "shift_date": "2026-01-24",
  "amounts": {
    "credit_card": 12.50,
    "cash": 5.00,
    "total": 17.50
  },
  "pool_contribution": {
    "pool_id": "pool_001",
    "pool_name": "FOH Pool",
    "amount": 3.50,
    "percentage": 20
  },
  "tipouts": [
    {
      "to_employee_id": "emp_010",
      "to_role": "busser",
      "amount": 0.88,
      "percentage": 5
    },
    {
      "to_employee_id": "emp_015",
      "to_role": "bartender",
      "amount": 1.75,
      "percentage": 10
    }
  ],
  "net_tips": 11.37,
  "status": "distributed",
  "recorded_at": "2026-01-24T19:30:00Z"
}

List Tips

GET /api/v1/tips

Query Parameters

Parameter	Type	Description
`employee_id`	uuid	Filter by employee
`location_id`	uuid	Filter by location
`shift_date`	date	Filter by date
`date_start`	date	Period start
`date_end`	date	Period end
`status`	string	`pending`, `distributed`, `paid`

Response

{
  "tips": [
    {
      "tip_id": "tip_001",
      "employee_id": "emp_001",
      "employee_name": "Sarah Johnson",
      "shift_date": "2026-01-24",
      "credit_card": 125.50,
      "cash": 85.00,
      "total": 210.50,
      "pool_contribution": 42.10,
      "tipouts_given": 26.31,
      "tipouts_received": 15.00,
      "net_tips": 157.09,
      "status": "distributed"
    }
  ],
  "summary": {
    "total_tips": 2450.00,
    "credit_card_total": 1650.00,
    "cash_total": 800.00
  }
}

Declare Cash Tips

POST /api/v1/tips/declare-cash

Request Body

{
  "employee_id": "emp_001",
  "shift_date": "2026-01-24",
  "amount": 85.00,
  "notes": "End of shift declaration"
}

Tip Pools

List Tip Pools

GET /api/v1/tips/pools

Response

{
  "pools": [
    {
      "id": "pool_001",
      "name": "FOH Tip Pool",
      "location_id": "loc_123",
      "status": "active",
      "contribution_rules": {
        "roles": ["server", "bartender"],
        "percentage": 20
      },
      "distribution_rules": {
        "method": "hours_worked",
        "eligible_roles": ["busser", "food_runner", "host"],
        "distribution_schedule": "daily"
      },
      "current_balance": 450.00,
      "participants": 8
    },
    {
      "id": "pool_002",
      "name": "Kitchen Tip Pool",
      "location_id": "loc_123",
      "status": "active",
      "contribution_rules": {
        "source": "service_charge",
        "percentage": 100
      },
      "distribution_rules": {
        "method": "equal",
        "eligible_roles": ["cook", "prep_cook", "dishwasher"]
      },
      "current_balance": 280.00,
      "participants": 5
    }
  ]
}

Create Tip Pool

POST /api/v1/tips/pools

Request Body

{
  "name": "FOH Tip Pool",
  "location_id": "loc_123",
  "contribution_rules": {
    "contributing_roles": ["server", "bartender"],
    "contribution_percentage": 20,
    "source": "credit_card_tips"
  },
  "distribution_rules": {
    "method": "points",
    "eligible_roles": [
      {"role": "busser", "points": 1.0},
      {"role": "food_runner", "points": 0.75},
      {"role": "host", "points": 0.5}
    ],
    "schedule": "end_of_shift"
  }
}

Get Tip Pool

GET /api/v1/tips/pools/{pool_id}

Response

{
  "id": "pool_001",
  "name": "FOH Tip Pool",
  "location_id": "loc_123",
  "status": "active",
  "contribution_rules": {
    "contributing_roles": ["server", "bartender"],
    "contribution_percentage": 20,
    "source": "credit_card_tips"
  },
  "distribution_rules": {
    "method": "points",
    "eligible_roles": [
      {"role": "busser", "points": 1.0},
      {"role": "food_runner", "points": 0.75},
      {"role": "host", "points": 0.5}
    ],
    "schedule": "end_of_shift"
  },
  "current_period": {
    "date": "2026-01-24",
    "total_contributed": 450.00,
    "contributors": 8,
    "recipients": 5
  },
  "created_at": "2025-01-01T00:00:00Z"
}

Update Tip Pool

PUT /api/v1/tips/pools/{pool_id}

Distribute Pool

POST /api/v1/tips/pools/{pool_id}/distribute

Request Body

{
  "shift_date": "2026-01-24",
  "override_distribution": null
}

Response

{
  "distribution_id": "dist_001",
  "pool_id": "pool_001",
  "shift_date": "2026-01-24",
  "total_distributed": 450.00,
  "recipients": [
    {
      "employee_id": "emp_010",
      "employee_name": "Mike Wilson",
      "role": "busser",
      "hours_worked": 6.0,
      "points": 6.0,
      "amount": 180.00
    },
    {
      "employee_id": "emp_011",
      "employee_name": "Lisa Chen",
      "role": "food_runner",
      "hours_worked": 5.0,
      "points": 3.75,
      "amount": 135.00
    },
    {
      "employee_id": "emp_012",
      "employee_name": "Tom Brown",
      "role": "host",
      "hours_worked": 6.0,
      "points": 3.0,
      "amount": 135.00
    }
  ],
  "distributed_at": "2026-01-25T02:00:00Z"
}

Tip Outs

Configure Tip Out Rules

POST /api/v1/tips/tipout-rules

Request Body

{
  "location_id": "loc_123",
  "from_role": "server",
  "rules": [
    {
      "to_role": "busser",
      "percentage": 5,
      "calculation_base": "net_sales"
    },
    {
      "to_role": "bartender",
      "percentage": 10,
      "calculation_base": "bar_sales"
    },
    {
      "to_role": "food_runner",
      "percentage": 3,
      "calculation_base": "food_sales"
    }
  ]
}

Get Tip Out Rules

GET /api/v1/tips/tipout-rules

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`from_role`	string	Filter by tipping role

Response

{
  "rules": [
    {
      "id": "rule_001",
      "location_id": "loc_123",
      "from_role": "server",
      "to_role": "busser",
      "percentage": 5,
      "calculation_base": "net_sales",
      "active": true
    },
    {
      "id": "rule_002",
      "location_id": "loc_123",
      "from_role": "server",
      "to_role": "bartender",
      "percentage": 10,
      "calculation_base": "bar_sales",
      "active": true
    }
  ]
}

Process Tip Outs

POST /api/v1/tips/tipouts/process

Request Body

{
  "location_id": "loc_123",
  "shift_date": "2026-01-24",
  "employees": ["emp_001", "emp_002", "emp_003"]
}

Response

{
  "process_id": "tipout_001",
  "shift_date": "2026-01-24",
  "tipouts": [
    {
      "from_employee": "emp_001",
      "from_name": "Sarah Johnson",
      "net_sales": 1250.00,
      "tipouts_given": [
        {"to": "emp_010", "to_name": "Mike Wilson", "role": "busser", "amount": 62.50},
        {"to": "emp_015", "to_name": "James Lee", "role": "bartender", "amount": 45.00}
      ],
      "total_tipout": 107.50
    }
  ],
  "summary": {
    "total_processed": 3,
    "total_tipout_amount": 322.50
  }
}

Reports

Get Tip Report

GET /api/v1/tips/reports

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`date_start`	date	Period start
`date_end`	date	Period end
`group_by`	string	`employee`, `role`, `day`
`format`	string	`summary`, `detailed`

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "location_id": "loc_123",
  "summary": {
    "total_tips": 45250.00,
    "credit_card_tips": 32500.00,
    "cash_tips": 12750.00,
    "pool_distributions": 8500.00,
    "tipouts": 4200.00
  },
  "by_employee": [
    {
      "employee_id": "emp_001",
      "name": "Sarah Johnson",
      "role": "server",
      "shifts_worked": 18,
      "hours_worked": 126.5,
      "credit_card_tips": 2450.00,
      "cash_tips": 850.00,
      "pool_received": 0,
      "pool_contributed": 660.00,
      "tipouts_given": 412.50,
      "tipouts_received": 0,
      "net_tips": 2227.50,
      "hourly_tip_rate": 17.61
    }
  ],
  "compliance": {
    "minimum_wage_status": "compliant",
    "tip_credit_applied": true,
    "all_cash_declared": true
  }
}

Export Tips for Payroll

POST /api/v1/tips/reports/export

Request Body

{
  "location_id": "loc_123",
  "pay_period_start": "2026-01-01",
  "pay_period_end": "2026-01-15",
  "format": "payroll",
  "include": ["credit_card", "cash_declared", "pool_distributions", "tipouts"]
}

Response

{
  "export_id": "export_001",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-15"
  },
  "employees": [
    {
      "employee_id": "emp_001",
      "employee_number": "EMP-2024-0042",
      "name": "Sarah Johnson",
      "ssn_last_four": "4567",
      "credit_card_tips": 1850.00,
      "cash_tips_declared": 650.00,
      "pool_distributions_received": 0,
      "tipouts_given": 312.50,
      "tipouts_received": 0,
      "total_tips": 2187.50,
      "hours_tipped": 72.5
    }
  ],
  "totals": {
    "credit_card_tips": 28500.00,
    "cash_tips_declared": 9850.00,
    "total_tips": 38350.00
  },
  "download_url": "https://..."
}

Compliance

Labor Law Compliance

Tip pool and distribution rules must comply with federal and state labor laws. The compliance endpoint validates that your configuration adheres to FLSA tip credit regulations, eligible role restrictions, and minimum wage requirements.

Get Compliance Status

GET /api/v1/tips/compliance

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`date`	date	Date to check

Response

{
  "location_id": "loc_123",
  "date": "2026-01-24",
  "status": "compliant",
  "checks": [
    {
      "rule": "tip_credit_minimum_wage",
      "status": "compliant",
      "details": "All tipped employees earned at least minimum wage with tip credit"
    },
    {
      "rule": "tip_pool_eligible_roles",
      "status": "compliant",
      "details": "Only eligible roles participate in tip pool"
    },
    {
      "rule": "cash_tips_declared",
      "status": "warning",
      "details": "2 employees have not declared cash tips for today",
      "affected_employees": ["emp_005", "emp_008"]
    },
    {
      "rule": "service_charge_disclosure",
      "status": "compliant",
      "details": "Service charges properly disclosed and distributed"
    }
  ],
  "recommendations": [
    "Remind employees emp_005 and emp_008 to declare cash tips before shift end"
  ]
}

Webhooks

Event	Description
`tips.recorded`	New tips recorded
`tips.pool_distributed`	Tip pool distributed
`tips.tipout_processed`	Tip outs processed
`tips.compliance_warning`	Compliance issue detected
`tips.cash_undeclared`	Cash tips not declared

Error Responses

Status	Code	Description
400	`invalid_amount`	Tip amount invalid
400	`pool_already_distributed`	Pool already distributed for date
404	`pool_not_found`	Tip pool not found
409	`tips_already_recorded`	Tips already recorded for order
422	`compliance_violation`	Would violate tip regulations

Employees API - Employee management
Payments API - Payment processing
Payroll Integration - Payroll export

Overview​

Tip Collection​

Record Tips​

Get Tip Details​

List Tips​

Declare Cash Tips​

Tip Pools​

List Tip Pools​

Create Tip Pool​

Get Tip Pool​

Update Tip Pool​

Distribute Pool​

Tip Outs​

Configure Tip Out Rules​

Get Tip Out Rules​

Process Tip Outs​

Reports​

Get Tip Report​

Export Tips for Payroll​

Compliance​

Get Compliance Status​

Webhooks​

Error Responses​

Related Documentation​

Overview

Tip Collection

Record Tips

Get Tip Details

List Tips

Declare Cash Tips

Tip Pools

List Tip Pools

Create Tip Pool

Get Tip Pool

Update Tip Pool

Distribute Pool

Tip Outs

Configure Tip Out Rules

Get Tip Out Rules

Process Tip Outs

Reports

Get Tip Report

Export Tips for Payroll

Compliance

Get Compliance Status

Webhooks

Error Responses

Related Documentation