API Documentation

Integrate TipCalculate into your apps

Your API Key
Manage Keys

Overview

The TipCalculate API allows you to programmatically add and retrieve tip records. Use it to integrate tip tracking into your own apps, POS systems, or automation workflows.

Base URL

https://tipcalculateapp.com/api

Available Endpoints

POST /tips

Add a new tip record

GET /tips

Retrieve your tip history

Authentication

All API requests require authentication using a Bearer token. You can generate an API key from your Account Settings.

Using Your API Key

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request

# Using cURL
curl -X POST https://tipcalculateapp.com/api/tips \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"billAmount": 50.00, "tipPercentage": 20, "totalAmount": 60.00}'

Keep your API key secret! Don't share it publicly or commit it to version control.

Add a Tip

Create a new tip record in your history.

POST /tips

Request Body

Parameter Type Description
billAmount required number The bill amount before tip
tipPercentage required integer Tip percentage (e.g., 20 for 20%)
totalAmount required number Total amount including tip
tipAmount optional number The tip amount
businessName optional string Name of the business
categoryId optional string Category: restaurant, bar, cafe, delivery, salon, taxi, hotel, other
peopleCount optional integer Number of people splitting the bill
perPersonAmount optional number Amount per person if splitting
currencyId optional string Currency code (default: USD)
notes optional string Additional notes
addressOrDescription optional string Address or location description
latitude optional number Location latitude
longitude optional number Location longitude
timestamp optional integer Unix timestamp in milliseconds (default: now)

Example Request

{
  "billAmount": 85.50,
  "tipPercentage": 20,
  "tipAmount": 17.10,
  "totalAmount": 102.60,
  "businessName": "The Local Bistro",
  "categoryId": "restaurant",
  "peopleCount": 2,
  "perPersonAmount": 51.30,
  "notes": "Great service!"
}

Response

{
  "success": true,
  "message": "Tip added successfully",
  "id": "abc123-def456"
}

Get Tips

Retrieve your tip history.

GET /tips

Query Parameters

Parameter Type Description
limit optional integer Number of tips to return (default: 50, max: 100)

Example Request

curl https://tipcalculateapp.com/api/tips?limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "count": 2,
  "tips": [
    {
      "id": "abc123",
      "billAmount": 85.50,
      "tipPercentage": 20,
      "totalAmount": 102.60,
      "businessName": "The Local Bistro",
      "timestamp": 1706313600000
    }
  ]
}

Errors

The API uses standard HTTP status codes to indicate success or failure.

Status Code Description
200 Success
201 Created successfully
400 Bad request - missing or invalid parameters
401 Unauthorized - invalid or missing API key
404 Not found - invalid endpoint
500 Server error

Error Response Format

{
  "error": "Description of what went wrong"
}