# Moneybird

Source: https://developers.swell.is/app-guides/moneybird

The Moneybird app books your paid Swell orders in Moneybird. When an order is paid, the app creates its invoice in your Moneybird administration, either a sales invoice that Moneybird numbers or an external sales invoice with the Swell order number, and registers the payment so the invoice shows as paid. When a payment is refunded, the app books the refund as a credit invoice.

Each invoice line gets the Moneybird sales tax rate with the percentage Swell charged. Customers become Moneybird contacts with their first order, and later changes to their account are sent to the contact. Each order shows its invoice number, its status in Moneybird and a link to the invoice on its **Moneybird** tab.

## How it works

| When | What the app does |
| --- | --- |
| An order is paid in full | Finds or creates the customer's Moneybird contact, creates the invoice, marks it as sent or emails it as New sales invoices says, and registers the payment if Register payments is on. Draft orders and orders with a total of 0 aren't sent. |
| A payment of an order that's in Moneybird is refunded | Creates a credit invoice for the refunded amount, or a negative external sales invoice, and registers the refund payment if Register payments is on. Needs Send refunds on. |
| A customer's name, email, phone, address or VAT number changes | Updates the customer's Moneybird contact, if they have one and Update contacts is on. |
| You choose Send to Moneybird on an order, or on up to 10 selected orders | Sends the paid orders that aren't in Moneybird yet, and finishes the ones that stopped halfway. |
| You run Send existing orders | Sends the paid orders placed in the last 7, 30 or 90 days, one at a time, in the background. |
| You run Test connection | Checks the API token and the administration, and lists your administrations, sales tax rates and financial accounts with their IDs. |

Nothing is sent to Moneybird while **Enabled** is off.

## Before you begin

- A Moneybird administration on a plan that allows the invoices you create. When the plan doesn't allow a document, Moneybird refuses it and the order shows the error.
- A personal API token. Moneybird lets only the owner of an administration create one. The token needs access to sales invoices and settings, and it can't be read-only, because the app creates contacts, invoices and payments. Moneybird doesn't let you change a token's access after it's created.
- An active sales tax rate in Moneybird for each tax percentage your store charges, such as 21% and 9%. The app matches each line to a rate by its percentage. Lines without a match get the default tax rate you set in the app, or the administration's default tax rate.
- Optionally, the Moneybird workflow and document style for sales invoices, a revenue ledger account, and the financial account your payments arrive in. To register payments as payments without proof, turn that option on in Moneybird first.
- Orders in any currency. Invoices and payments use the order's currency. For an order in another currency than the administration's, the payment also gets Moneybird's amount in the administration's currency.

## Set up

Install Moneybird from the Swell App Store, and set it up in your test environment before the live one.

**1. Create an API token**

In Moneybird, signed in as the administration's owner, go to **Settings > External applications and AI connections > New API token**. Give the token access to sales invoices and settings, leave it read and write, and copy it.

For the test environment, you can use a Moneybird sandbox administration, which Moneybird offers for testing integrations. Create one at `moneybird.com/administrations/sandboxes/new`. Its invoices carry a watermark.

**2. Enter the token**

In Swell, go to **Apps > Moneybird > Settings**, paste the token into **API token** and click **Save settings**.

**3. Test the connection**

Choose **Actions > Test connection**. Without an **Administration ID**, the message lists the administrations the token can use, with their IDs, such as `Found administration Alder & Co. (ID 421356890027183401). Enter its ID in Administration ID and save, then test again.` Test connection doesn't fill in any setting. The ID is also the number after `moneybird.com/` in your Moneybird address.

Enter the ID in **Administration ID**, click **Save settings** and choose **Test connection** again. The message names the administration and its currency, such as `Connected to Alder & Co. (EUR).`, and lists up to 6 active sales tax rates and 6 financial accounts with their IDs. Copy the IDs you need for the next steps.

**4. Choose how orders are booked**

