Genaya

API Reference
SupportkeyGet API key
Sales

Invoices

Invoices with line items, totals, balances, and a send flow.

GET/invoices

List invoices

Returns a cursor-paginated list of invoices for the organization that owns the API key. Results are ordered by document id and exclude soft-deleted invoices. Pass number or uuid to look up a specific invoice server-side instead of paging the whole list. Requires scope: invoices:read.

Parameters

Query

number
integer
Filter to the invoice whose sequential business number is exactly this value (the `number` field on the invoice object). Must be numeric; a non-numeric value returns 400 (code invalid_number). Use one lookup filter at a time - combining number with uuid, or with from/to/updated_since, returns 400 (code conflicting_filters). Pagination (limit/starting_after) works unchanged within the filtered results.
uuid
string
Filter to the invoice whose short reference code is exactly this value (the `uuid` field on the invoice object). Codes are uppercase, so pass the code as shown (e.g. K7M2PQ). Use one lookup filter at a time - combining uuid with number, or with from/to/updated_since, returns 400 (code conflicting_filters). Pagination (limit/starting_after) works unchanged within the filtered results.

Response 200

No fields.

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
429Rate limited
500Unexpected server error
POST/invoices

Create an invoice

Creates a new invoice. The provided lineItems are validated and the subtotal, tax total, total, and balance are computed server-side - any caller-sent totals are ignored. A sequential business number is assigned from the organization's numbering settings. At least one line item is required. Requires scope: invoices:write.

Request body

FieldTypeDescription
lineItemsrequired
array of object
The invoice line items. At least one is required.
namerequired
string
The line item name.
description
string
Optional line item description.
quantityrequired
number
Quantity of the item. Must be greater than 0.
unitPricerequired
number
Price per unit. Must be 0 or greater.
unitCost
number
Cost per unit. Must be 0 or greater. Defaults to 0.
taxable
boolean
Whether tax applies to this line. Defaults to true.
taxRate
any
Tax rate accepted as a fraction (0..1), a percent number (0..100), or a percent string such as "10%". Normalized to a fraction server-side.
type
string
Line item type (e.g. item, custom, labor). Defaults to "item".
itemId
string
Optional catalog item/service reference.
invoiceName
string
Optional display name/title for the invoice.
status
string
Initial status. Defaults to "draft".
dueDate
string
Due date in YYYY-MM-DD form. Defaults to today.
terms
integer
Payment terms in days (net days). Defaults to 0.
currency
string
ISO currency code. Defaults to USD.
notes
string
Free-form notes.
discountName
string
Optional label for an applied discount.
clientId
string
Identifier of the client this invoice belongs to.
clientUUID
string
Short reference code of the linked client.
clientDocId
string
Firestore document id of the linked client.
clientName
string
Display name of the client.
firstName
string
Client first name snapshot.
lastName
string
Client last name snapshot.
companyName
string
Client company name snapshot.
email
string
Client email snapshot.
phoneNumber
string
Client phone number snapshot.
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment.
appointmentUUID
string
Short reference code of a linked appointment.
appointmentDocId
string
Firestore document id of a linked appointment.
organizationCompanyId
string
Identifier of the issuing organization company.
customFields
object
Arbitrary organization-defined custom field values.

Response 201

