# Credit notes, quotes, items and numbering (https://docs.getbeel.com/en/api/invoicing)

Credit an invoice with a TD04 credit note, turn a quote into an invoice, save items and number with series.

Four everyday invoicing tools, on the same services as the app. Writes need the `invoices:write` scope, reads `invoices:read`. Test keys work on sandbox data (their own credit notes, quotes and items), live keys on real data.

## Edit a draft [#edit-a-draft]

`PATCH /invoices/{id}` changes a draft with the same rules as create and the app's edit form; the answer is the invoice with its totals recomputed.

- Send only what changes. Each field replaces that part: `lines` replaces every line (send them all), `customer` and `payment` are sent whole, `notes: null` removes the causale.
- If the draft has a withholding or a cassa previdenziale and you change `lines`, `withholding` or `cassa_previdenziale`, send those again too (`null` removes them): their amounts depend on the lines. Otherwise `400 parameter_missing`.
- A number from a numbering series and the type of a credit note do not change: sending a different value answers `422 invoice_invalid` (the same value is accepted), and a series number cannot move to another year (`422 invoice_invalid`); a typed number must fit the year's sequence (`422 invoice_number_out_of_sequence`).
- Only drafts: `409 invoice_not_draft` once it is sent, `409 invoice_send_in_progress` while it is being sent. A rejected invoice is reopened first ([SDI lifecycle](/en/api/sdi-lifecycle#rejected-ns--rejected)); a sent one is corrected with a credit note.

```bash
curl -X PATCH https://www.getbeel.com/api/v1/invoices/$INVOICE \
  -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"lines": [{"description": "Consulenza novembre", "quantity": "3", "unit_price": "120.00", "vat_rate": "22"}], "notes": "Novembre 2026"}'
```

In MCP: `update_invoice_draft` and `reopen_rejected_invoice`.

## Credit notes (TD04) [#credit-notes-td04]

A credit note credits an invoice SDI accepted: all of it, or some lines (also with a smaller quantity).

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/credit-notes \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [{ "index": 0, "quantity": 2 }], "reason": "Returned goods" }'
```

- Without `lines` it credits the whole invoice (ritenuta, cassa and discounts included). A partial credit leaves those out: split them by hand.
- The note copies the customer and payment data, refers to the invoice in `DatiFattureCollegate` (number and date) and starts as a **draft**: send it with `POST /invoices/{id}/send`, like any invoice. Webhook events are the invoice ones (`invoice.sent`, `invoice.delivered`…).
- Number: the default series for credit notes, else the invoice's series. `series_id` picks one.
- Credit notes that were not rejected can add up to the invoice total at most (`422 credit_exceeds_invoice`). Drafts, proformas and other notes cannot be credited (`409`).

Once SDI accepts the note, the invoice shows `amount_credited` and its `amount_due` goes down: fully credited, it becomes `paid`, and reminders and overdue events take it into account. A rejected note stops counting.

Alternatively, `POST /invoices` with `tipo_documento: "TD04"` and `related_invoice_id` creates a note with free lines.

In the app: open a sent invoice and choose **Create credit note**.

## Quotes [#quotes]

A quote has the same fields as an invoice (customer, lines, payment, notes) plus `valid_until`. Numbered per year (`12/2026`), statuses `draft` → `sent` → `accepted` or `declined`; a draft or sent quote past `valid_until` reads as `expired`.

```bash
# create
curl -X POST https://www.getbeel.com/api/v1/quotes \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "denominazione": "Rossi S.r.l.", "partita_iva": "01234567890", "email": "accounts@rossi.it" },
    "lines": [{ "description": "Website", "unit_price": "2500", "vat_rate": "22" }],
    "valid_until": "2026-12-31"
  }'

# email the PDF to the customer
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# accepted: it becomes an invoice draft
curl -X POST https://www.getbeel.com/api/v1/quotes/$QUOTE/convert \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

- `GET /quotes/{id}/pdf` downloads the PDF. With a test key the email goes to the account owner only.
- `convert` creates the invoice dated today (or `date`) with the next number, under the same rules as `POST /invoices` (live keys need the SDI plan and quota), and marks the quote accepted. A quote converts once (`409 quote_converted`).
- `POST /quotes/{id}/accept` and `POST /quotes/{id}/decline` record the customer's answer.
- `GET /quotes/{id}` reads a quote; `PATCH /quotes/{id}` changes it until it is converted (`409 quote_converted`) or accepted (`409 quote_not_editable`); `DELETE /quotes/{id}` removes it (its invoice, if any, stays).

In the app: **Issued invoices → Quotes**.

## Items [#items]

Saved products and services with price, VAT (or natura) and unit, to pick in invoices and quotes.

```bash
curl -X POST https://www.getbeel.com/api/v1/items \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Consulting", "unit_price": "80", "unit": "ore", "vat_rate": "22" }'
```

`GET /items?search=consult`, `PATCH /items/{id}` and `DELETE /items/{id}`. Invoices already made do not change when you edit an item.

## Numbering (series) [#numbering-series]

Without series Getbeel uses Standard numbering: plain numbers without a suffix (`1`, `2`, `3`…) restarting at 1 every calendar year, as the Agenzia delle Entrate allows (Risoluzione 1/E of 2013); if the company chose one sequence across years, `default_numbering.yearly_reset` is `false`. Invoices numbered before keep the number sent to SdI (`45/`) and the next one continues without the slash (`46`). An invoice's `number` is always exactly the XML `Numero`. Without `number`, `POST /invoices` assigns it for the year of the date; a numeric `number` may be the next one or fill a gap, never skip ahead of its year's sequence (`422 invoice_number_out_of_sequence`). See the [numbering guide](/en/guide/numerazione-fatture). A series adds a prefix or suffix (`FT-12`, `12/A`), restarts from 1 every year (unless `yearly_reset: false`) and has its own sequence, separate for test and live keys. A number is never assigned twice.

```bash
# list with the next number
curl https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

# new series, default for invoices (live keys only)
curl -X POST https://www.getbeel.com/api/v1/numbering-series \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Foreign", "suffix": "/E", "default_for_invoices": true }'
```

`POST /invoices`, `POST /quotes/{id}/convert` and credit notes take `series_id` (`null` = the standard numbering). Prefix, suffix and yearly restart cannot change after the first invoice (`409 numbering_series_in_use`); `GET /numbering-series/{id}` reads one series, and `PATCH /numbering-series/{id}` renames it, makes it the default or archives it (`{ "archived": true }`), with a live key.

In the app: **Issued invoices → Quotes → Numbering**, and the **Numbering** menu in the new-invoice form.

## With an AI assistant [#with-an-ai-assistant]

MCP tools: `list_quotes`, `create_quote`, `send_quote`, `convert_quote_to_invoice`, `create_credit_note`, `list_credit_notes` and `list_items`. The assistant asks before sending an email or creating a credit note; nothing goes to SDI without `send_invoice`.
