Extending the plugin

The plugin exposes several hooks that allow you to add/modify functionality through WordPress filters. This page lists the available filters and provides example code for some common use cases.

List of available filter hooks

woocommerce_moneybird_contact_details

Filter array containing the contact details of a given order. These contact details are used to search for a match in the Moneybird contacts, or to create a new Moneybird contact.
```
Plugin versions:    3.5.0 and newer
Filtered object:    Array containing the contact details
Arguments:          corresponding WC_Order
```

woocommerce_moneybird_credit_invoice

Filter the credit invoice object before it is pushed to Moneybird.

Plugin versions:    3.0.0 and newer
Filtered object:    Array containing the complete credit invoice object
Arguments:          corresponding refund (WC_Order instance) and original order (WC_Order instance)

woocommerce_moneybird_custom_field_value

Filter the value of a custom field.

Plugin versions:    3.20.0 and newer
Filtered object:    Value of the custom field for the corresponding WC_Order.
Arguments:          Custom field key (string); order id (int).

woocommerce_moneybird_custom_fields

Filter the array of available custom field keys.

Plugin versions:    3.20.0 and newer
Filtered object:    Array containing the available custom field keys.
Arguments:          None

woocommerce_moneybird_invoice

Filter the sales invoice object before it is pushed to Moneybird.

Plugin versions:    2.1.2 and newer
Filtered object:    Array containing the complete invoice object
Arguments:          corresponding WC_Order

woocommerce_moneybird_invoice_item

Filter item details that are put on the Moneybird invoice. Return an empty array to skip the item.

Plugin versions:    2.5 and newer
Filtered object:    Array of invoice lines (see source for details)
Arguments:          corresponding WC_Order_Item and WC_Order

woocommerce_moneybird_invoice_shipping

Filter invoice lines corresponding to shipping costs.

Plugin versions:    2.5 and newer
Filtered object:    Array of invoice lines (see source for details)
Arguments:          corresponding WC_Order

woocommerce_moneybird_invoice_fees

Filter invoice lines corresponding to ordering fees.

Plugin versions:    2.5 and newer
Filtered object:    Array of invoice lines (see source for details)
Arguments:          corresponding WC_Order

woocommerce_moneybird_invoice_gift_cards

Filter invoice lines corresponding to gift card redemptions.

Plugin versions:    3.49 and newer
Filtered object:    Array of invoice lines (see source for details)
Arguments:          corresponding WC_Order

woocommerce_moneybird_invoice_send_parameters

Filter the parameters of the Moneybird API request to send an invoice.

Plugin versions:    3.48.0 and newer
Filtered object:    Array containing the API request parameters
Arguments:          corresponding WC_Order and Moneybird invoice object

woocommerce_moneybird_invoice_sequence_id

Filter the {id} part of the invoice id. Default format: {year}-{id}.

Plugin versions:    2.1.1 and newer
Filtered object:    incremental part of the invoice id
Arguments:          corresponding WC_Order

woocommerce_moneybird_is_order_paid

Filter the payment status of an order. By default, an order is considered paid if the status is “processing” or “complete”, and a payment method has been associated with the order.
```
Plugin versions:    2.5 and newer
Filtered object:    Boolean indicating the payment status
Arguments:          corresponding WC_Order
```
woocommerce_moneybird_new_contact

Filter array containing the fields for a new Moneybird contact. Use this filter to add any additional fields, such as tax_number.
```
Plugin versions:    2.1.1 and newer
Filtered object:    Array containing the contact details
Arguments:          corresponding WC_Order
```
woocommerce_moneybird_process_order

Filter a boolean indicating whether the specified order should be processed. Returning false allows one to suppress Moneybird contact and invoice generation.
```
Plugin versions:    3.34.0 and newer
Filtered object:    Boolean indicating whether order should be processed (default: true).
Arguments:          corresponding WC_Order
```

woocommerce_moneybird_reference

Filter the value of the reference field on the invoice.

Plugin versions:    2.1.1 and newer
Filtered object:    Value of the invoice reference string, for example "order #{{order_id}}"
Arguments:          corresponding WC_Order

woocommerce_moneybird_register_payment