FieldTypeDescription
id
string
Unique invoice identifier (the Firestore document id).
object
string
The object type. Always "invoice".
number
integer
The sequential numeric business number assigned from the organization's numbering settings. Null if numbering could not be assigned.nullable
uuid
string
Short human-friendly reference code (e.g. for portal links).nullable
invoiceName
string
Optional display name/title for the invoice.nullable
status
string
The invoice status (e.g. draft, sent, paid).
currency
string
ISO currency code.
terms
integer
Payment terms in days (net days). Defaults to 0.
dueDate
string
Local due date in YYYY-MM-DD form.nullable
sent
boolean
Whether the invoice has been marked as sent.
sentAt
string <date-time>
ISO-8601 timestamp the invoice was sent, if ever.nullable
subtotal
number
Sum of all line-item amounts (quantity * unitPrice), computed server-side.
taxTotal
number
Total tax across taxable line items, computed server-side.
total
number
subtotal plus taxTotal, computed server-side.
discountTotal
number
Total discount applied, computed server-side.
discountName
string
Optional label for the applied discount.nullable
tipTotal
number
Total tip applied, computed server-side.
taxableTotal
number
Sum of taxable line-item amounts, computed server-side.
taxRate
string
Invoice-level tax rate, when stored as a single display value.nullable
itemCostTotal
number
Total item cost across line items, computed server-side.
laborCostTotal
number
Total labor cost across line items, computed server-side.
amountPaid
number
Total amount paid against this invoice.
balance
number
Outstanding balance (total minus amountPaid).
notes
string
Free-form notes on the invoice.nullable
clientId
string
Identifier of the client this invoice belongs to.nullable
clientUUID
string
Short reference code of the linked client.nullable
clientDocId
string
Firestore document id of the linked client.nullable
clientName
string
Display name of the client.nullable
firstName
string
Client first name snapshot.nullable
lastName
string
Client last name snapshot.nullable
companyName
string
Client company name snapshot.nullable
email
string
Client email snapshot.nullable
phoneNumber
string
Client phone number snapshot.nullable
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment, if any.nullable
appointmentUUID
string
Short reference code of a linked appointment.nullable
appointmentDocId
string
Firestore document id of a linked appointment.nullable
organizationCompanyId
string
Identifier of the issuing organization company.nullable
billedFrom
object
Read-only snapshot of the issuing organization company at the time the invoice was created or its company was changed. Never accepted on input.nullable
companyName
string
nullable
address
string
nullable
email
string
nullable
phone
string
nullable
logoUrl
string
nullable
websiteUrl
string
nullable
timeZone
string
nullable
timeZoneLabel
string
nullable
lineItems
array of object
The invoice line items.
entryId
string
Stable per-row identifier.nullable
itemId
string
Catalog item/service reference, if the line came from the catalog.nullable
itemandservicesId
string
Catalog reference used by inventory fulfillment. Present on invoices authored in-app; null for API-created lines.nullable
name
string
The line item name.nullable
description
string
Optional line item description.nullable
quantity
number
Quantity of the item.
unitPrice
number
Price per unit.
unitCost
number
Cost per unit (for margin tracking).
amount
number
Line total (quantity * unitPrice).
taxable
boolean
Whether tax applies to this line.
taxRate
number
Tax rate as a fraction in the range 0 to 1 (e.g. 0.1 for 10 percent).
type
string
Line item type (e.g. item, custom, labor).nullable
signatures
array of object
Signature references attached to the invoice.
signature
object
Legacy single-signature object, when present.nullable
customFields
object
Arbitrary organization-defined custom field values.
issueDate
string <date-time>
ISO-8601 timestamp the invoice was created (mirrors createdAt).nullable
reminderSentAt
string <date-time>
When a payment reminder was last sent for this invoice (read-only).nullable
createdAt
string <date-time>
ISO-8601 creation timestamp.nullable
updatedAt
string <date-time>
ISO-8601 last-update timestamp.nullable

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
409Idempotency-Key reused with a different body
422Rejected by a business rule
429Rate limited
500Unexpected server error
GET/invoices/{id}

Retrieve an invoice

Returns a single invoice by id. A record belonging to another organization returns 404 rather than 403, so this can never confirm cross-tenant existence. Requires scope: invoices:read.

Parameters

Path

idrequired
string
The invoice id.

Response 200

