Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

The invoice object

The invoice object in the Shortcut API - every field, an example, and the endpoints that return it.

An invoice: a bill to a customer.

Fields

Field
Type
Description

id

id

The invoice's id.

object

"invoice"

Always invoice.

number

integer

The invoice number the customer sees.

kind

standard, prepay, project

standard invoices bill completed visits or manual lines. prepay invoices bill a coverage period in advance (see coverageStartDate). project invoices bill a project (deposit, progress, or final).

status

draft, unpaid, overdue, paid, void

draft invoices have not been sent to the customer. unpaid invoices are sent and not yet due (or have no due date). overdue invoices are past dueAt. paid and void invoices are closed. These match the app's invoice list, except that the app shows a draft as Unpaid or Overdue.

paymentActivity

processing, verification or null

processing while a bank payment is in flight, verification while the bank needs the customer to verify; otherwise null. The invoice stays unpaid or overdue until the payment settles.

customerId

id

The customer billed.

propertyId

id or null

The property (service address) billed, when there is one.

propertyAddress

string or null

The property's address as printed on the invoice when it was created.

propertyLabel

string or null

The property's label as printed on the invoice when it was created.

subtotal

number

Sum of the lines before tax and fees, in US dollars.

salesTax

number

Sales tax charged, in US dollars.

taxMode

flat, automatic

How the sales tax was worked out when the invoice was created: flat is the workspace's one rate; automatic is a rate per property address and service category, split by jurisdiction in taxBreakdown.

taxExempt

boolean

Whether the customer was exempt from sales tax when the tax was worked out; salesTax is then 0.

taxBreakdown

array of objects or null

With taxMode automatic, the sales tax by jurisdiction; the entries' tax add up to salesTax. Null for flat invoices.

taxBreakdown[].level

string

The jurisdiction's level, such as state, county, city or district; flat for lines taxed at the workspace's flat rate because no address rate was available.

taxBreakdown[].name

string

The jurisdiction's name, such as Minnesota or Hennepin County.

taxBreakdown[].state

string or null

The jurisdiction's state code, such as MN, or null.

taxBreakdown[].ratePct

number

The jurisdiction's rate, in percent (6.875 is 6.875%).

taxBreakdown[].taxableAmount

number

Sales this jurisdiction taxed on the invoice, in US dollars.

taxBreakdown[].tax

number

Sales tax this jurisdiction charged on the invoice, in US dollars.

processingFee

number

The processing fee in total. With processingFeeScope card_only it is 0 until a credit card pays the invoice with the fee, then equals cardProcessingFee; it stays 0 when the invoice is paid without the fee (bank, debit, offline, or a card-fee payment review settled at the total), in US dollars.

processingFeeScope

all_payments, card_only

Which payments carry the processing fee, fixed when the invoice was created: all_payments (in total) or card_only (only a credit-card payment adds cardProcessingFee).

cardProcessingFee

number

With card_only, the fee a credit-card payment adds on top of total; bank, debit, check and cash payments never pay it. 0 for all_payments, in US dollars.

lateFees

number

Late fees applied and not removed, in US dollars.

total

number

What the customer owes in all: subtotal + salesTax + processingFee + lateFees, in US dollars.

dueDate

date or null

The due date as the customer's invoice prints it, YYYY-MM-DD: the calendar date of dueAt in UTC (the app stores a due date chosen as a date at midnight UTC). Null when there is none.

dueAt

timestamp or null

The stored due instant. The invoice is overdue once this moment passes, as in the app, ISO 8601 in UTC, or null.

coverageStartDate

date or null

First day a prepay invoice covers, YYYY-MM-DD, or null.

coverageEndDate

date or null

Last day a prepay invoice covers, YYYY-MM-DD, or null.

sentAt

timestamp or null

When the invoice was first sent, ISO 8601 in UTC, or null.

paidAt

timestamp or null

When the invoice was paid in full, ISO 8601 in UTC, or null.

createdAt

timestamp

When the invoice was created, ISO 8601 in UTC.

updatedAt

timestamp

When the invoice last changed, ISO 8601 in UTC.

lines

array of objects

The lines in the order the customer's invoice shows them. Sales tax is the invoice's salesTax, computed by the app on the underlying lines. Only in answers from GET /v1/invoices/{id}.

lines[].id

id

The line's id.

lines[].type

service, product, add_on, discount, manual, project

service bills a visit, product a product used on it, add_on an add-on to it, discount a visit discount (negative), manual a line entered by hand, project a project milestone, labor, material, change order, credit, or adjustment.

lines[].name

string

What the line is for, as the customer sees it.

lines[].description

string or null

More detail, as the customer sees it.

lines[].date

date

The service date of the line, YYYY-MM-DD.

lines[].amount

number

The line amount; a visit's amount includes the products shown as included in its price, in US dollars.

lines[].taxable

boolean

Whether sales tax applies to the line.

lines[].taxRatePct

number or null

With automatic sales tax, the line's rate in percent (0 when its category is not taxed there). Null on flat invoices, discount lines, and a visit line that includes products taxed at a different rate.

lines[].taxAmount

number or null

With automatic sales tax, the sales tax on the line in US dollars, after any discount on it; a visit's includes the products shown as included in its price. Null on flat invoices and discount lines.

lines[].quantity

number or null

Quantity, for product and project lines that have one.

lines[].unitPrice

number or null

Price per unit in US dollars, when the line has a quantity.

lines[].unitLabel

string or null

The unit, such as bag, when the line has one.

lines[].visitId

id or null

The visit the line bills, when there is one.

lines[].serviceId

id or null

The service the line bills, when there is one.

Example

Endpoints

Endpoint
What it does

GET /v1/invoices

List invoices

GET /v1/invoices/{id}

Get an invoice

POST /v1/invoices/{id}/void

Void an invoice

Last updated