On the **Invoices** tab, choose **Book orders as**. For sales invoices, choose what **New sales invoices** does, and optionally enter a **Workflow ID** from **Settings > Workflows** in Moneybird and a **Document style ID** from **Settings > Document styles**. Optionally enter a **Default tax rate ID** from the Test connection message and a **Revenue ledger account ID**.

**5. Choose payments, refunds and contacts**

On the **Payments and refunds** tab, keep **Register payments** on to mark invoices as paid, and optionally enter the **Financial account ID** of the Moneybird account your payments arrive in. Turn on **Payments without proof** only if it's turned on in Moneybird. Keep **Send refunds** on to book refunds.

On the **Contacts** tab, choose whether **Update contacts** sends customer changes to Moneybird. Click **Save settings**.

**6. Place a test order**

Place and pay a test order. Open the order's **Moneybird** tab: **Invoice** shows the Moneybird invoice number, **Status in Moneybird** shows `Paid`, and **Open in Moneybird** links to the invoice. Check the lines, the tax rates and the total in Moneybird. To test a credit invoice, refund part of the payment in Swell.

The test environment creates real contacts, invoices and payments in the administration its settings name, and a sent sales invoice takes the next number in that administration. With **Email to the customer**, Moneybird also emails the invoice to the test customer. Use a sandbox or a separate administration for the test environment.

**7. Go live**

Settings are saved separately for each environment. In the live environment, repeat steps 2 to 5 with your live administration. If the token can't use it, Test connection says so. Create a token for it as in step 1.

Keep the test environment on its own administration. Before it creates a sales invoice, the app looks in Moneybird for one with the reference `Order <number>`, and a test order and a live order can have the same number. A test order would then use the live invoice, or the other way round.

To send orders paid before you installed the app, choose **Actions > Send existing orders**.

## Using Moneybird

### Sales invoices and external sales invoices

**Book orders as** decides what each order becomes in Moneybird:

- **Sales invoices** creates a Moneybird sales invoice with the reference `Order 100238`, dated on the order date, in the order's currency, with the **Workflow ID** and **Document style ID** you set, or your defaults. Moneybird gives it a number and can email it.
- **External sales invoices** creates an external sales invoice that records the order with the order number as its reference, such as `100238`, and `Swell` as its source. Moneybird doesn't number it, and **New sales invoices**, **Workflow ID** and **Document style ID** don't apply.

Both have the same lines:

- One line per item, named after the product and its variant, such as `Linen Shirt – Large`, with the quantity and the unit price after the item's discounts.
- One line for shipping, named after the shipping service, such as `Shipping – Express`, with the price after the shipping discount.

Prices include tax when the order's item prices include tax, and shipping priced on the other basis is converted with its tax. Gift cards and account credit used to pay the order are payments in Swell, not invoice lines.

New sales invoices are drafts in Moneybird. **New sales invoices** decides what happens next:

- **Mark as sent, without emailing** gives the invoice its number, and nothing is emailed. This is the default.
- **Email to the customer** gives the invoice its number, and Moneybird emails it to the contact's invoice email address, with your workflow's email text.
- **Leave as draft** keeps the draft. It has no number, isn't booked until you send it in Moneybird, and its payment isn't registered. The app doesn't check Moneybird for drafts you send there, so register the payment in Moneybird.

An invoice keeps the type it was created as when you change **Book orders as** later, and its refunds use the same type.

### Invoice numbers

Sales invoices get their number from Moneybird when they're marked as sent or emailed. The number shows in **Invoice** on the order's **Moneybird** tab and in the **Moneybird** column of the order list. Drafts have no number, so **Invoice** stays empty.

External sales invoices aren't numbered by Moneybird. **Invoice** shows their reference, the order number.

Before it creates a sales invoice, the app looks in Moneybird for a sales invoice with the reference `Order <number>`, and uses it if there is one. A sales invoice you or another integration created with that reference is used for the order instead of a new one.

### Contacts

Each order's invoice goes to the customer's Moneybird contact. The app finds the contact whose customer ID is the Swell customer ID. If there's none, it creates one with:

