API Integration guide

Sending Sales Invoices with Peppol

Send sales invoices to your customers through the Peppol network directly from your integration.

Overview

Peppol enables secure, standards-based e-invoicing between organizations. This guide focuses on sending a sales invoice with Peppol. It follows a similar flow as Creating Sales Invoices, but adds the Peppol-specific requirements.

Prerequisites

• You have an access token and your administration ID. See Getting started and Authentication.
• Your administration is registered for Peppol. Follow the signup steps in the Moneybird Help Center: Aanmelden voor Peppol.
• Your customer (contact) has a Peppol identifier on file (si_identifier_type and si_identifier). For Dutch KVK this is si_identifier_type = 0106 and si_identifier = your customer’s KVK number.

Tip: You can verify a registration via Participant Lookup by entering 0106 and the KVK number as described in the signup article above.

Step-by-step

1. Ensure Peppol is enabled for your administration

Follow the steps in the Help Center article to enable Peppol in your Moneybird account: Aanmelden voor Peppol.

2. Create or update the contact with a Peppol identifier

The contact must include a valid Peppol identifier so we can deliver via the network. You can also set the contact’s preferred delivery_method to Peppol.

Create a new contact with a Peppol identifier:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "contact": {
      "company_name": "TechStart Inc.",
      "address1": "123 Business St",
      "zipcode": "1234 AB",
      "city": "Amsterdam",
      "country": "NL",
      "delivery_method": "Peppol",
      "si_identifier_type": "0106",
      "si_identifier": "12345678"
    }
  }'

Update an existing contact to add a Peppol identifier (if needed):

Code
 
curl -X PATCH "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts/{CONTACT_ID}.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "contact": {
      "delivery_method": "Peppol",
      "si_identifier_type": "0106",
      "si_identifier": "12345678"
    }
  }'

Notes:

• A contact requires a non-blank company_name, firstname, or lastname.
• country should be an ISO 3166-1 alpha-2 code (e.g., NL, DE).
• si_identifier_type accepts specific codes (e.g., 0106 for Dutch KVK). Use the appropriate code for your market.

3. Create the sales invoice (draft)

Create a draft sales invoice that references the contact:

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/sales_invoices.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "sales_invoice": {
      "contact_id": "{CONTACT_ID}",
      "reference": "INV-2025-001",
      "invoice_date": "2025-09-16",
      "due_date": "2025-10-16",
      "currency": "EUR",
      "details_attributes": [
        {
          "description": "Premium Software License",
          "price": "299.00",
          "amount": "1",
          "tax_rate_id": "{TAX_RATE_ID}",
          "ledger_account_id": "{LEDGER_ACCOUNT_ID}"
        }
      ]
    }
  }'

4. Send the invoice with Peppol

Send the draft invoice through Peppol by specifying delivery_method: Peppol in the send request:

Code
 
curl -X PATCH "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/sales_invoices/{SALES_INVOICE_ID}/send_invoice.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "sales_invoice_sending": {
      "delivery_method": "Peppol"
    }
  }'

After sending, the invoice status changes from "draft" to "open". Track status changes with Webhooks or by polling the invoice resource.

Troubleshooting

• Delivery fails with validation errors (422): Ensure the contact has a valid si_identifier_type and si_identifier, and your administration is Peppol-enabled.
• Customer not found on Peppol: Confirm the correct identifier (e.g., KVK for NL with type 0106) and verify registration via Participant Lookup as noted in the Aanmelden voor Peppol article.

Related

• Creating Sales Invoices
• Webhooks