Retrieve an issued invoice with its lines
apiKeyAuthorizationBearer <token>API key: gb_test_… or gb_live_…
id*stringGetbeel-Company?stringAct on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.
uuidOK
application/json- response
object*stringid*stringlivemode*booleanfalse for sandbox invoices created with a test key
number*stringInvoice number with its suffix
tipo_documento*stringinvoice_date*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$datedue_date*|nullstatus*stringdraft → sending (XML being generated and submitted) → sent (accepted by SDI) → delivered (RC), not_delivered (MC) or rejected (NS)
"draft""sending""sent""delivered""not_delivered""rejected"is_proforma*booleancurrency*stringamount_subtotal*stringDecimal amount as a string
^-?\d+\.\d{2}$amount_tax*stringDecimal amount as a string
^-?\d+\.\d{2}$amount_total*stringDecimal amount as a string
^-?\d+\.\d{2}$customer*sdi*payment_status*stringunpaid → partially_paid → paid, from the payments recorded (POST /v1/invoices/{id}/payments, Stripe payment links)
"unpaid""partially_paid""paid"amount_due*stringWhat the customer pays: amount_total less the ritenuta d'acconto and less amount_credited
^-?\d+\.\d{2}$amount_credited*stringTotal of the credit notes (TD04) on this invoice that SDI accepted; a fully credited invoice counts as paid
^-?\d+\.\d{2}$withholdings*array<>DatiRitenuta blocks: what the customer withholds and pays to the State or the fund (amount_due is net of all of them)
related_invoice_id*|Credit notes: the invoice they credit
series_id*|Numbering series (GET /numbering-series); null = the default numbering
amount_paid*stringDecimal amount as a string
^-?\d+\.\d{2}$paid_at*|Date of the payment that settled it
overdue*booleanIssued, not paid and due_date before today (Italian time)
payment_link_url*|Stripe payment link (POST /v1/invoices/{id}/payment-link)
lines?array<>Only on GET /v1/invoices/{id}
created_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timeupdated_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecurl -X GET 'https://www.getbeel.com/api/v1/invoices/string'{ "object": "invoice", "id": "fe_3f1c…", "livemode": true, "number": "string", "tipo_documento": "TD01", "invoice_date": "2026-10-29", "due_date": "2026-10-29", "status": "draft", "is_proforma": true, "currency": "string", "amount_subtotal": "122.00", "amount_tax": "122.00", "amount_total": "122.00", "customer": { "name": "string", "vat_number": "string", "codice_fiscale": "string", "codice_destinatario": "string", "pec": "string", "email": "string", "country": "string", "address": "string", "postal_code": "string", "city": "string", "province": "string" }, "sdi": { "identificativo_sdi": "string", "file_name": "string", "error_message": "string", "error_codes": [ "00404" ], "errors": [ { "code": "00305", "description": "1.4.1.1.2 <IdCodice> non valido" } ], "available_since": "2026-10-31", "updated_at": "2019-08-24T14:15:22Z" }, "payment_status": "unpaid", "amount_due": "122.00", "amount_credited": "122.00", "withholdings": [ { "type": "RT01", "rate": "122.00", "amount": "122.00", "reason": "A" } ], "related_invoice_id": "string", "series_id": "0f6582ac-1e7e-41dc-a63a-24fccd074d0c", "amount_paid": "122.00", "paid_at": "2026-10-29", "overdue": true, "payment_link_url": "string", "lines": [ { "description": "string", "quantity": "1", "unit_price": "100.00", "amount": "122.00", "vat_rate": "22.00", "natura": "N2.2" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}Create a draft invoice POST
Creates a draft issued invoice (fattura emessa). Totals are computed by getbeel. The number defaults to the next one (separate sequences for test and live keys) and the date to today in Italy. Live keys need an SDI plan, the pay-per-use rate card or an SDI add-on, and count toward its monthly quota (402 sdi_addon_required or sdi_quota_exhausted otherwise); test keys create sandbox invoices for free.
Edit a draft invoice PATCH
Changes a draft with the same rules as the app's edit form and as create (a 0% line needs a natura, totals are recomputed). Each field sent replaces that part: lines replaces every line, customer and payment are sent whole. When the draft has a withholding or cassa and you change lines, withholding or cassa_previdenziale, send them again (null removes them). A number from a numbering series and the type of a credit note cannot change. Only drafts: a rejected invoice is reopened first (POST /invoices/{id}/reopen); a sent one is corrected with a credit note.