Skip to navigation
API ReferenceInvoices

Create Invoice

Create a new invoice.

Required fields:

  • recordId: Project or account ID (the record must exist first)
  • calculationMethod: Must be “LINE_ITEMS” or “PERCENTAGE”

Conditionally required:

  • lineItems: Required when calculationMethod is “LINE_ITEMS” (at least one item)
  • percentage: Required when calculationMethod is “PERCENTAGE”

Optional fields:

  • issueDate: ISO 8601 datetime string
  • dueDate: ISO 8601 datetime string
  • status: Initial invoice status (defaults to DRAFT)
  • description: Invoice description

Authentication

x-api-keystring
API Key authentication via header

Request

This endpoint expects an object.
recordIdintegerRequired>=1
Project or account ID
calculationMethodenumRequired
Calculation method
Allowed values:
lineItemslist of objectsOptional

Required when calculationMethod is LINE_ITEMS and sections is not provided. Flat array of line items (auto-grouped into one unnamed section).

sectionslist of objectsOptional

Required when calculationMethod is LINE_ITEMS and lineItems is not provided. Grouped line items with named sections. May be combined with lineItems (ungrouped items).

percentagedoubleOptional>=0

Required when calculationMethod is PERCENTAGE.

statusenumOptional

Optional; defaults to DRAFT when omitted. To finalize the invoice, set SENT, PARTIALLY_PAID, or PAID — issueDate is then required. Lifecycle statuses (DECLINED, OVERDUE) cannot be set at creation.

Allowed values:
issueDatestringOptionalformat: "date-time"

Issue date (ISO 8601). Optional. Applied only when status is SENT/PARTIALLY_PAID/PAID (required for those); ignored for DRAFT invoices.

dueDatestringOptionalformat: "date-time"

Due date (ISO 8601 datetime string)

descriptionstring or nullOptional
Invoice description

Response

Invoice created successfully
idinteger
Invoice identifier
invoiceNumberinteger
Unique invoice number
statusenum
Invoice status
amountdouble
Total invoice amount
amountPaiddouble
Amount paid
calculationMethodstring

Calculation method (e.g., LINE_ITEMS)

createdAtstringformat: "date-time"
Creation timestamp
updatedAtstringformat: "date-time"
Last update timestamp
descriptionstring or nullOptional
Invoice description
basedOnIdinteger or nullOptional
ID of the record this invoice is based on
basedOnUidinteger or nullOptional
UID of the record this invoice is based on
dueDatestringOptionalformat: "date-time"
Due date
issueDatestring or nullOptionalformat: "date-time"
Issue date when the invoice has been issued
isArchivedbooleanOptional
Whether the invoice is archived
sharedWithPortalbooleanOptional
Whether the invoice is shared with portal
percentagedouble or nullOptional
Percentage if applicable
baseAmountdouble or nullOptional
Base amount if applicable
accountobject or nullOptional
recordobject or nullOptional
lineItemslist of objectsOptional

Errors

400
Bad Request Error
401
Unauthorized Error