# 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](/integration/getting-started) and [Authentication](/authentication).
- You know the correct `ledger_account_id` and `tax_rate_id` for your revenue. See [Ledger accounts](/api/ledger-accounts) and [Tax rates](/api/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:

```bash
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](/api/contacts#get-contact-by-customer-id). 

- An alternative method is querying by email:
```bash
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](/api/custom-fields#list-all-custom-fields) 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.
```bash
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.

```bash
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](/api/external-sales-invoices#add-attachment-to-external-sales-invoice) 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.

```bash
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](/webhooks/getting-started) for automatic reconciliation
2. Set up **[webhooks](/webhooks/getting-started)** for real-time updates