FieldTypeDescription
id
string
Unique invoice identifier (the Firestore document id).
object
string
The object type. Always "invoice".
number
integer
The sequential numeric business number assigned from the organization's numbering settings. Null if numbering could not be assigned.nullable
uuid
string
Short human-friendly reference code (e.g. for portal links).nullable
invoiceName
string
Optional display name/title for the invoice.nullable
status
string
The invoice status (e.g. draft, sent, paid).
currency
string
ISO currency code.
terms
integer
Payment terms in days (net days). Defaults to 0.
dueDate
string
Local due date in YYYY-MM-DD form.nullable
sent
boolean
Whether the invoice has been marked as sent.
sentAt
string <date-time>
ISO-8601 timestamp the invoice was sent, if ever.nullable
subtotal
number
Sum of all line-item amounts (quantity * unitPrice), computed server-side.
taxTotal
number
Total tax across taxable line items, computed server-side.
total
number
subtotal plus taxTotal, computed server-side.
discountTotal
number
Total discount applied, computed server-side.
discountName
string
Optional label for the applied discount.nullable
tipTotal
number
Total tip applied, computed server-side.
taxableTotal
number
Sum of taxable line-item amounts, computed server-side.
taxRate
string
Invoice-level tax rate, when stored as a single display value.nullable
itemCostTotal
number
Total item cost across line items, computed server-side.
laborCostTotal
number
Total labor cost across line items, computed server-side.
amountPaid
number
Total amount paid against this invoice.
balance
number
Outstanding balance (total minus amountPaid).
notes
string
Free-form notes on the invoice.nullable
clientId
string
Identifier of the client this invoice belongs to.nullable
clientUUID
string
Short reference code of the linked client.nullable
clientDocId
string
Firestore document id of the linked client.nullable
clientName
string
Display name of the client.nullable
firstName
string
Client first name snapshot.nullable
lastName
string
Client last name snapshot.nullable
companyName
string
Client company name snapshot.nullable
email
string
Client email snapshot.nullable
phoneNumber
string
Client phone number snapshot.nullable
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment, if any.nullable
appointmentUUID
string
Short reference code of a linked appointment.nullable
appointmentDocId
string
Firestore document id of a linked appointment.nullable
organizationCompanyId
string
Identifier of the issuing organization company.nullable
billedFrom
object
Read-only snapshot of the issuing organization company at the time the invoice was created or its company was changed. Never accepted on input.nullable
companyName
string
nullable
address
string
nullable
email
string
nullable
phone
string
nullable
logoUrl
string
nullable
websiteUrl
string
nullable
timeZone
string
nullable
timeZoneLabel
string
nullable
lineItems
array of object
The invoice line items.
entryId
string
Stable per-row identifier.nullable
itemId
string
Catalog item/service reference, if the line came from the catalog.nullable
itemandservicesId
string
Catalog reference used by inventory fulfillment. Present on invoices authored in-app; null for API-created lines.nullable
name
string
The line item name.nullable
description
string
Optional line item description.nullable
quantity
number
Quantity of the item.
unitPrice
number
Price per unit.
unitCost
number
Cost per unit (for margin tracking).
amount
number
Line total (quantity * unitPrice).
taxable
boolean
Whether tax applies to this line.
taxRate
number
Tax rate as a fraction in the range 0 to 1 (e.g. 0.1 for 10 percent).
type
string
Line item type (e.g. item, custom, labor).nullable
signatures
array of object
Signature references attached to the invoice.
signature
object
Legacy single-signature object, when present.nullable
customFields
object
Arbitrary organization-defined custom field values.
issueDate
string <date-time>
ISO-8601 timestamp the invoice was created (mirrors createdAt).nullable
reminderSentAt
string <date-time>
When a payment reminder was last sent for this invoice (read-only).nullable
createdAt
string <date-time>
ISO-8601 creation timestamp.nullable
updatedAt
string <date-time>
ISO-8601 last-update timestamp.nullable

Errors

401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
404No such resource in this organization
429Rate limited
500Unexpected server error
PATCH/invoices/{id}

Update an invoice

Updates an existing invoice. Only the supplied fields are changed. When lineItems are provided, the subtotal, tax total, total, and balance are recomputed server-side - caller-sent totals are never trusted. Line-item edits are rejected with a 422 once the invoice is paid, completed, fulfilled, cancelled, or voided. At least one line item is required when lineItems is supplied. Requires scope: invoices:write.

Parameters

Path

idrequired
string
The invoice id.

Request body

FieldTypeDescription
lineItems
array of object
Replacement line items. At least one is required when supplied.
namerequired
string
The line item name.
description
string
Optional line item description.
quantityrequired
number
Quantity of the item. Must be greater than 0.
unitPricerequired
number
Price per unit. Must be 0 or greater.
unitCost
number
Cost per unit. Must be 0 or greater. Defaults to 0.
taxable
boolean
Whether tax applies to this line. Defaults to true.
taxRate
any
Tax rate accepted as a fraction (0..1), a percent number (0..100), or a percent string such as "10%". Normalized to a fraction server-side.
type
string
Line item type (e.g. item, custom, labor). Defaults to "item".
itemId
string
Optional catalog item/service reference.
invoiceName
string
Optional display name/title for the invoice.nullable
status
string
The invoice status.
dueDate
string
Due date in YYYY-MM-DD form.nullable
terms
integer
Payment terms in days (net days).
currency
string
ISO currency code.
notes
string
Free-form notes.nullable
discountName
string
Optional label for an applied discount.nullable
sent
boolean
Whether the invoice is marked as sent.
clientId
string
Identifier of the client this invoice belongs to.nullable
clientUUID
string
Short reference code of the linked client.nullable
clientDocId
string
Firestore document id of the linked client.nullable
clientName
string
Display name of the client.nullable
firstName
string
Client first name snapshot.nullable
lastName
string
Client last name snapshot.nullable
companyName
string
Client company name snapshot.nullable
email
string
Client email snapshot.nullable
phoneNumber
string
Client phone number snapshot.nullable
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment.nullable
appointmentUUID
string
Short reference code of a linked appointment.nullable
appointmentDocId
string
Firestore document id of a linked appointment.nullable
organizationCompanyId
string
Identifier of the issuing organization company.nullable
customFields
object
Arbitrary organization-defined custom field values.