- The customer's first and last name, and the company of the billing address as the company name. Without a name or company, the customer's full name or email becomes the company name.
- The order's billing address, or the customer's saved one. When neither has a street or city, the shipping address.
- The customer's email as the invoice email, with delivery by email, the phone number, and the VAT number of the customer or the billing address.

Moneybird checks that an email's domain can receive mail. When it refuses the email, the contact is created without it, with manual delivery, and the order's **Note** says so. The customer's **Moneybird** tab links to the contact in **Moneybird contact**.

An existing contact isn't changed when an order is sent. A contact you created in Moneybird by hand is used only if its customer ID is the Swell customer ID, so the app otherwise creates a second contact for that customer.

With **Update contacts** on, a change to a customer's name, email, phone, billing or shipping address or VAT number is sent to their Moneybird contact. The Swell values replace the ones in Moneybird, including the invoice email and delivery by email. Fields that are empty in Swell aren't cleared in Moneybird. When the name changes, the app renames the contact person with the old name, so the contact doesn't get a new person for each name.

Customers without an order in Moneybird have no contact there, so changes to them aren't sent. Their contact is created with their first order that's sent, whether it's paid, sent with **Send to Moneybird** or sent with **Send existing orders**.

### Tax rates and ledger accounts

The app uses the tax Swell charged on each line. It works out the line's tax percentage and gives the line the active Moneybird sales tax rate with that percentage:

- A rate for the billing country comes first, or for the shipping country when the order has no billing country.
- Then a rate without a country.
- Then any rate with that percentage. When several rates share a percentage, such as `0%`, the first one Moneybird lists is used.
- When no rate has the percentage, the line gets the **Default tax rate ID**, or the administration's default tax rate when that's empty. The order's **Note** names the percentage, such as `No Moneybird sales tax rate of 7%: used the administration's default tax rate.`

Moneybird calculates the tax per line, so with prices that exclude tax its total can differ from Swell's by a cent. The order's **Note** then says so, such as `The Moneybird total 121.01 differs from the Swell total 121.00.`

With a **Revenue ledger account ID**, every line, including credit invoice lines, is booked to that ledger account. Without one, Moneybird uses its default.

### Payments

With **Register payments** on, the app registers a payment on each invoice once it's numbered, so it shows as paid. The payment is for the unpaid total Moneybird calculated, in the invoice's currency, with the transaction reference `Swell order 100238`. It's dated on the day the app sends the paid order, or on the order date for orders sent with **Send to Moneybird** or **Send existing orders**. For an order in another currency, it also has Moneybird's amount in the administration's currency. **Payment registered** on the order shows when the app registered it.

With a **Financial account ID**, the payment is registered on that Moneybird account, such as your payment provider's. With **Payments without proof** on, payments are registered as payments without proof. Moneybird accepts these only when payments without proof are turned on in the administration, under **Instellingen > Facturen en offertes > Betalingen zonder bewijs** in Moneybird's Dutch interface. Moneybird replaces a payment without proof when you link a bank transaction of the same amount.

Drafts get no payment. With **Register payments** off, invoices stay open in Moneybird. To register the payment of an order sent while it was off, turn it on, click **Save settings**, and choose **Send to Moneybird** on the order. If the invoice was paid in Moneybird in the meantime, no second payment is registered.

### Refunds as credit invoices

With **Send refunds** on, each successful refund of an order that's in Moneybird is booked once:

- For a sales invoice, as a credit invoice with the reference `Refund 100015 of order 100238`. **New sales invoices**, the workflow and the document style apply to it as they do to invoices, so with **Email to the customer** Moneybird emails it.
- For an external sales invoice, as a negative external sales invoice with the reference `100238-R100015`.

The credit invoice is dated on the refund. Its lines are the refunded share of the order, one per tax percentage, such as `Refund of order 100238 (21% tax)`, so the tax is reversed in proportion. The percentage is left out when the order has one tax percentage. With **Register payments** on, a numbered credit invoice gets a negative payment for its total. A refund is never more than the part of the order that isn't refunded in Moneybird yet.

The credit invoice isn't linked to the order's invoice in Moneybird. Its reference names the order. On the order, **Refunded in Moneybird** shows the total, and **Credit invoices** lists each one, such as `Refund 100015: credit invoice 2026-0043 (−15.00 EUR)`. A credit invoice left as a draft is listed as `draft`.

Refunds of orders that aren't in Moneybird are ignored. Refunds made before the order was sent, or while **Send refunds** or **Enabled** was off, aren't sent later, and no action sends them. Book those in Moneybird by hand. Refunds of payments that don't belong to an order, such as subscription invoice payments, aren't sent.

### The order's Moneybird tab

Each order has a **Moneybird** tab with:

- **Invoice**: the Moneybird invoice number, or the reference of an external sales invoice.
- **Status in Moneybird**: the invoice's status when the app last changed it, such as `Draft`, `Open` or `Paid`. Changes you make in Moneybird don't show here.
- **Open in Moneybird**: a link to the invoice in Moneybird.
- **Payment registered** and **Refunded in Moneybird**.
- **Credit invoices**, **Note** and **Error**, when they have a value. **Note** lists tax percentages without a Moneybird rate, a Moneybird total that differs from Swell's, and an email Moneybird refused. **Error** says why the last step failed, such as `Couldn't register the payment: …`, and is cleared by the next successful step.

