GetbeelDocs

Email, payments and reminders

Email the invoice to your customer, record payments, create a Stripe payment link and send reminders.

Once SDI has the invoice, it needs collecting. The API does what the Payment block of an issued invoice does in the app: customer emails, payments, payment links and reminders. Every endpoint uses the invoices:write scope (reads use invoices:read).

You can email, mark as paid and remind invoices SDI accepted (sent, delivered, not_delivered) and proformas. Drafts and rejected invoices answer 409 invoice_not_issued. Credit notes (TD04) can be emailed but are not collected: no payments, links or reminders.

Test keys

With a gb_test_ key you work on sandbox invoices and emails never reach the customer: they go only to the team owner's address, with a banner and [TEST] in the subject. In the response sandbox is true and sent_to shows where it actually went.

Email the invoice to the customer

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/email \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "to": ["accounts@customer.com"], "language": "en", "message": "Thank you for your business!", "attach_xml": false }'

Every field is optional: without to it uses the customer's email on the invoice (422 customer_email_missing when there is none). The customer receives the PDF as a courtesy copy (copia di cortesia): the legally valid invoice is the one SDI delivered, and the email says so. attach_xml: true also attaches the FatturaPA file. When the invoice has a payment link, the email has a Pay now button.

The response (201) is the email record with status: sent and provider_message_id. When the provider refuses the email we answer 502 email_failed: the attempt stays on record and you can retry with the same Idempotency-Key.

curl https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/deliveries \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

GET /deliveries lists the invoice's emails (copies and reminders), newest first.

Record a payment

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Without a body it records everything still due, dated today, method bank_transfer: the invoice becomes paid. For a part payment pass the amount:

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payments \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "50.00", "date": "2026-10-30", "method": "card" }'

Methods: bank_transfer, card, cash, stripe, other. More than what is still due answers 422 amount_exceeds_balance, an invoice already paid 409 invoice_already_paid. The response holds payment and the updated invoice.

Every invoice now has these fields:

FieldMeaning
payment_statusunpaid, partially_paid or paid
amount_dueWhat the customer pays: the total less the ritenuta d'acconto (withholding tax)
amount_paidSum of the payments recorded
paid_atDate of the payment that settled it
overduetrue when issued, unpaid and past due_date
payment_link_urlThe Stripe payment link, until paid

For invoices to collect or overdue: GET /invoices?payment_status=unpaid or GET /invoices?overdue=true. Invoices imported from Stripe are already paid.

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/payment-link \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

Creates a Payment Link for the outstanding amount on the Stripe account connected to the team (201), or returns the existing one (200). Without Stripe connected it answers 409 stripe_not_connected: connect it from the fatture emesse page of the app or with POST /connections/stripe. The Stripe mode must match the invoice: sandbox invoices need a test-mode connection, real invoices a live one (409 stripe_mode_mismatch otherwise). When a payment is recorded the link is switched off, since it charges the old balance: create a new one for what is left.

When the customer pays, Getbeel records the payment (method stripe) within the hour and the invoice becomes paid.

Reminders

A manual reminder:

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE_ID/reminders \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en" }'

It takes the same fields as the email (to, cc, language, message) and attaches the PDF with the payment link. An invoice already paid answers 409.

Automatic reminders are switched on per company in the app (Fatture emesse → Reminders): off by default, they go out the number of days after the due date you choose (for example 3, 10, 30), once per step, only for live invoices with the customer's email and due from the day you switched them on.

The same setting through the API (invoices:write, live keys; reading takes invoices:read and works with both):

curl -X PATCH https://www.getbeel.com/api/v1/companies/me/reminder-settings \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "days": [3, 10, 30] }'

A PATCH changes only what it sends. The answer, like GET /companies/me/reminder-settings, has enabled, days (up to 5 steps) and enabled_at, the day reminders started. MCP tools: get_reminder_settings, update_reminder_settings.

Webhooks

EventWhendata.object
invoice.emailedEmail or reminder sentinvoice_email
invoice.email_failedSending failedinvoice_email
invoice.paidThe payments cover what is dueinvoice
invoice.overdueThe day after the due date, once, when unpaidinvoice

With an AI assistant

The MCP server has email_invoice_to_customer, mark_invoice_paid, list_overdue_invoices, create_payment_link and send_payment_reminder. Before sending an email the assistant asks you to confirm the recipients.

On this page