Filter a boolean indicating whether or not to register a payment in Moneybird. Use this filter to overwrite the payment registration setting for individual orders.
```
Plugin versions:    2.1.2 and newer
Filtered object:    Boolean indicating if the order payment should be registered in Moneybird
Arguments:          corresponding WC_Order
```
woocommerce_moneybird_revenue_ledger_accounts

Filter the array of available Moneybird revenue ledger accounts. The keys of the associative array start with ’s’, followed by the id of the ledger account. The values contain the ledger names.
```
Plugin versions:    3.16.0 and newer
Filtered object:    Associative array containing the available Moneybird ledger accounts.
Arguments:          Array in format s{id} => {ledger_name}.
```
woocommerce_moneybird_payment_amount

Filter the payment amount. The default payment amount is equal to the open balance of the invoice (to prevent rounding errors).
```
Plugin versions:    2.7 and newer
Filtered object:    Float: payment amount in the store's default currency
Arguments:          corresponding WC_Order
```

woocommerce_moneybird_sendmode

Filter the invoice sending mode.

Plugin versions:    3.3.0 and newer
Filtered object:    String with possible values: 'draft', 'default', 'Manual', 'Email' or 'Post'.
Arguments:          corresponding WC_Order and Invoice object.

List of available action hooks

woocommerce_moneybird_after_invoice_generate

This action is executed after a Moneybird invoice has been generated.
```
Plugin versions:    3.44.0 and newer
Arguments:          (1) WC_Order instance, (2) Moneybird invoice object
```
woocommerce_moneybird_generate_invoice_error

This action is executed if an error occurs during invoice generation. It can be used for example to send a notification to the admin.
```
Plugin versions:    3.1.3 and newer
Arguments:          (1) WC_Order instance, (2) description of the error
```

Access invoice from front-end

If you want to provide customers with a link to their invoice(s) you can use the following code to access the invoice linked to a WooCommerce order:

$moneybird = WCMB(); // This loads the registered WC_MoneyBird2 instance
$invoice = $moneybird->get_invoice_from_order_id($order_id);
if ($invoice) {
    var_dump($invoice); // Replace this with code to output info about the invoice
}

Add VAT number to Moneybird contacts

Support for the EU VAT numbers plugin is built-in since v2.5.9. The plugin checks the following order meta fields for a VAT number: _vat_number, vat_number, _billing_vat_number. If one of these fields contains a VAT number, it is automatically passed to Moneybird. Almost all EU VAT plugins store the VAT number in one of the mentioned fields, so it should work out-of-the-box. However, some custom code might be required to pass VAT numbers to Moneybird if you use another plugin to collect the VAT number.

You can add a piece of code to functions.php such that the VAT numbers of customers get passed on to Moneybird. Modify the code below to read the VAT number from the correct location (depends on the plugin used for collecting the VAT number). It is also possible the pass the Chamber of Commerce registration (“KvK nummer” in Dutch) to Moneybird (see the commented line in the example code).

function filter_woocommerce_moneybird_new_contact($contact, $order) {
    // Add VAT number from "EU VAT Number" plugin to Moneybird contact
    $order_id = is_callable(array($order, 'get_id')) ? $order->get_id() : $order->id;
    $vat_number = get_post_meta($order_id, '_vat_number', true); // Modify to read the correct field
    if ($vat_number) {
        $contact['tax_number'] = $vat_number;
    }
    // $contact['chamber_of_commerce'] = 'FILL THIS FIELD IF NEEDED';

    return $contact;
}

add_filter('woocommerce_moneybird_new_contact', 'filter_woocommerce_moneybird_new_contact', 10, 2);

Example: order-dependent invoice workflow

Edit and paste the following code snippet in functions.php to make the workflow of the invoice dependent on the properties of the WooCommerce order. For example, we can use a different workflow for orders in the German language:

// The following filter modifies the invoice workflow based on the WooCommerce order.
// $order contains the WC_Order instance corresponding to the order for which the invoice is being generated.

function filter_woocommerce_moneybird_modify_workflow($invoice, $order) {
    // Use the $order object here to look up the required information
    $order_id = is_callable(array($order, 'get_id')) ? $order->get_id() : $order->id;
    $language = get_post_meta($order_id, 'wpml_language', true);

    if ($language == 'de') {
        // Note: the workflow id can be extracted from the url when editing it in Moneybird.
        $invoice['workflow_id'] = '136261670020318887';
    }

    return $invoice;
}

