Bexio Synchronizer for Craft Commerce

Seamlessly synchronize completed Craft Commerce orders and customer contact details into Bexio as either Orders (Aufträge) or Invoices (Rechnungen). Elevate your Swiss e-commerce store with automated accounting, contact deduplication, tax mapping, and instant email billing.

---

Key Features

• Flexible Synchronization:
  • Orders (Aufträge): Sync checkouts as open orders in Bexio, perfect for manual fulfillment workflows.
  • Invoices (Rechnungen): Automatically book, issue, and optionally send finished invoices to your customers immediately.
• Automated Email Dispatch: Send generated invoices as booked PDFs directly through Bexio’s email delivery network, ensuring they include required online portals and Swiss billing links.
• Deduplicated Contact Matching: Automatically matches buyers by email in Bexio. If found, the order or invoice maps to their existing profile; if new, a robust customer record with complete address lines and primary tags is created.
• Flexible Bookkeeping & VAT Mapping:
  • Map default ledger/booking accounts for all synchronized lines.
  • Detect and match complex tax percentages automatically, falling back safely to a default mapped VAT rate if unmatched.
• Robust Background Processing: Integrates natively with the Craft Queue to ensure a fast, non-blocking customer checkout flow.
• Interactive Control Panel Dashboard: Manage synchronization status, read full error traces, and manually trigger syncs for any failed checkout attempt with a single click.

---

Requirements

This plugin requires:

• Craft CMS 5.10.0 or later
• Craft Commerce 5.0.0 or later
• PHP 8.2 or later
• A valid Bexio account with API access (Developer Personal Access Token)

---

Installation

From the Craft Plugin Store

1. In your Craft Control Panel, go to Plugin Store.
2. Search for Bexio Synchronizer.
3. Click Install.

With Composer

Run the following commands in your terminal from your project root:

# Require the plugin via Composer
composer require thekitchen-agency/craft-bexio-synchronizer

# Install and activate the plugin via Craft CLI
./craft plugin/install bexio-synchronizer

---

Setup & Configuration

1. Obtain a Bexio Personal Access Token (PAT):
   • Log in to your Bexio developer portal at developer.bexio.com.
   • Create a new Personal Access Token (PAT) with the required scopes for contacts, orders, and invoices.
2. Configure the Plugin:
   • In the Craft Control Panel, navigate to Settings → Bexio Synchronizer (or Bexio Sync in the sidebar).
   • Enter your Personal Access Token.
   • Click the Test & Load Accounts/Taxes button. This uses a secure AJAX call to verify credentials and pull your real-time bookkeeping charts and tax rates.
3. Map Ledger Accounts & Taxes:
   • Select a Default Bookkeeping Account for line-item positions.
   • Choose a Default Tax Rate (VAT) to act as a safe fallback.
   • Enable Auto Synchronize Completed Orders if you want the queue jobs to fire immediately upon successful checkout.
4. Choose Your Document Type:
   • Order (Auftrag): The plugin creates open orders in Bexio.
   • Invoice (Rechnung): The plugin creates invoices, issues them (committing them to bookkeeping and generating invoice numbers), and opens up automated dispatch settings.
5. Configure Invoice Emails (Optional):
   • Enable Send Invoice via Bexio.
   • Provide a custom Email Subject and Email Message.
   • Important: You must include the [Network Link] placeholder inside your email message. Bexio uses this to insert the secure link where customers view and download their invoice.

---

Under the Hood

Event-Driven Sync

When Auto Synchronize is enabled, the plugin hooks into Order::EVENT_AFTER_COMPLETE_ORDER. It logs a new row in the database tables as pending and immediately dispatches a SyncOrderJob to the Craft Queue. This guarantees that checkout is never slowed down by external API latency.

Resilient Try-Catch Lifecycles

If you choose the invoice sync, the system performs a multi-stage transaction:

1. POST 2.0/kb_invoice — Creates the draft invoice.
2. POST 2.0/kb_invoice/{id}/issue — Books the invoice, locking it and generating the Swiss VAT invoice number.
3. POST 2.0/kb_invoice/{id}/send — Delivers the invoice email to the customer.

If an email server issue or temporary Bexio mail block occurs, the service catches the exception gracefully, logs a warning in the system log, and successfully commits the order/invoice linkage in the database to prevent double-billing.

---

Support & Contributions

For bugs, feature requests, or custom agency requests, please open an issue in the GitHub issue tracker or reach out directly to tech@thekitchen.agency.

License

This plugin is licensed under a proprietary agency license. See the LICENSE.md file for details.