Generate an invoice from a job

POST/api/v1/jobs/{job_id}/invoice

A job billed on_completion must be completed and gets one invoice; calling again returns it. A job billed per_visit or monthly (active or completed) gets one invoice covering the completed visits not yet invoiced: every one of them, or those listed in visit_ids. Each job line is written once per visit with the visit's date in its description ("Lawn mowing, 7 Oct"), the discount is applied once per visit, and the description lists the dates. Those visits then carry the invoice's invoice_id. visit_ids is ignored for a job billed on completion. A monthly job can be invoiced here at any time; createMonthEndInvoices invoices every such job at once. When the job came from a quote whose deposit was invoiced, its invoice takes the deposit off (deposit_invoice_id, deposit_deduction_cents). A job billed on_completion has one invoice, which always takes it: all of it, or as much as the invoice comes to. A job billed per_visit or monthly takes it on the first invoice that comes to at least the deposit; a smaller one takes nothing off and leaves it for a later invoice. Errors: 409 when the job is billed none, is cancelled or, billed on completion, not yet completed; 422 no_visits_to_invoice when a job billed by visit has no completed visits left to invoice, 422 visits_not_invoiceable when visit_ids names a visit that is not a completed, uninvoiced visit of this job, and 422 job_has_no_items when the job has no line items yet.

Needs an API key, and runs with the access of the member who made the key.
Send an Idempotency-Key. The same key with the same request within 24 hours gives the first answer again and changes nothing.
A connected AI assistant can use it too, as createJobInvoice.

Parameters

In the address

job_idstring (uuid)required

Headers

Idempotency-Keystringrequired
Unique user-scoped key for safely retrying this mutation for 24 hours.
At least 1 character. Up to 200 characters.

Request body

Sent as application/json.

lock_versioninteger
At least 0.
visit_idsarray of string (uuid)
Completed, uninvoiced visits of this job. Omit to invoice every one.
At least 1 item.

Responses

201Invoice details.

dataobjectrequired
Fields(49)
- lock_versionintegerrequired
  At least 0.
- created_atstring (date-time)required
- updated_atstring (date-time)required
- idstring (uuid)required
- account_idstring (uuid)required
- customer_idstring (uuid)required
- job_idstring (uuid) or null
- quote_idstring (uuid) or null
- kindstring
  `deposit` for the invoice issued when a quote that asks for a deposit is accepted; its `quote_id` is that quote. It is an invoice like any other: sent, paid, reminded about and voided the same way. Every other invoice is `standard`. Read-only.
  One of: standard, deposit.
- deposit_invoice_idstring (uuid) or null
  The deposit invoice this invoice takes off. The first invoice for a job whose quote had its deposit invoiced deducts it, once: the one invoice of a job billed on completion always, and for a job billed by visit the first invoice that comes to at least the deposit. An invoice made with createInvoice that names the job counts as the job's. A deposit invoice that has been voided is never deducted, and voiding or deleting the invoice that deducted one leaves it to be deducted again. Read-only.
- deposit_deduction_centsinteger (int64)
  The deposit invoice's amount before tax, taken off this invoice before tax beside `discount_cents`: `total_cents` is `subtotal_cents` less `discount_cents` less this, plus `tax_cents`. `tax_cents` is then the tax the lines carry after the discount, less the tax the deposit invoice charged, so the two invoices come to exactly what one would have. When the lines come to less than the deposit, all of them comes off and nothing is left to pay. 0 when no deposit is taken off. Read-only.
  At least 0.
- numberstringrequired
- titlestringrequired
- descriptionstring or null
- statusstringrequired
  One of: draft, issued, void.
- payment_statusstringrequired
  `written_off` when the business has written off what was left to pay (writeOffInvoice): settled, and never received.
  One of: unpaid, partially_paid, paid, written_off.
- overduebooleanrequired
  Past its due date with something left to pay. Never while `collecting`, or while `collect_on` is set.
- collectingbooleanrequired
  A payment is on its way and has not cleared: one the customer made online, or a Direct Debit. The invoice is not overdue, cannot be voided and is not to be chased.
- collecting_centsinteger (int64)required
  How much is on its way: the invoice's `pending` payments.
  At least 0.
