Billing

Preview time to bill

POSThttps://paysuitett.com/api/v1/billing/preview

Approved and awaiting-approval billable time, excluding linked entries. Missing fields use the customer's profile. Missing dates use its next service period; 409 NOTHING_TO_BILL when no period is available. Amount is tracked hours × rate, rounded to two decimals, or zero for a missing rate or currency mismatch. Unknown fields are rejected.

Access. Master key, or a personal key held by an owner/admin or accountant. The business must have the invoices service. Runs as the holder under their row-level security.

Body

A JSON object. Every field is optional.

customerIdstring · uuid: Customer whose billing profile supplies missing fields.
clientNamesarray: Time client names; defaults to the profile's names.
projectIdsarray: Time project UUIDs; defaults to the profile's projects. A client OR project match includes time.
startstring · date: First service date; defaults to nextServicePeriod from the customer's profile.
endstring · date: Last service date, inclusive; defaults to nextServicePeriod (no later than yesterday).
groupBystring: Defaults to the profile's grouping, then project.Allowed:projectproject_tasksingle
rateSourcestring: Defaults to customer when a rate is known, otherwise project.Allowed:customerproject
ratenumber: Nonnegative hourly rate in the invoice currency; defaults to the customer's profile rate.
currencystring: Invoice currency (three letters); defaults to the profile's, then TTD. Project rates in another currency are flagged currencyMismatch.
invoiceIdstring · uuid: Current invoice, whose existing links are excluded without counting as billed elsewhere.

Response

200 with a JSON body, as in the example.

curl -X POST "https://paysuitett.com/api/v1/billing/preview" \
  -H "Authorization: Bearer $PAYSUITETT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerId":"4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b"}'

Success

{
  "period": {
    "start": "2026-10-01",
    "end": "2026-10-14",
    "text": "1–14 Oct 2026"
  },
  "rate": 150,
  "rateSource": "customer",
  "groupBy": "project",
  "lines": [
    {
      "key": "p:a1b2c3d4-e5f6-4789-90ab-cdef12345678",
      "title": "Development",
      "needsInvoiceName": false,
      "projectIds": [
        "a1b2c3d4-e5f6-4789-90ab-cdef12345678"
      ],
      "trackedHours": 2,
      "unapprovedHours": 0,
      "rate": 150,
      "currencyMismatch": false,
      "entryIds": [
        "7b8f0c2e-3c4d-4a51-9a0e-2f1b6c9d8e71"
      ],
      "taskTitles": [
        "Updated checkout"
      ],
      "plainDescription": "Development: Updated checkout",
      "amount": 300
    }
  ],
  "totals": {
    "trackedHours": 2,
    "amount": 300
  },
  "unapprovedHours": 0,
  "alreadyBilledHours": 0,
  "alreadyBilledOn": [],
  "currency": "TTD",
  "exchangeRate": null,
  "invoiceNumberPrefix": null
}