### Sending orders with Send to Moneybird

To send an order now, open it and choose **Actions > Send to Moneybird**. To send several, select up to 10 orders in the order list and choose **Send to Moneybird**. The action uses the current settings and works on paid orders that aren't in Moneybird yet, and on orders that stopped halfway, such as an invoice that wasn't numbered or a payment that wasn't registered.

The dashboard waits for the result, such as `Sent 2 orders to Moneybird: 100238 (created, marked as sent, payment registered) · 100239 (created, marked as sent, payment registered).` Orders it doesn't send are listed after `Skipped:` or `Failed:` with the reason. When nothing was sent, the message shows as an error. With more than 10 orders selected, it shows `Select up to 10 orders.` and sends nothing.

**Send to Moneybird** doesn't send refunds. When Moneybird rejects the token or the plan, or can't be reached, it stops at that order.

### Sending existing orders

To send orders placed before you installed the app, go to **Apps > Moneybird** and choose **Actions > Send existing orders**. Choose **Orders placed in the last** `7 days`, `30 days` or `90 days`, and click **Send orders**.

- The run sends each paid order placed in that period that isn't in Moneybird yet, with the current settings, and registers its payment as the settings say. Orders already in Moneybird are skipped, and orders that stopped halfway are finished. Refunds made before aren't sent.
- It runs in the background, 10 orders per step, one order at a time. The action shows **Running** while it works, and the run is listed on the app's **Workflows** tab.
- Moneybird allows about 30 orders every 5 minutes. When Moneybird's limit is reached, the step waits and tries again, up to 6 times, from 1 minute and doubling.
- The settings are read before each order. When you turn off **Enabled**, or remove the API token or Administration ID, the run stops before the next order.
- When it finishes, the dashboard shows `"Send existing orders" finished`, and the logs show the totals, such as `sent 12, finished 0, already in Moneybird 3, skipped 0, failed 1`.

### In the dashboard

| Where | What it's for |
| --- | --- |
| Apps > Moneybird > Settings | The API token, Administration ID and Enabled, and the Invoices, Payments and refunds and Contacts tabs. |
| Apps > Moneybird > Actions | Test connection and Send existing orders. Save the settings first: the actions are unavailable while there are unsaved changes. |
| Apps > Moneybird > Workflows | The runs of Send existing orders. |
| An order's Moneybird tab | The invoice number, status in Moneybird, link, payment, refunds, credit invoices, note and error. |
| An order's Actions menu | Send to Moneybird. |
| The order list | The Moneybird column with the invoice number, and Send to Moneybird for up to 10 selected orders. |
| A customer's Moneybird tab | Moneybird contact, the link to the customer's contact in Moneybird. |
| Developer > Console > Logs | Each order, refund and contact update the app sends, the import's totals, and each error. |

