Create a draft from tracked time

Runs the preview with the customer's profile, then creates hours lines at exact tracked hours in the profile's currency and sets the service period. Skips missing rates and currency mismatches; 409 NOTHING_TO_BILL when no lines remain. Default billed hours are tracked hours; overrides cannot exceed tracked hours. 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. Fields marked required must be sent.

customerIdstring · uuidrequired

Customer whose billing profile supplies missing fields.

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.

sectionstring

Section on every generated line.

billedHoursobject

Map of preview line keys to billed hours (nonnegative, up to four decimals, no more than tracked hours).

exchangeRatenumber

TTD for one unit of the invoice currency; defaults to the customer's profile rate.

conversionFeePercentnumber

Foreign invoices: percentage taken off the TTD value booked (0 to under 100); null for none. On PATCH, omit all three books fields to keep the draft's. Defaults to the customer's profile fees.

conversionFeeTtdnumber

Foreign invoices: fixed TTD amount taken off the TTD value booked, after the percentage. Defaults to the customer's profile fees.

booksTotalnumber

Foreign invoices: the TTD total to book, typed instead of worked out (fees are then ignored). The document amounts don't change; the TTD amount is spread over the lines in proportion. Defaults to the customer's profile fees.

invoiceNumberstring

Drafts: a number to use instead of the next in sequence, up to 30 characters, unique in the business ignoring case (voided numbers included). It locks when the invoice is posted. Blank or null returns to the automatic number. Owner/Admin or Accountant only.

taxTreatmentstring

VAT treatment for every line, such as zero_rated for exported services; defaults to the business's VAT setup.Allowed:standardzero_ratedexemptout_of_scope

descriptionsobject

Map of preview line keys to descriptions; otherwise plainDescription.

issueDatestring · date

Defaults to today's business date on creation.

dueDatestring · date

Defaults to issue date plus 30 days on creation; cannot precede issue date.

notesstring

Invoice notes; empty string clears them.

Response

201 with a JSON body, as in the example.