Response 200

FieldTypeDescription
id
string
Unique invoice identifier (the Firestore document id).
object
string
The object type. Always "invoice".
number
integer
The sequential numeric business number assigned from the organization's numbering settings. Null if numbering could not be assigned.nullable
uuid
string
Short human-friendly reference code (e.g. for portal links).nullable
invoiceName
string
Optional display name/title for the invoice.nullable
status
string
The invoice status (e.g. draft, sent, paid).
currency
string
ISO currency code.
terms
integer
Payment terms in days (net days). Defaults to 0.
dueDate
string
Local due date in YYYY-MM-DD form.nullable
sent
boolean
Whether the invoice has been marked as sent.
sentAt
string <date-time>
ISO-8601 timestamp the invoice was sent, if ever.nullable
subtotal
number
Sum of all line-item amounts (quantity * unitPrice), computed server-side.
taxTotal
number
Total tax across taxable line items, computed server-side.
total
number
subtotal plus taxTotal, computed server-side.
discountTotal
number
Total discount applied, computed server-side.
discountName
string
Optional label for the applied discount.nullable
tipTotal
number
Total tip applied, computed server-side.
taxableTotal
number
Sum of taxable line-item amounts, computed server-side.
taxRate
string
Invoice-level tax rate, when stored as a single display value.nullable
itemCostTotal
number
Total item cost across line items, computed server-side.
laborCostTotal
number
Total labor cost across line items, computed server-side.
amountPaid
number
Total amount paid against this invoice.
balance
number
Outstanding balance (total minus amountPaid).
notes
string
Free-form notes on the invoice.nullable
clientId
string
Identifier of the client this invoice belongs to.nullable
clientUUID
string
Short reference code of the linked client.nullable
clientDocId
string
Firestore document id of the linked client.nullable
clientName
string
Display name of the client.nullable
firstName
string
Client first name snapshot.nullable
lastName
string
Client last name snapshot.nullable
companyName
string
Client company name snapshot.nullable
email
string
Client email snapshot.nullable
phoneNumber
string
Client phone number snapshot.nullable
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment, if any.nullable
appointmentUUID
string
Short reference code of a linked appointment.nullable
appointmentDocId
string
Firestore document id of a linked appointment.nullable
organizationCompanyId
string
Identifier of the issuing organization company.nullable
billedFrom
object
Read-only snapshot of the issuing organization company at the time the invoice was created or its company was changed. Never accepted on input.nullable
companyName
string
nullable
address
string
nullable
email
string
nullable
phone
string
nullable
logoUrl
string
nullable
websiteUrl
string
nullable
timeZone
string
nullable
timeZoneLabel
string
nullable
lineItems
array of object
The invoice line items.
entryId
string
Stable per-row identifier.nullable
itemId
string
Catalog item/service reference, if the line came from the catalog.nullable
itemandservicesId
string
Catalog reference used by inventory fulfillment. Present on invoices authored in-app; null for API-created lines.nullable
name
string
The line item name.nullable
description
string
Optional line item description.nullable
quantity
number
Quantity of the item.
unitPrice
number
Price per unit.
unitCost
number
Cost per unit (for margin tracking).
amount
number
Line total (quantity * unitPrice).
taxable
boolean
Whether tax applies to this line.
taxRate
number
Tax rate as a fraction in the range 0 to 1 (e.g. 0.1 for 10 percent).
type
string
Line item type (e.g. item, custom, labor).nullable
signatures
array of object
Signature references attached to the invoice.
signature
object
Legacy single-signature object, when present.nullable
customFields
object
Arbitrary organization-defined custom field values.
issueDate
string <date-time>
ISO-8601 timestamp the invoice was created (mirrors createdAt).nullable
reminderSentAt
string <date-time>
When a payment reminder was last sent for this invoice (read-only).nullable
createdAt
string <date-time>
ISO-8601 creation timestamp.nullable
updatedAt
string <date-time>
ISO-8601 last-update timestamp.nullable

Errors

400Malformed or missing parameters
401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
404No such resource in this organization
422Rejected by a business rule
429Rate limited
500Unexpected server error
DELETE/invoices/{id}

Delete an invoice

Soft-deletes an invoice. The invoice is never hard-deleted; it is stamped with a deletion timestamp and excluded from future reads. Requires scope: invoices:write.

Parameters

Path

idrequired
string
The invoice id.

Response 200

FieldTypeDescription
id
string
The deleted invoice id.
object
string
deleted
boolean

Errors

401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
404No such resource in this organization
429Rate limited
500Unexpected server error
POST/invoices/{id}/send

Send an invoice