## Settings

Settings are in **Apps > Moneybird > Settings** and are saved separately for each environment.

**API token**, **Administration ID** and **Enabled** are at the top. The other settings are on the **Invoices**, **Payments and refunds** and **Contacts** tabs.

| Setting | Description | Default |
| --- | --- | --- |
| API token | A personal API token from Settings > External applications and AI connections in Moneybird, with access to sales invoices and settings. Required. Masked on the settings page. | None |
| Administration ID | The ID of the Moneybird administration, the number after moneybird.com/ in your Moneybird address. Test connection lists the administrations the token can use. Nothing is sent while it's empty. | None |
| Enabled | Turns off everything the app sends to Moneybird, without uninstalling it. Test connection still works while it's off. | On |
| Invoices > Book orders as | Sales invoices, which Moneybird numbers and can email, or External sales invoices, which record the order with the order number as reference. | Sales invoices |
| Invoices > New sales invoices | Mark as sent, without emailing, Email to the customer, or Leave as draft. Applies to sales invoices and credit invoices. Drafts have no number and get no payment. Shown for sales invoices only. | Mark as sent, without emailing |
| Invoices > Workflow ID | The Moneybird workflow for sales invoices and credit invoices, from Settings > Workflows in Moneybird. Empty uses your default invoice workflow. Shown for sales invoices only. | None |
| Invoices > Document style ID | The Moneybird document style for sales invoices and credit invoices, from Settings > Document styles in Moneybird. Empty uses your default style. Shown for sales invoices only. | None |
| Invoices > Default tax rate ID | The Moneybird tax rate for lines whose percentage has no active sales tax rate. Test connection lists the IDs. Empty uses the administration's default tax rate. | None |
| Invoices > Revenue ledger account ID | The ledger account every line is booked to. Empty uses Moneybird's default. | None |
| Payments and refunds > Register payments | Registers a payment on each numbered invoice and credit invoice, so it shows as paid. | On |
| Payments and refunds > Financial account ID | The Moneybird account the payments arrive in, such as your payment provider's. Test connection lists the IDs. Shown while Register payments is on. | None |
| Payments and refunds > Payments without proof | Registers payments as payments without proof. Turn on payments without proof in Moneybird first. Shown while Register payments is on. | Off |
| Payments and refunds > Send refunds | Books each Swell refund of an order in Moneybird as a credit invoice, or a negative external sales invoice, for the refunded amount. | On |
| Contacts > Update contacts | Sends changes to a customer's name, email, phone, address or VAT number to their Moneybird contact. Contacts are created with the customer's first order either way. | On |

## Limitations

- Only paid orders are sent. Unpaid orders, draft orders and orders with a total of 0 aren't. A refund can make an order count as unpaid in Swell, so an order refunded before it was sent is skipped as `order is not paid`.
- Changes to an order after it was sent, such as edited items or a cancellation, don't change its invoice. Refund the order to book a credit invoice.
- The app doesn't read invoices back from Moneybird. Drafts you send there, payments you register there and other changes don't show in Swell.
- Tax rates are matched by percentage only. When several Moneybird rates share a percentage, such as `0%`, the first match is used, which may not be the rate your tax return needs.
- Moneybird calculates tax per line, so its total can differ from Swell's by a cent. The payment registered is Moneybird's total.
- Contacts are matched by Swell customer ID only, and existing contacts aren't updated when an order is sent. With **Update contacts** on, changes you make to a linked contact in Moneybird are overwritten at the customer's next change in Swell.
- Credit invoices are for an amount, not for items, and aren't linked to the order's invoice in Moneybird. Refunds are sent only when they happen, for orders that are in Moneybird.
- Moneybird allows 150 API requests every 5 minutes. Sending an order takes up to 9 requests, so large imports take a while.
- **Send to Moneybird** works on up to 10 orders at a time.
- Each environment uses the administration in its settings. Moneybird has no test mode, so the test environment creates real documents unless it uses a sandbox administration.
- If Moneybird can't be reached, limits the app's requests or has a server error, Swell runs the function again later, at growing intervals. If it keeps failing for about 4 days, Swell turns off the function and emails the store's admins. Reinstall the app to turn it back on. Other errors are saved on the order, or logged for contact updates, and aren't retried.
- When creating an external sales invoice or a credit invoice fails because Moneybird couldn't be reached or had a server error, it isn't retried, because Moneybird may have created it and the app can't look it up.
- **Test connection** lists up to 6 sales tax rates and 6 financial accounts.

