API Integration guide

Importing External Invoices

Import invoices from external software into Moneybird for complete revenue tracking and centralized bookkeeping.

Overview

External sales invoices allow you to import invoices created in other systems (e-commerce platforms, marketplaces, accounting software) into Moneybird. This ensures all your revenue is tracked in one place for accurate financial reporting.

Prerequisites

• You have an access token and your administration ID. See Getting started and Authentication.
• You know the correct ledger_account_id and tax_rate_id for your revenue. See Ledger accounts and Tax rates.

Step-by-step

1. Create Contact

Before creating an external invoice, ensure you have a contact record. Depending on your integration, you can link Moneybird contacts to your external application in several ways:

• Sync the Moneybird contact_id back to your application after creating a contact.
• Set the external contact ID as customer_id when creating the contact in Moneybird.
• Add custom fields to contacts in Moneybird (via the UI) and store the external contact ID there.
• If your application uses unique email addresses, you can also rely on those as a reference.

If there's already a contact stored in Moneybird you can skip this step.

Create a contact:

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.",
      "firstname": "John",
      "lastname": "Smith",
      "email": "john@techstart.com",
      "customer_id": "ext_reference"
    }
  }'

2. Find existing Contact

• Depending on your integration you can retrieve the contact by customer id.

• An alternative method is querying by email:

Code
 
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts.json?query=info%40moneybird.com" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

• If your integration relies on custom fields, you can use those too. First retrieve the custom field ID and include it in your contact request. You can also obtain this ID by visiting custom fields in the UI and copying it from the URL.

Code
 
curl -X GET "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/contacts.json?contact_field={CUSTOM_FIELD_ID}&contact_value={CUSTOM_FIELD_VALUE}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

3. Create External Sales Invoice

Now create the external invoice using all necessary details. Setting the correct ledger account ID and tax rate ID from the beginning will make sure the invoice is booked correctly in your administration and matches your reporting. Setting a source_url enables you to easily visit the external sales invoice whenever that's needed.

Code
 
curl -X POST "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/external_sales_invoices.json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{
    "external_sales_invoice": {
      "contact_id": "{CONTACT_ID}",
      "reference": "EXT-INV-2025-001",
      "date": "2025-09-16",
      "due_date": "2025-10-16",
      "currency": "EUR",
      "source": "ecommerce_platform",
      "source_url": "https://shop.example.com/orders/12345",
      "details_attributes": [
        {
          "description": "Premium Software License",
          "price": "299.00",
          "amount": "1",
          "tax_rate_id": "{TAX_RATE_ID}",
          "ledger_account_id": "{LEDGER_ACCOUNT_ID}"
        },
        {
          "description": "Setup Fee",
          "price": "50.00",
          "amount": "1",
          "tax_rate_id": "{TAX_RATE_ID}",
          "ledger_account_id": "{LEDGER_ACCOUNT_ID}"
        }
      ]
    }
  }'

4. Upload Attachment

It's recommended to also upload and attach the original (PDF) invoice from the external software. This document will be displayed in Moneybird as the source document, ensuring everything is stored and accessible in one place. Upload the document as binary data.

Code
 
curl -X POST \
  "https://moneybird.com/api/v2/{ADMINISTRATION_ID}/external_sales_invoices/{EXTERNAL_SALES_INVOICE_ID}/attachment.json" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -F "file=@invoice_document.pdf;type=application/pdf"

After importing external invoices, you may want to:

1. Track payment status with webhooks for automatic reconciliation
2. Set up webhooks for real-time updates