# Email, payments and reminders (https://docs.getbeel.com/en/api/invoice-collection)

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.

<Callout title="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.
</Callout>

## Email the invoice to the customer [#email-the-invoice-to-the-customer]

```bash
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`.

```bash
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 [#record-a-payment]

```bash
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:

```bash
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:

| Field              | Meaning                                                                         |
| ------------------ | ------------------------------------------------------------------------------- |
| `payment_status`   | `unpaid`, `partially_paid` or `paid`                                            |
| `amount_due`       | What the customer pays: the total less the ritenuta d'acconto (withholding tax) |
| `amount_paid`      | Sum of the payments recorded                                                    |
| `paid_at`          | Date of the payment that settled it                                             |
| `overdue`          | `true` when issued, unpaid and past `due_date`                                  |
| `payment_link_url` | The 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.

## Stripe payment link [#stripe-payment-link]

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

Creates a [Payment Link](https://docs.stripe.com/payment-links) 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`](/en/api/connections). 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 [#reminders]

A manual reminder:

```bash
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):

```bash
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 [#webhooks]

| Event                  | When                                          | `data.object`   |
| ---------------------- | --------------------------------------------- | --------------- |
| `invoice.emailed`      | Email or reminder sent                        | `invoice_email` |
| `invoice.email_failed` | Sending failed                                | `invoice_email` |
| `invoice.paid`         | The payments cover what is due                | `invoice`       |
| `invoice.overdue`      | The day after the due date, once, when unpaid | `invoice`       |

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

The [MCP server](/en/api/mcp) 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.