## Troubleshooting

Errors from sending an order or refund show in **Error** on the order's **Moneybird** tab. **Test connection** and **Send to Moneybird** show their messages in the dashboard, and **Send existing orders** shows its message when it fails. The app also logs each order, refund and contact update it sends, and each error. In the Swell dashboard, the logs are under **Developer > Console > Logs**.

### Test connection fails

`Add the API token and save the settings first.` means no token is saved. `The API token has no access to any Moneybird administration.` means the token belongs to a user without an administration. `The API token has no access to administration …` means the **Administration ID** isn't one the token can use. The message lists the ones it can use. Enter one of their IDs, click **Save settings** and test again.

### "Moneybird rejected the API token (…)"

The token is wrong or was deleted in Moneybird. Create a new one under **Settings > External applications and AI connections > New API token** in Moneybird, paste it in **API token**, click **Save settings** and run **Test connection**. Then choose **Send to Moneybird** on the orders that weren't sent.

### "The API token isn't allowed to do this (…)"

The token lacks access to sales invoices or settings, or is read-only. Moneybird doesn't let you change a token's access, so create a new token with access to sales invoices and settings, and enter it in the app settings.

### "Your Moneybird plan doesn't allow this (…)"

The administration's plan doesn't allow the document, for example because of an invoice limit. Check your subscription in Moneybird, then choose **Send to Moneybird** on the order.

### "Moneybird didn't find the administration (…)"

Check the **Administration ID**. Clear it, click **Save settings** and run **Test connection** to list the administrations the token can use.

### "Moneybird refused it: …"

Moneybird refused the values the app sent, and the message ends with Moneybird's reason. Check the IDs in the settings: **Workflow ID**, **Document style ID**, **Default tax rate ID**, **Revenue ledger account ID** and **Financial account ID**. If the refused step is the payment and **Payments without proof** is on, check that payments without proof are turned on in Moneybird. Correct the cause, then choose **Send to Moneybird** on the order.

### "Moneybird is not available right now (…), try again later."

Moneybird couldn't be reached, limited the app's requests or had a server error. Swell runs the order or refund again later. For an action, try again in a few minutes.

### "Couldn't create the invoice: …" on an external sales invoice

If the reason is that Moneybird wasn't available, Moneybird may have created the invoice anyway. Look for the order number among your external sales invoices in Moneybird before you choose **Send to Moneybird**, which would create another.

### Paid orders don't reach Moneybird

Check that **Enabled** is on and that **API token** and **Administration ID** are saved. The logs show `Moneybird: missing` followed by the setting when one is empty. Draft orders and orders with a total of 0 aren't sent. Orders paid before you installed the app or while it was off aren't sent automatically. Choose **Send to Moneybird** on them, or run **Send existing orders**.

### The invoice has no number

**New sales invoices** is set to **Leave as draft**, or marking it as sent or emailing it failed, and **Error** says why. External sales invoices aren't numbered by Moneybird. **Invoice** shows their reference.

### The invoice isn't marked as paid

**Register payments** was off, the invoice is a draft, or **Error** shows `Couldn't register the payment: …`. Correct the cause, then choose **Send to Moneybird** on the order to register the payment.

### A refund wasn't booked

Check that **Send refunds** and **Enabled** were on when the refund was made, and that the order was in Moneybird by then. The logs show `the order isn't in Moneybird` or `order already fully refunded in Moneybird` when the refund was skipped. A refund whose credit invoice failed shows the reason in **Error**, such as `Refund 100015: couldn't create the credit invoice: …`. Book it in Moneybird by hand.

