OatmilkDevelopers

API reference Get an API key

Invoicing

Invoices, customers and vendors, and how they pay.

50 actions

Give an AI assistant only these actions with the invoicing MCP toolset.

MCP address

https://app.getoatmilk.com/api/mcp?toolset=invoicing

invoices

POSTinvoices.approveApprove a prepared invoice so it can be sent on its scheduled date. Invoices prepared by schedules and payment plans are never sent without approval.
POSTinvoices.archiveArchive or restore up to 100 invoices at once with ids and archived (true to archive, false to restore). Archived invoices leave the invoice lists and counts but stay in the customer's history, reports and payments. Drafts and prepared invoices without a send date, paid, written-off and cancelled invoices can be archived; an invoice that is still owed or set to go out on a date is skipped with a reason (record the payment or write off the balance, or clear the send date, first). An archived invoice can't be approved, sent, paid, edited or cancelled until it is restored. Returns the invoices changed and, for each one left alone, why.
POSTinvoices.correctTaxCorrect how an issued invoice imported from outside Oatmilk splits its unchanged total into subtotal and sales tax, without voiding it: pass id, expectedRevision, taxes (up to 5 lines of label, rate in percent, and amountMinor; an empty list means no sales tax), a reason of 10 to 500 characters, and an idempotency key. The tax becomes the sum of the lines and the subtotal the total minus that tax, which moves onto the invoice's single line. The total, payments, status, number, dates, and PDF don't change, and the reason and the split before and after are kept in the audit history. Refused for invoices Oatmilk issued (void and duplicate those instead), void or uncollectible invoices, invoices with more than one line or a quantity other than 1, and taxes above the total. Administrator only.
POSTinvoices.createCreate a draft invoice for a customer. By default it starts from the customer's last invoice (lines, currency, notes, payment methods, terms); pass startFrom blank to start empty. Totals and sales tax are calculated on the server. Pass projectId to tie it to a project.
POSTinvoices.duplicateCreate a new draft from an existing invoice, or from a customer's last invoice when partyId is given. The new draft keeps the source invoice's project.
POSTinvoices.filesCommitImport reviewed invoice files with their original numbers, dates, lines, taxes, and status. Paid imports record a matching payment and PDFs become the invoice's permanent file. Nothing is emailed.
GETinvoices.filesExtractRead an uploaded invoice file and return extracted invoice candidates with suggested customers. For CSV files, first call without csvMapping to get headers, then call again with the confirmed column mapping.
POSTinvoices.filesPreparePrepare an invoice file upload (PDF, Word, image, CSV, or email up to 20 MB). Supply filename, mimeType, sizeBytes, sha256, and idempotencyKey. Upload unchanged bytes to the returned uploadUrl unless alreadyUploaded is true.
GETinvoices.getRead one invoice with its lines, taxes, totals, payments, balance due, printed customer and sender details, schedule, and approval and delivery history.
POSTinvoices.importRecord an invoice issued outside the platform with its original number, dates, lines, taxes, and status (sent, paid, or void) so it appears in customer history. Paid imports record a matching payment.
POSTinvoices.issueIssue a draft: assign the next invoice number, freeze the customer, sender, and payment details, and store the final PDF with its SHA-256 hash. Issuing does not email anyone.
GETinvoices.lastForPartyGet the most recent invoice for a customer and a starting template (lines, currency, notes, payment methods, terms, tax) for creating a similar invoice.
GETinvoices.listList invoices with number, customer, project, dates, totals, balance due, and status. Filter by status (including open, unpaid, upcoming and needs_action: awaiting approval, ready to send by hand, or late), overdue, customer, project (or none), currency, source (manual, duplicate, recurring, plan, import), schedule, issue or due date range, or search text. Archived invoices are left out unless archived is only or include. Sort by issued, due, amount, number, updated or created. Overdue is derived from the due date and remaining balance.
POSTinvoices.markUncollectibleMark an issued, unpaid invoice as uncollectible with a reason, or reopen it with uncollectible false.
GETinvoices.pdfGet a short-lived link to an issued invoice PDF and its SHA-256 hash.
GETinvoices.previewRender a PDF preview of a saved invoice or an unsaved draft without changing anything. Returns base64 PDF bytes, the number it would receive, and computed totals.
GETinvoices.projectSuggestionsSuggest which project (a project tag) an invoice belongs to. With id, the top suggestions for that invoice with their reasons; without, recent invoices that have no project and the best suggestion for each. Reasons are the customer's other invoices, invoices of the same recurring schedule or payment plan, the invoice it was duplicated from, the project tag on the bank deposit that paid it, the project's name, aliases or keywords in the title, lines or memo, and the issue date falling inside the project's dates. Suggestions are never applied by themselves; use invoices.setProject.
GETinvoices.projectTotalsInvoiced revenue per project and currency: how much was invoiced, collected and is still owed, and how many invoices, for issued invoices that aren't cancelled. Filter by projectIds and an issue-date range. Pair with tags.report for the project's spend and income from transactions.
POSTinvoices.recordPaymentRecord a full or partial payment on an issued invoice with amountMinor in the invoice currency, paid date, method, reference, and an optional bank transaction. Optionally write off a small remaining balance such as wire fees. Updates the balance and paid status.
POSTinvoices.remindEmail the customer a payment reminder for an issued, unpaid invoice with the PDF attached.
POSTinvoices.removePaymentRemove a recorded payment with a reason. The payment stays in history as reversed and the invoice balance and status are recalculated.
POSTinvoices.scheduleSet or clear the date an invoice is sent. Scheduling approves it and it is sent automatically on that date unless autoSend is false; pass review true to have administrators asked to review it a few days before instead.
POSTinvoices.sendSend an invoice to the customer's billing contacts from the invoices sender identity with the PDF attached, issuing it first if needed. The email is queued and the invoice marked sent together, and an invoice's first email goes out only once; sending an already-sent invoice again is a deliberate resend. Use method manual to record that you delivered it yourself.
POSTinvoices.setProjectTie up to 100 invoices to a project (a project tag's id from tags.list) or clear it with projectId null. Works on issued invoices too, because the project is internal and never printed. Archived projects can't be chosen. Returns the invoices changed and any left alone.
GETinvoices.summaryWhat the invoice list adds up to right now: what customers owe per currency and how much of it is overdue, what was paid in the last 30 days, and how many invoices need action, are overdue, are drafts, wait for approval, or are archived. Archived invoices are counted only as archived.
GETinvoices.taxPlaceWork out where a customer is for sales tax. With query, the places a typed city, town, province, postal code or country can mean (Toronto, Gimli MB, M5V 2T6, London UK), each with its jurisdiction such as CA-ON; a name Oatmilk doesn't know is read by AI that has no tools and never picks the tax. With partyId, a web search for the customer's head office by its name and website, returning the place only when a quote on the page it came from says it, with that page and quote. Only the name, the website or billing email's domain, and the city leave Oatmilk. Nothing is saved; set the customer's address or the invoice's tax to use the place.
POSTinvoices.updateEdit a draft, scheduled, or awaiting-approval invoice with its expectedRevision. Editing an approved invoice returns it for approval. Issued invoices can't be edited; void and duplicate them instead. Their memo and project (projectId) can still change.
POSTinvoices.voidVoid an invoice with a reason. Invoices with recorded payments must have those payments removed first. Voided invoices stay on record.

invoices.automation

POSTinvoices.automation.runRun invoice automation now for this organization: prepare due recurring invoices, request reviews, send approved invoices due today, and remind administrators about approvals. Administrator only.

invoices.numbering

GETinvoices.numbering.previewPreview the next invoice number using the saved or a proposed number pattern and next-number setting.

invoices.plans

POSTinvoices.plans.createCreate a payment plan that splits a project into 2 to 12 installment invoices on set dates, by percentages or exact pre-tax amounts that add up to the subtotal. Each installment is prepared ahead of time and needs approval before it is sent.

invoices.schedules

parties

paymentMethods