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
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
GET /v1/invoices
List invoices
GET /v1/invoices/{id}
Get an invoice
POST /v1/invoices/{id}/void
Void an invoice
Last updated