`invoices.import`

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

POST/api/v1/accounting/invoices.import

Permissions

accounting:readaccounting:write

Who can call it

admin, finance

Retries

Idempotency key required

MCP

accounting_invoices_import

Fields

partyIdstring (ID)Required
The ID of a customer or vendor account, from parties.list.
numberstringRequired
1–60 characters
issueDatestringRequired
The date the document was issued, as YYYY-MM-DD.
dueDatestring
The date payment is due, as YYYY-MM-DD.
currencystring
Three-letter currency code, such as CAD or USD.
titlestring
A short title.
at most 200 characters
linesarray of objectsRequired
1–100 items
taxTreatmentenum or null
autohstgstgst_qstzero_ratedexemptnone
taxRateCodeenum or null
HST_13HST_14HST_15
taxesarray of objects
at most 5 items
notesstring
Notes kept with the record.
at most 4000 characters
statusenum
Only include records with this status.
sentpaidvoid
Default "sent"
sentOnstring
paidOnstring
idempotencyKeystringRequired
Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match.
8–200 characters

curl https://app.getoatmilk.com/api/v1/accounting/invoices.import \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
  "number": "example",
  "issueDate": "2026-09-30",
  "lines": [
    {
      "description": "Synthetic example from the docs",
      "unitAmountMinor": "1250"
    }
  ]
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/invoices.import", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
    "number": "example",
    "issueDate": "2026-09-30",
    "lines": [
      {
        "description": "Synthetic example from the docs",
        "unitAmountMinor": "1250"
      }
    ]
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/invoices.import",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
        "number": "example",
        "issueDate": "2026-09-30",
        "lines": [
            {
                "description": "Synthetic example from the docs",
                "unitAmountMinor": "1250",
            },
        ],
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Response

{
  "data": { … }
}

Try it

Checks your input with this action’s real schema and answers like the API, with synthetic data. No key needed, and nothing changes.

Input

POST/api/v1/accounting/invoices.import

curl https://app.getoatmilk.com/api/v1/accounting/invoices.import \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
  "number": "example",
  "issueDate": "2026-09-30",
  "lines": [
    {
      "description": "Synthetic example from the docs",
      "unitAmountMinor": "1250"
    }
  ]
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/invoices.import", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
    "number": "example",
    "issueDate": "2026-09-30",
    "lines": [
      {
        "description": "Synthetic example from the docs",
        "unitAmountMinor": "1250"
      }
    ]
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/invoices.import",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "partyId": "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
        "number": "example",
        "issueDate": "2026-09-30",
        "lines": [
            {
                "description": "Synthetic example from the docs",
                "unitAmountMinor": "1250",
            },
        ],
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Fields

Fields inside lines

Fields inside taxes

Example

Try it