add_filter('woocommerce_moneybird_invoice', 'filter_woocommerce_moneybird_modify_workflow', 10, 2);

Example: ignore non-virtual products when generating invoices

The code snippet below provides an example of how to filter order items when generating an invoice.

function mb_invoice_item_filter($item, $wc_order_item, $wc_order) {
    // Ignore non-virtual products when generating invoices

    $product = apply_filters('woocommerce_order_item_product', $wc_order->get_product_from_item($wc_order_item), $wc_order_item);
    if (!$product->is_virtual()) {
        $item = array();
    }

    return $item;
}
add_filter('woocommerce_moneybird_invoice_item', 'mb_invoice_item_filter', 10, 3);

Example: add Subscription properties as custom fields

If you use WooCommerce Subscriptions, you might want to make certain properties of subscriptions available as custom fields, so they can be mapped to custom invoice/contact fields (“Extra Velden”) in Moneybird. The following example code illustrates how this can be achieved.

function insert_subscription_custom_fields($custom_fields) {
    // Add user-defined custom field keys to the list of available custom fields.
    $custom_fields[] = 'subscription_start_date';
    return $custom_fields;
}

add_filter('woocommerce_moneybird_custom_fields', 'insert_subscription_custom_fields', 10, 1);

function resolve_subscription_custom_field_values($val, $key, $order_id) {
    // Resolve the value of all user-defined custom fields (as specified in `insert_subscription_custom_fields`).
    if (!in_array($key, array('subscription_start_date'))) {
        // We don't have to resolve this custom field
        return $val;
    }

    // Get subscriptions associated with the order
    $subscriptions = wcs_get_subscriptions_for_order($order_id);
    if (!$subscriptions) {
        $subscriptions = wcs_get_subscriptions_for_renewal_order($order_id);
    }

    if ($subscriptions) {
        if ($key == 'subscription_start_date') {
            foreach ($subscriptions as $subscription) {
                $start_date = $subscription->get_time('date_created');
                if ($start_date) {
                    $val = date('d-m-Y', $start_date);
                    break;
                }
            }
        }
    }
    return $val;
}

add_filter('woocommerce_moneybird_custom_field_value', 'resolve_subscription_custom_field_values', 10, 3);

Example: change ledger account based on country

Use the following example code to change the Moneybird revenue ledger account (omzetcategorie) for all invoice lines if the country of the buyer is not NL.

function filter_woocommerce_moneybird_modify_ledger_account($invoice, $order) {
    // Use the $order object here to look up the required information
    if (strtolower($order->get_billing_country()) != 'nl') {
        // Note: the ledger account id can be extracted from the url when editing it in Moneybird.
        for ($i=0; $i<count($invoice['details_attributes']); $i++) {
            $invoice['details_attributes'][$i]['ledger_account_id'] = '123456789'; # TODO: use correct id here
        }
    }

    return $invoice;
}

add_filter('woocommerce_moneybird_invoice', 'filter_woocommerce_moneybird_modify_ledger_account', 10, 2);

Example: modify contact details

The following example code replaces the default values of contact fields with order meta field values. Additionally, you can fill contact fields that are not filled by default. In the example, the “T.a.v. facturen” field is filled, corresponding to the send_invoices_to_attention field in the Moneybird API. Refer to the Moneybird Contacts API documentation for a full overview of the available fields.

function wc_mb_modify_contact_details($contact_details, $order) {
    // Replace values in $contact_details array with values from custom meta fields
    // This overwrites the default field values. To clear a value, use:
    // $contact_details['firstname'] = ''; // Empty value
    $order_id = $order->get_id();
    $contact_details['company_name'] = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['firstname']    = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['lastname']     = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['address1']     = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['address2']     = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['zipcode']      = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['city']         = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['country']      = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['email']        = get_post_meta($order_id, '_custom_field_name', true);
    $contact_details['phone']        = get_post_meta($order_id, '_custom_field_name', true);

    // Fill the "T.a.v. facturen" field of Moneybird contact
    $contact_details['send_invoices_to_attention'] = get_post_meta($order_id, '_custom_field_name', true);

    return $contact_details;
}

add_filter('woocommerce_moneybird_contact_details', 'wc_mb_modify_contact_details', 10, 2);