Marks an invoice as sent (sets the sent flag and a sent timestamp). If the invoice is currently a draft or has no status, its status transitions to "sent"; an invoice already past draft keeps its status. This endpoint does not email the client. Requires scope: invoices:write.

Parameters

Path

idrequired
string
The invoice id.

Response 200

FieldTypeDescription
id
string
Unique invoice identifier (the Firestore document id).
object
string
The object type. Always "invoice".
number
integer
The sequential numeric business number assigned from the organization's numbering settings. Null if numbering could not be assigned.nullable
uuid
string
Short human-friendly reference code (e.g. for portal links).nullable
invoiceName
string
Optional display name/title for the invoice.nullable
status
string
The invoice status (e.g. draft, sent, paid).
currency
string
ISO currency code.
terms
integer
Payment terms in days (net days). Defaults to 0.
dueDate
string
Local due date in YYYY-MM-DD form.nullable
sent
boolean
Whether the invoice has been marked as sent.
sentAt
string <date-time>
ISO-8601 timestamp the invoice was sent, if ever.nullable
subtotal
number
Sum of all line-item amounts (quantity * unitPrice), computed server-side.
taxTotal
number
Total tax across taxable line items, computed server-side.
total
number
subtotal plus taxTotal, computed server-side.
discountTotal
number
Total discount applied, computed server-side.
discountName
string
Optional label for the applied discount.nullable
tipTotal
number
Total tip applied, computed server-side.
taxableTotal
number
Sum of taxable line-item amounts, computed server-side.
taxRate
string
Invoice-level tax rate, when stored as a single display value.nullable
itemCostTotal
number
Total item cost across line items, computed server-side.
laborCostTotal
number
Total labor cost across line items, computed server-side.
amountPaid
number
Total amount paid against this invoice.
balance
number
Outstanding balance (total minus amountPaid).
notes
string
Free-form notes on the invoice.nullable
clientId
string
Identifier of the client this invoice belongs to.nullable
clientUUID
string
Short reference code of the linked client.nullable
clientDocId
string
Firestore document id of the linked client.nullable
clientName
string
Display name of the client.nullable
firstName
string
Client first name snapshot.nullable
lastName
string
Client last name snapshot.nullable
companyName
string
Client company name snapshot.nullable
email
string
Client email snapshot.nullable
phoneNumber
string
Client phone number snapshot.nullable
address
object
The client address snapshot stamped on the invoice.nullable
line1
string
Street address line.nullable
unit
string
Unit, suite, or apartment.nullable
city
string
nullable
state
string
nullable
zip
string
nullable
country
string
nullable
appointmentId
string
Business number of a linked appointment, if any.nullable
appointmentUUID
string
Short reference code of a linked appointment.nullable
appointmentDocId
string
Firestore document id of a linked appointment.nullable
organizationCompanyId
string
Identifier of the issuing organization company.nullable
billedFrom
object
Read-only snapshot of the issuing organization company at the time the invoice was created or its company was changed. Never accepted on input.nullable
companyName
string
nullable
address
string
nullable
email
string
nullable
phone
string
nullable
logoUrl
string
nullable
websiteUrl
string
nullable
timeZone
string
nullable
timeZoneLabel
string
nullable
lineItems
array of object
The invoice line items.
entryId
string
Stable per-row identifier.nullable
itemId
string
Catalog item/service reference, if the line came from the catalog.nullable
itemandservicesId
string
Catalog reference used by inventory fulfillment. Present on invoices authored in-app; null for API-created lines.nullable
name
string
The line item name.nullable
description
string
Optional line item description.nullable
quantity
number
Quantity of the item.
unitPrice
number
Price per unit.
unitCost
number
Cost per unit (for margin tracking).
amount
number
Line total (quantity * unitPrice).
taxable
boolean
Whether tax applies to this line.
taxRate
number
Tax rate as a fraction in the range 0 to 1 (e.g. 0.1 for 10 percent).
type
string
Line item type (e.g. item, custom, labor).nullable
signatures
array of object
Signature references attached to the invoice.
signature
object
Legacy single-signature object, when present.nullable
customFields
object
Arbitrary organization-defined custom field values.
issueDate
string <date-time>
ISO-8601 timestamp the invoice was created (mirrors createdAt).nullable
reminderSentAt
string <date-time>
When a payment reminder was last sent for this invoice (read-only).nullable
createdAt
string <date-time>
ISO-8601 creation timestamp.nullable
updatedAt
string <date-time>
ISO-8601 last-update timestamp.nullable

Errors

401Bad, missing, or revoked key
402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up
403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off
404No such resource in this organization
429Rate limited
500Unexpected server error