Invoice every job billed at month end

POST/api/v1/invoices/month_end

Raises and issues one invoice for each job billed monthly that has completed visits not yet invoiced, then emails each invoice to its customer. A visit counts when the day it was booked for, in the account's time zone, is on or before through, which defaults to the last day of last month: run on the 1st, it takes the whole of the month before and nothing from the new one. Each invoice is the one createJobInvoice would raise for those visits, with a line for each visit under its date, and never covers more than one job. job_ids limits the run to those jobs. With email (the default), every invoice whose customer has an email address is sent as sendInvoice sends it, with the account's standard note or message in its place, and is listed among the customer's messages. A customer with no email address still gets an issued invoice, which is listed in not_emailed to be posted or handed over. These emails are not counted towards the 100 a day that sendInvoice is limited to. All or nothing: one job that cannot be invoiced stops the run and nothing is raised or sent. Sending the same request again with the same Idempotency-Key returns the first answer and raises and emails nothing more. Managers only. Errors: 422 nothing_to_invoice when no such job has visits to invoice; 422 round_too_large when there are more than 300 jobs (run it in parts with job_ids); 422 jobs_not_invoiceable when job_ids names a job that is not billed monthly or has nothing to invoice up to through; 422 job_has_no_items when a job in the run has no line items, with its id in meta.job_id; 422 message_too_long.

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 createMonthEndInvoices.

Parameters

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.

throughstring (date)
The last day whose visits are invoiced, in the account's time zone. Defaults to the last day of last month.
job_idsarray of string (uuid)
Jobs billed `monthly` that have visits to invoice. Omit to invoice every one.
At least 1 item.
emailboolean
Email each invoice to its customer. False issues the invoices and emails nobody.
Default: true.
messagestring or null
Replaces the account's standard invoice note in every email of the run. Placeholders in square brackets, such as [First name], [Number], [Amount], [Due date] and [Link], are filled in for each invoice.
Up to 2000 characters.

Responses

201The invoices raised, how many were emailed, and those that could not be.

dataobjectrequired
Fields(3)
- invoicesarray of objectrequired
  One issued invoice for each job in the run.
  Each item(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.
- emailedintegerrequired
  How many of the invoices were emailed.
  At least 0.
- not_emailedarray of objectrequired
  Invoices that were issued and not emailed, because the customer has no email address. Empty when `email` was false.
  Each item(3)
  invoice_idstring (uuid)required
  customer_idstring (uuid)required
  reasonstringrequired
  One of: no_email.

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/invoices/month_end" \
  -H "Authorization: Bearer $TRADESENDER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "through": "2026-09-30",
  "job_ids": [
    "57d29885-f541-5e38-8af4-af326a1435c4"
  ]
}'