Credit notes, quotes, items and numbering
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
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:
linesreplaces every line (send them all),customerandpaymentare sent whole,notes: nullremoves the causale. - If the draft has a withholding or a cassa previdenziale and you change
lines,withholdingorcassa_previdenziale, send those again too (nullremoves them): their amounts depend on the lines. Otherwise400 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_draftonce it is sent,409 invoice_send_in_progresswhile it is being sent. A rejected invoice is reopened first (SDI lifecycle); a sent one is corrected with a credit note.
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)
A credit note credits an invoice SDI accepted: all of it, or some lines (also with a smaller quantity).
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
linesit 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 withPOST /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_idpicks 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
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.
# 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}/pdfdownloads the PDF. With a test key the email goes to the account owner only.convertcreates the invoice dated today (ordate) with the next number, under the same rules asPOST /invoices(live keys need the SDI plan and quota), and marks the quote accepted. A quote converts once (409 quote_converted).POST /quotes/{id}/acceptandPOST /quotes/{id}/declinerecord 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
Saved products and services with price, VAT (or natura) and unit, to pick in invoices and quotes.
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)
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. 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.
# 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
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.