### "No Moneybird sales tax rate of …"

No active Moneybird sales tax rate has that percentage, so the line got the default tax rate. Add the rate in Moneybird, or set **Default tax rate ID**, for future orders, and correct the invoice in Moneybird.

### "The Moneybird total … differs from the Swell total …"

Moneybird rounds tax per line. The payment registered is Moneybird's total. Check the invoice in Moneybird if the difference matters.

### "Moneybird refused the customer's email …"

The email's domain can't receive mail, so the contact was created without an invoice email. Add the right email to the contact in Moneybird.

### A customer's contact isn't updated

Check that **Update contacts** is on. Only customers with a contact in Moneybird are updated, and only changes to the name, email, phone, addresses or VAT number are sent. The logs show `couldn't update the contact` with the reason.

### "Nothing sent to Moneybird. …"

**Send to Moneybird** sent none of the orders. Each one is listed with the reason: `already in Moneybird`, `order is not paid`, `order is a draft`, `order total is 0`, or the error for a failed order.

### "The Moneybird app is turned off in its settings." or "Add the … in Apps → Moneybird first."

Turn on **Enabled**, or fill in **API token** and **Administration ID**, and click **Save settings**.

### Send to Moneybird stops before it finishes

The action runs while the dashboard waits, within Swell's time limit for functions, and several orders can take longer. Each finished step is saved on its order, so choose **Send to Moneybird** again on the orders without an invoice number, or use **Send existing orders**.

### "Import not started: …"

**Send existing orders** didn't send anything: `Import not started: the Moneybird app is turned off in its settings.` when **Enabled** is off, or `Import not started: add the … in Apps → Moneybird.` when the API token or Administration ID is empty. Correct the setting, click **Save settings**, and run it again.

### "Import stopped: …"

**Enabled** was turned off, or the API token or Administration ID was removed, while the import ran. The message gives the totals until then. Correct the setting and run the import again. Orders already sent are skipped.

### "Import failed on page …"

Moneybird refused the token, the plan or the request for the tax rates, and the message gives the reason and the totals until then. When Moneybird stays unavailable after the retries, the run fails with Moneybird's error instead. Correct the cause and run the import again.

### "Import finished, but Moneybird refused all … orders it was sent"

Every order the import tried failed. The reason is in **Error** on each order's **Moneybird** tab.

## Uninstalling

Uninstalling the app stops sending orders, refunds and contact changes to Moneybird. It removes the app's functions, including **Send existing orders**, and its settings with the API token, the **Moneybird** tabs on orders and customers, the **Moneybird** column in the order list, and **Send to Moneybird**. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

The Moneybird values saved on orders and customers, such as the invoice and contact IDs, are kept and show again if you reinstall, so orders already in Moneybird aren't sent again. Invoices, credit invoices, payments and contacts stay in Moneybird.

The app isn't notified when it's uninstalled. If you no longer need the API token, revoke it in Moneybird under **Settings > External applications and AI connections**. To pause the app without uninstalling it, turn off **Enabled**.

## For developers

| Function | Runs on | What it does |
| --- | --- | --- |
| order-events | order.paid | Loads the order with account, items.product and items.variant, and runs the order sync with the payment dated on the day it runs. |
| refund-events | payment.refund.succeeded | Reads the refund from the event, or from /payments:refunds/{id} when order_id or amount is missing, loads its order and sends the credit invoice, when Send refunds is on. |
| account-events | account.updated | When $event.data has first_name, last_name, name, email, phone, billing, shipping or vat_number, updates the customer's existing contact, when Update contacts is on. |
| send-to-moneybird | The Send to Moneybird action on an order and the bulk action in the order list | Runs the order sync on up to 10 orders, with the tax rates loaded once. Returns a summary, or throws a 400 SwellError. |
| test-connection | The Test connection action | Reads the administrations, sales tax rates and financial accounts. Works while Enabled is off, and only reads. |
| import-orders | The Send existing orders action | A workflow. Reads paid orders created in the last 7, 30 or 90 days, 10 per step in id order, and runs the order sync on each. |