- collect_onstring (date) or null
  The day the customer's bank is expected to be debited, when the invoice is going to be collected by Direct Debit without anybody asking: the due date, or the next working day; later when the invoice was issued with less than two working days to go, and on a bank holiday. Null for any other invoice, and once a collection has been started. An invoice collects itself only if it was issued while its customer's Direct Debit was in force, and nothing has been paid or tried online for it: one issued while a new Direct Debit was still being confirmed by the customer's bank is paid some other way, or collected with collectInvoice.
- collectablebooleanrequired
  Whether collectInvoice would start a Direct Debit for what is left to pay now.
- direct_debit_failedbooleanrequired
  True when the last Direct Debit collection tried for the invoice failed, or could not be started, and something is still left to pay. Nothing is tried again by itself: it stays true until collectInvoice starts another collection or the invoice is paid some other way. A payment recorded by hand with the method `direct_debit` does not count as a collection.
- currencystringrequired
- subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- discount_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- paid_centsinteger (int64)required
  Payments that have `succeeded`, less what was refunded.
  At least 0.
- written_off_centsinteger (int64)required
  What the business wrote off with writeOffInvoice because the customer will not pay it: settled, and never received, so it is not in `paid_cents`. 0 unless written off.
  At least 0.
- written_off_atstring (date-time) or null
  When it was written off. Null unless it is.
- write_off_reasonstring or null
  Why it was written off. The customer is never shown it.
  Up to 255 characters.
- written_off_by_membership_idstring (uuid) or null
  The member who wrote it off.
- balance_due_centsinteger (int64)required
  What is left to pay: the total less `paid_cents` and `written_off_cents`, and never below zero.
  At least 0.
- issue_datestring (date) or null
- due_datestring (date) or null
- issued_atstring (date-time) or null
- paid_atstring (date-time) or null
  When nothing was left to pay. Null again if a refund, a failed payment or a dispute leaves a balance, and null for an invoice written off: that is settled, not paid.
- voided_atstring (date-time) or null
- sent_atstring (date-time) or null
  When the invoice was last emailed.
- sent_to_emailstring (email) or null
- email_messagestring
  The note the invoice is emailed with unless the sender edits it, from the account's template. [Link] and any placeholder without a value yet are filled in on sending.
- public_urlstring (uri) or null
  The customer's link. Null while the invoice is a draft or archived.
- notesstring or null
- termsstring or null
- bill_toobject or null
  Who the invoice is addressed to and where the work was, frozen when it is issued. Null on a draft, which shows the live customer and property.
  Fields(4)
  namestringrequired
  The property's billing name, else the customer's name.
  company_namestring or null
  addressobject or null
  The property's billing address, else the customer's, else the property's own address.
  Fields(6)
  address_line_1stringrequired
  address_line_2string or null
  citystringrequired
  regionstring or null
  postal_codestringrequired
  country_codestringrequired
  At least 2 characters. Up to 2 characters.
  propertystring or null
  The property the work was at, on one line, printed as "Property: …".
- invoice_remindersstringrequired
  Whether the overdue reminders the workspace sends by itself go for this invoice: `default` follows its customer's `invoice_reminders`. The one field an issued invoice can still change: send it with `lock_version` alone.
  One of: default, on, off. Default: "default".
- remindersobject or nullrequired
  Where the invoice's overdue reminders stand. Null for an invoice that asks for nothing: a draft, a void or archived invoice, and one with nothing left to pay.
  Read only.
  Fields(5)
  settingstringrequired
  Whether an email the workspace sends by itself goes: `default` follows the workspace's switch, `on` sends it even while that is off, and `off` never does. The most specific setting wins: an invoice's own over its customer's, and a customer's over the workspace's. Set to `on`, it counts from that moment, so nothing already overdue or awaiting an answer is chased that day. Emails a person sends are not affected.
  One of: default, on, off. Default: "default".
  sentintegerrequired
  How many reminders the customer has been sent about it, by themselves or with sendInvoiceReminder.
  At least 0.
  limitintegerrequired
  The most that are sent by themselves, the workspace's `invoice_reminder_limit`.
  At least 1.
  next_onstring (date) or nullrequired
  The first day the next reminder can go by itself, in the workspace's time zone. A refund, a failed payment or a dispute can hold it back. Null when `reason` says why none will.
  reasonstring or nullrequired
  Why no reminder will go by itself. `collecting`: a payment is on its way. `direct_debit`: a Direct Debit is going to collect it. `customer_archived`: the customer is archived. `no_email`: the customer has no email address. `off_invoice`, `off_customer`, `off_workspace`: the setting that decides is off. `plan`: the plan does not include automatic emails. `all_sent`: it has had `limit`. Null while one is to come.
  One of: collecting, direct_debit, customer_archived, no_email, off_invoice, off_customer, off_workspace, plan, all_sent.
