Sales Invoices API guide

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

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

POST /v2/sales-invoices

{
  "status": "draft",
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "[email protected]",
    "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.

PATCH /v2/sales-invoices/{id}

{
  "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 and Mandates 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.

POST /v2/sales-invoices

{
  "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": "[email protected]",
    "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.

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

POST /v2/sales-invoices

{
  "status": "paid",
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "[email protected]",
    "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.
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

POST /v2/sales-invoices

{
  "status": "issued",
  "isEInvoice": true,
  "vatMode": "exclusive",
  "paymentTerm": "30 days",
  "recipientIdentifier": "customer-abc-123",
  "recipient": {
    "type": "business",
    "organizationName": "Acme B.V.",
    "vatNumber": "NL123456789B01",
    "email": "[email protected]",
    "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."
  }
}

Track delivery

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

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.