The app stores its values under `$app.moneybird`. On orders: `moneybird_invoice_id`, `moneybird_invoice_type`, `moneybird_invoice_number`, `moneybird_invoice_url`, `moneybird_state`, `moneybird_status`, `moneybird_paid_at`, `moneybird_refunds` (credit invoice IDs by Swell refund ID), `moneybird_refunds_done`, `moneybird_refund_total`, `moneybird_credit_invoices`, `moneybird_note` and `moneybird_error`. On accounts: `moneybird_contact_id` and `moneybird_contact_url`.

The app calls the Moneybird API v2 at `https://moneybird.com/api/v2/<administration id>/<resource>.json` with the API token as a Bearer token: `GET /administrations` (without the administration), `GET /tax_rates` with `filter=tax_rate_type:sales_invoice` and `per_page=100`, `GET /financial_accounts`, `GET /contacts/customer_id/{id}`, `GET /contacts/{id}`, `POST /contacts`, `PATCH /contacts/{id}`, `PATCH /contacts/{id}/contact_people/{id}`, `GET /sales_invoices/find_by_reference/{reference}`, `POST /sales_invoices`, `PATCH /sales_invoices/{id}/send_invoice` with `delivery_method` `Manual` or `Email`, `POST /external_sales_invoices`, and `GET /{kind}/{id}` and `POST /{kind}/{id}/payments` for both kinds. Moneybird IDs are 18-digit numbers and are kept as strings.

Each step of an order is saved on it: the invoice ID and type when it's created, the state when it's numbered, and `moneybird_paid_at` when the payment is registered. A retry, **Send to Moneybird** or the import continues from the saved state, and the payment step reads the invoice's `total_unpaid` first, so a payment isn't registered twice. Before creating a sales invoice, the app calls `find_by_reference` with `Order <number>`, so an invoice whose result wasn't saved is reused. External sales invoices and credit invoices can't be looked up that way, so a failed create of one is retried only after a 429. A credit invoice's ID is saved in `moneybird_refunds` right after it's created, and the refund is marked done in `moneybird_refunds_done` after its last step. A failed write to Swell is only logged.

Amounts are rounded to cents and sent as strings with two decimals. A line's unit price is `price` minus `discount_each`, and its tax percentage is `tax_each` divided by the net unit price, rounded to two decimals. `prices_are_incl_tax` follows `item_tax_included`, and shipping with another `shipment_tax_included` is converted with `shipment_tax`. Refund lines sum the order lines per percentage and scale them by the refunded share of `grand_total`. With prices that include tax, the rounding difference goes on the last line. A refund is capped at `grand_total` minus `moneybird_refund_total`. The payment's `price` is Moneybird's `total_unpaid`, and `price_base` its `total_unpaid_base`.

Tax rates come from the first page of 100 sales tax rates, without inactive ones. A line gets the rate within 0.1 percentage points whose `country` is the billing country, or the shipping country without one, then a rate without a country, then the first match, then `default_tax_rate_id`. Without any, `tax_rate_id` is left out and Moneybird uses its default.

In the event functions, Moneybird 429, 5xx and network errors are rethrown so Swell retries the event, unless running again could create a second external invoice or credit invoice. Other errors are logged with `console.error`, with the refused call, and saved in `moneybird_error` for orders and refunds, and the function succeeds.

The import runs one `step.do` per page, retried 6 times from 1 minute with exponential backoff. Each step reads the settings itself, so the API token stays out of the step output, and checks them again before each order. A 401, 402 or 403, or a refused tax rate request, fails the run. Other refused orders count as failed, and the run goes on. Workflow requests carry only `store.id`, so the import doesn't set `source_url` on external invoices. The event functions and **Send to Moneybird** set it to `store.admin_url` followed by `/orders/<order id>`.

## Support

Swell builds and maintains the Moneybird app. For help with the app, email support@swell.is. For questions about your Moneybird administration, invoices or tax rates, contact Moneybird.