# Required fields when creating invoices through the API

> The minimum payload for POST /invoices, what Alya Books fills in for you, and what PINT AE still needs.

Source: /help/en/api/required-fields

`POST /invoices` accepts one invoice or a batch under `invoices`. Alya Books validates the payload, then runs the full PINT AE check before the invoice leaves draft. The list below separates what the request must contain from what must be set up once in the app.

## Required in the request

| Field | Rule |
|---|---|
| `buyer.name` or `buyer.id` | A buyer name, or the id of an existing contact |
| `items` | At least one line, at most 500 |
| `items[].description` | Text, up to 1000 characters |
| `items[].quantity` | Number |
| `items[].unitPrice` | Net price |

Everything else has a default: `issueDate` is today, `currency` is `AED`, `invoiceTypeCode` is `380` (tax invoice), `taxCategory` is `standard` with 5 %, `language` is `en`. `dueDate` is derived from `payment.termsDays` when given. If `buyer.trn` is sent it must be 15 digits.

## Required by PINT AE

These come from your organization settings and are checked on every invoice:

- Seller name, TRN (15 digits), street, city and country under **Settings → Profile** and **Tax & currency** (BT-27, BT-31, BT-35, BT-37, BT-40).
- For credit and debit notes: `precedingInvoice.number` (BT-25).
- A due date whenever an amount is due (IBR-127-AE): `dueDate`, or `payment.termsDays` to calculate it. Credit notes and fully prepaid invoices (`prepaidAmount` equal to the total) may leave it out.
- Custom fields marked required in the active template for the document kind, sent as `metadata: { key: value }`.

Missing seller data returns `400 E_VALIDATION` with the business terms in `extra.errors`, and nothing is created. Add `draftOnly: true` to create a draft anyway and finish it in the app.

## Recommended

Buyer TRN and email, payment means and IBAN (`payment.accountId`), and an order or buyer reference. They only raise warnings, but the FTA and your buyers expect them.

## Example

```json
{ "invoices": [{
  "buyer": { "name": "Buyer LLC", "trn": "100000000000011" },
  "issueDate": "2026-09-23",
  "payment": { "termsDays": 30 },
  "items": [{ "description": "Consulting, September", "quantity": 10, "unitPrice": 500 }],
  "submit": true
}] }
```

## Good to know

- `draftOnly` cannot be combined with `submit` or `send`.
- `invoiceNumber` is optional; the next number of the series is allocated. A number already in use fails with `field: invoiceNumber`.
- In a batch, elements with `success: true` were created even when the response status is `400`; retry only the failed ones.
- Contacts are matched by id, then TRN, then name; unknown buyers are created.

## Related

- [Which PINT AE fields the API supports](/help/en/api/ibt-field-support)
- [API errors and status codes](/help/en/api/error-handling)