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

{
  "recipientType": "employee",
  "recipientId": "abc123",
  "amount": 10.00,
  "environment": "live"
}

For an outlet or department, change recipientType and provide that entity's ID. The legacy employeeId field remains accepted for employee-only integrations, but new clients should always send the canonical recipient pair.

Expanded Request

{
  "recipientType": "outlet",
  "recipientId": "outlet456",
  "amount": 25.50,
  "currency": "USD",
  "idempotencyKey": "order-8675309-tip",
  "paymentMethod": "card",
  "source": "api",
  "visitId": "visit789",
  "ratingId": "rating123",
  "guestName": "Jane Smith",
  "guestRoom": "501",
  "guestEmail": "jane@example.com",
  "message": "Great service!",
  "serviceType": "housekeeping",
  "environment": "live"
}

Distribution is not selected by the guest request. Aplauso reads the saved rule on the exact canonical destination. If that rule is disabled, employee tips remain direct and outlet or department tips use their equal-split default. Parent rules are not inherited silently.

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": 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:

{
  "recipientType": "employee",
  "recipientId": "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?recipientType=outlet&recipientId=outlet456&environment=live&limit=50

Query Parameters

Response

{
  "tips": [
    {
      "id": "tip_xxxxxxxxxxx",
      "tipId": "tip_xxxxxxxxxxx",
      "recipientType": "outlet",
      "recipientId": "outlet456",
      "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.

Destination Distribution

Tip distribution is configured on the employee, outlet, or department record, not chosen per guest transaction:

• Employee sharing uses fixed employee percentages totaling 100%.
• Outlet and department rules use position groups totaling 100%; each group is split equally among matching active employees.
• Enabled rules fail closed: inactive or missing recipients, unmatched funded groups, empty groups, or invalid totals block payment until the rule is fixed or disabled.
• The tip record keeps the canonical recipient and the calculated allocation plan.
• Paid allocations create employee dividend entries without changing the canonical rating or tip destination.