# 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:read`, `accounting:write` · Roles: admin, finance · Idempotency key required

MCP tool: `accounting_invoices_import`

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `partyId` | string (ID) | Yes | The ID of a customer or vendor account, from parties.list. |
| `number` | string | Yes | 1–60 characters. |
| `issueDate` | string | Yes | The date the document was issued, as YYYY-MM-DD. |
| `dueDate` | string |  | The date payment is due, as YYYY-MM-DD. |
| `currency` | string |  | Three-letter currency code, such as CAD or USD. |
| `title` | string |  | A short title. at most 200 characters. |
| `lines` | array of objects | Yes | 1–100 items. |
| `lines[].id` | string |  | The record's ID. at most 64 characters. |
| `lines[].description` | string | Yes | A short description. 1–500 characters. |
| `lines[].quantity` | string |  |  |
| `lines[].unitAmountMinor` | string |  | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Whole number written as a string, may be negative. |
| `lines[].isHeader` | boolean |  |  |
| `lines[].taxCode` | enum |  | One of: `standard`, `exempt`, `zero_rated`. |
| `taxTreatment` | enum or null |  | One of: `auto`, `hst`, `gst`, `gst_qst`, `zero_rated`, `exempt`, `none`. |
| `taxRateCode` | enum or null |  | One of: `HST_13`, `HST_14`, `HST_15`. |
| `taxes` | array of objects |  | at most 5 items. |
| `taxes[].label` | string | Yes | 1–80 characters. |
| `taxes[].rate` | string |  | Matches ^\d{1,3}(?:\.\d{1,4})?$. Default `"0"`. |
| `taxes[].amountMinor` | string | Yes | An amount in cents (the currency's smallest unit), written as a whole-number string such as "1250" for $12.50. Matches ^\d{1,18}$. |
| `notes` | string |  | Notes kept with the record. at most 4000 characters. |
| `status` | enum |  | Only include records with this status. One of: `sent`, `paid`, `void`. Default `"sent"`. |
| `sentOn` | string |  |  |
| `paidOn` | string |  |  |
| `idempotencyKey` | string | Yes | 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. |

## Example request

```bash
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"
    }
  ]
}'
```

Reference page: https://app.getoatmilk.com/docs/api/invoices.import