Tips API: Creating and Querying Tip Transactions

The /tips endpoint is the core of the Aplauso platform. It creates and tracks tip transactions from any source - kiosk, mobile, API, or custom integration.

Create a Tip

POST /v2/tips
Content-Type: application/json
Authorization: Bearer <idToken>  (optional)

Minimum Request

{
  "employeeId": "abc123",
  "amount": 10.00,
  "environment": "live"
}

Full Request (all optional fields)

{
  "employeeId": "abc123",
  "amount": 25.50,
  "currency": "USD",
  "idempotencyKey": "order-8675309-tip",
  "paymentMethod": "card",
  "source": "api",
  "visitId": "visit789",
  "outletId": "outlet456",
  "guestName": "Jane Smith",
  "guestRoom": "501",
  "guestEmail": "jane@example.com",
  "message": "Great service!",
  "serviceType": "housekeeping",
  "tipPoolConfig": {
    "enabled": true,
    "distribution": [
      { "employeeId": "emp1", "percentage": 60 },
      { "employeeId": "emp2", "percentage": 40 }
    ]
  },
  "environment": "live"
}

Supported Payment Methods

card | cash | bank | roomcharge | digital_wallet

Supported Sources

web | kiosk | mobile | qr | api

Supported Service Types

general | dining | housekeeping | concierge | valet | spa | other

Response

{
  "success": true,
  "tipId": "tip_xxxxxxxxxxx",
  "disbursement": {
    "primaryEmployee": {
      "employeeId": "abc123",
      "amount": 21.25,
      "currency": "USD"
    },
    "tipPoolMembers": [],
    "commissionRecipients": [],
    "total": 21.25
  },
  "fees": {
    "paymentProcessing": 1.04,
    "fixedFee": 0.30,
    "total": 1.34
  }
}

Tip Status Codes

Tips move through a lifecycle:

For tips paid through the kiosk, the status moves from 5 to 20 automatically via the Stripe webhook (no API call needed from your integration).

Idempotency

Use idempotencyKey to prevent duplicate tips if a request is retried:

{
  "employeeId": "abc123",
  "amount": 10.00,
  "idempotencyKey": "my-system-order-1234-tip"
}

• Keys must be 8-256 alphanumeric characters (plus - and _).
• Repeating a request with the same key returns the original tipId without creating a duplicate.
• Keys are valid for 24 hours.

Update Tip Status

PATCH /v2/tips
Content-Type: application/json
Authorization: Bearer <idToken>

{
  "tipId": "tip_xxxxxxxxxxx",
  "status": 20,
  "paymentTransaction": {
    "transactionId": "pi_stripe_id",
    "amount": 25.50,
    "currency": "USD",
    "status": "succeeded",
    "processor": "stripe",
    "method": "card"
  },
  "createDividends": true
}

Setting status to 20 (Paid) with a valid paymentTransaction creates dividend records in the employee's wallet. createDividends defaults to true.

Query Tips

GET /v2/tips?employeeId=abc123&environment=live&limit=50

Query Parameters

Response

{
  "tips": [
    {
      "id": "tip_xxxxxxxxxxx",
      "tipId": "tip_xxxxxxxxxxx",
      "employeeId": "abc123",
      "amount": 25.50,
      "status": 20,
      "environment": "live",
      "paymentMethod": "card",
      "source": "kiosk",
      "metadata": {
        "created": "2026-03-25T14:00:00Z"
      }
    }
  ]
}

Results are ordered by creation date, newest first.

Tip Pool Distribution

To split a tip across multiple employees, include tipPoolConfig:

• distribution percentages must sum to exactly 100 (tolerance: ±0.01).
• Each pool member receives a separate dividend entry.
• The tip record tracks the full distribution in its disbursement object.