---
updatedAt: 2026-08-11T09:36:39.000Z
agentTools:
  projectIndex: https://docs.mollie.com/llms.txt
---

# Sales Invoices API guide

Use the four scenarios below as a guidance to implement the most common Sales Invoices API integration patterns.

<Callout icon="📘" theme="info">
  **Business recipients:** for `type: "business"`, you must provide either `vatNumber` or `organizationNumber` (Chamber of Commerce number). At least one is required.
</Callout>

## Scenario 1: Create draft → issue and send

**Use case:** you want to review or store an invoice before sending it — e.g., when generating invoices in bulk or when a human approval step is required before delivery.

### Step 1: Create draft

```http
POST /v2/sales-invoices
```

```json
{
  "status": "draft",
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "billing@acme.nl",
    "streetAndNumber": "Keizersgracht 1",
    "postalCode": "1015 CW",
    "city": "Amsterdam",
    "country": "NL"
  },
  "lines": [
    {
      "description": "Consulting services — April 2026",
      "quantity": 1,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "1000.00"
      }
    }
  ]
}
```

The response contains the invoice `id`, (e.g., `invoice_4Y0eZitmBnQ6IDoMqZQKh`), and `status: "draft"`. No invoice number is assigned until the invoice is issued.

### Step 2: Issue and send draft

Once you are ready to send the draft, update the invoice to `issued` and include `emailDetails`. Mollie sends the invoice to the recipient by email and allows payment through the payment link included in the email.

```http
PATCH /v2/sales-invoices/{id}
```

```json
{
  "status": "issued",
  "emailDetails": {
    "subject": "Invoice from Acme B.V.",
    "body": "Dear customer,\n\nPlease find your invoice attached. You can pay it online via the link below.\n\nThank you."
  }
}
```

The response includes:

* `invoiceNumber` — assigned on issue (e.g., `#I-0042`).
* `issuedAt` — timestamp of when the invoice was issued.
* `dueAt` — calculated using `issuedAt` and the set `paymentTerm`.
* `_links.invoicePayment` — payment link URL to redirect to or share with your customer.

## Scenario 2: Automatic payment via mandate

**Use case:** you have a recurring billing setup where the customer has given a direct debit or card mandate. Mollie collects the payment automatically — no customer action is required.

**Prerequisites:** the customer must exist in Mollie and have a `customerId` along with a valid `mandateId`. Add these using [Customers](https://docs.mollie.com/reference/create-customer) and [Mandates](https://docs.mollie.com/reference/mandates-api) APIs before you create an invoice.

### Create invoice and trigger payment

Submit a `POST` request with `status: "paid"`, customer's `customerId` and `mandateId`. Mollie creates and issues the invoice and immediately initiates the recurring payment.

```http
POST /v2/sales-invoices
```

```json
{
  "status": "paid",
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "customerId": "cst_kEn1PlbGa",
  "mandateId": "mdt_h3gAaD5zP",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "billing@acme.nl",
    "streetAndNumber": "Keizersgracht 1",
    "postalCode": "1015 CW",
    "city": "Amsterdam",
    "country": "NL"
  },
  "lines": [
    {
      "description": "Subscription — May 2026",
      "quantity": 1,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "49.00"
      }
    }
  ]
}
```

### What happens next

The payment is processed asynchronously. The invoice moves to `pending-payment` while Mollie processes the charge.

| Outcome                      | Invoice status                                                                                                |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------ |
| Payment succeeds             | `paid` — `paymentDetails` in the response includes the payment token of the recurring payment that succeeded. |
| Payment fails or is rejected | `issued` — reverts to an unpaid but issued invoice; payment link payments are now possible.                   |

We recommend setting up and listening to webhooks for Sales Invoices to handle both outcomes. If the payment fails, the invoice falls back to `issued` so the customer can still pay through the payment link.

## Scenario 3: Invoice as receipt (payment already collected)

**When to use:** Payment has already been collected — either outside Mollie, such as by bank transfer or cash, or through Mollie in a separate transaction. You want to create an invoice as a receipt and mark it as paid immediately.

### Create the invoice and mark as paid

```http
POST /v2/sales-invoices
```

```json
{
  "status": "paid",
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "billing@acme.nl",
    "streetAndNumber": "Keizersgracht 1",
    "postalCode": "1015 CW",
    "city": "Amsterdam",
    "country": "NL"
  },
  "lines": [
    {
      "description": "Product delivery — order #8821",
      "quantity": 3,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "25.00"
      }
    }
  ],
  "paymentDetails": {
    "source": "manual"
  }
}
```

The invoice is created and immediately moves to `paid`. No payment link is generated, and the invoice shows the full amount as `paid` on the date the invoice was created. <br />You can include `emailDetails` in the same request if you want to send the paid invoice as a PDF to the recipient.

## Scenario 4: E-invoice via Peppol

**Use case:** your customer has requested a structured e-invoice delivered directly to their accounting system via Peppol network. Both you and your customer must be based in **NL**, **BE**, or **DE**.

**Prerequisites:** E-invoicing must be enabled in your Organization settings. Mollie automatically checks whether the recipient is registered with Peppol before delivery.

### Create and issue the e-invoice

```http
POST /v2/sales-invoices
```

```json
{
  "status": "issued",
  "isEInvoice": true,
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "billing@acme.nl",
    "streetAndNumber": "Keizersgracht 1",
    "postalCode": "1015 CW",
    "city": "Amsterdam",
    "country": "NL"
  },
  "lines": [
    {
      "description": "Software licence — Q2 2026",
      "quantity": 1,
      "vatRate": "21.00",
      "unitPrice": {
        "currency": "EUR",
        "value": "500.00"
      }
    }
  ],
  "emailDetails": {
    "subject": "Your invoice from Acme B.V.",
    "body": "Dear customer,\n\nWe have sent your invoice via the Peppol network. A PDF copy is attached in this email.\n\nThank you."
  }
}
```

<Callout icon="📘" theme="info">
  Including `emailDetails` is optional. When provided, Mollie sends a PDF copy by email in addition to the Peppol delivery.
</Callout>

### Track delivery

The initial response shows `status: "issuing"` while Peppol submission is in progress. Track delivery using the `eInvoiceStatus` field.

| `status`  | `eInvoiceStatus` | Meaning                             |
| :-------- | :--------------- | :---------------------------------- |
| `issuing` | `issuing`        | Peppol delivery in progress         |
| `issued`  | `issued`         | Delivered successfully              |
| `failed`  | `failed`         | Delivery failed — Mollie will retry |

Poll `GET /v2/sales-invoices/{id}` or listen for webhooks to detect when `status` moves from `issuing` to `issued` or `failed`.

If delivery fails, Mollie retries it automatically. You do not need to resubmit the invoice manually.