- itemsarray of objectrequired
  Each item(12)
  idstring (uuid)required
  service_idstring (uuid) or null
  positionintegerrequired
  descriptionstringrequired
  quantitystringrequired
  Matches ^\d{1,9}(\.\d{1,3})?$.
  unit_namestring or null
  unit_price_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_rate_basis_pointsintegerrequired
  At least 0. At most 10000.
  tax_inclusivebooleanrequired
  subtotal_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  tax_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
  total_centsinteger (int64)required
  Integer minor currency units, such as pence.
  At least 0.
- paymentsarray of objectrequired
  Each item(10)
  idstring (uuid)required
  amount_centsinteger (int64)required
  At least 1.
  methodstringrequired
  One of: cash, cheque, card, bank_transfer, direct_debit, other.
  statusstringrequired
  A payment recorded with createInvoicePayment or createCustomerPayment has `succeeded`. One the customer made online, or a Direct Debit, is `pending` until the money clears, `failed` if it does not or if a dispute is lost, and `disputed` while the customer's bank decides a dispute. A Direct Debit collection that could not be started at all is recorded as `failed` too, with why in `notes`. Only a `succeeded` payment, less `refunded_cents`, counts towards the invoice's `paid_cents`.
  One of: pending, succeeded, failed, disputed.
  refunded_centsinteger (int64)required
  How much of the payment has been refunded: its `refunds` that `succeeded`, added up, and 0 for a payment that `failed`. Never more than `amount_cents`.
  At least 0.
  refundsarray of objectrequired
  Every refund of the payment, oldest first, including those that failed. Empty when there are none. A history: `refunded_cents` is the figure to count with.
  Each item(9)
  idstring (uuid)required
  amount_centsinteger (int64)required
  How much was refunded, in minor currency units.
  At least 1.
  statusstringrequired
  `succeeded` from the moment the refund is made, though a refund through Stripe can take 5 to 10 working days to reach the customer's card or bank account. `failed` when Stripe could not get the money back to the customer, or the refund was cancelled: it no longer counts in the payment's `refunded_cents`, so the payment counts towards the invoice again.
  One of: succeeded, failed.
  sourcestringrequired
  How it was made. `app`: from TradeSender, through the business's Stripe account ("From TradeSender"). `manual`: a payment recorded by hand, refunded as a record, with no money moved ("Recorded by hand"). `stripe`: outside TradeSender, in the Stripe dashboard or by Stripe itself ("In Stripe").
  One of: app, manual, stripe.
  membership_idstring (uuid) or nullrequired
  The member who made it. Null for a refund made in Stripe, and for one whose maker was not kept.
  refunded_atstring (date-time)required
  When the refund was made.
  failed_atstring (date-time) or nullrequired
  When the refund was found to have failed. Null unless it `failed`.
  failure_reasonstring or nullrequired
  Stripe's reason for a refund that failed, such as `expired_or_canceled_card` or `lost_or_stolen_card`, when it gives one.
  referencestring or nullrequired
  The last 8 characters of Stripe's id for the refund. Null for a refund recorded by hand.
  onlinebooleanrequired
  Whether the payment went through the business's Stripe account: paid online by the customer, or collected by Direct Debit. A refund of it goes back through Stripe to the card or bank account it came from. False for a payment recorded with createInvoicePayment or createCustomerPayment, whose refund moves no money.
  referencestring or null
  notesstring or null
  For a payment that failed, why.
  paid_atstring (date-time)required
  When it was paid. For a payment made online, when the customer started it.

A refusal answers in the one error shape every operation shares.

Example

A request our own tests send. The ids are made up: put your own in their place.

curl -X POST "https://app.tradesender.co.uk/api/v1/jobs/4088bebb-3a71-586f-922c-1612b3fa6557/invoice" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)"