Installation

Requirements

• Craft CMS 5.3 or later
• PHP 8.2 or later
• Craft Commerce 5.0 or later, for order syncing
• An e-conomic agreement, plus an app secret token and an agreement grant token

Commerce is suggested rather than required. Econz installs and boots without it, so a site can connect and read its e-conomic reference data before a shop exists. Nothing gets invoiced until Commerce is installed.

Install

composer require justinholtweb/craft-econz
php craft plugin/install econz

You can also install Econz from the Craft Plugin Store.

Get your tokens

e-conomic authenticates with two tokens, and each one identifies something different:

• The app secret token identifies the app. You get it from the e-conomic developer portal when you register an app.
• The agreement grant token identifies the agreement, meaning the company whose books are written. You get it when the company's administrator grants your app access.

Both belong in .env. Anyone holding them can write to the company's books:

ECONOMIC_APP_SECRET="…"
ECONOMIC_AGREEMENT_GRANT="…"

Then open Econz → Settings → Connection and set the two fields to $ECONOMIC_APP_SECRET and $ECONOMIC_AGREEMENT_GRANT.

Test the connection

Press Test connection. Econz calls e-conomic's /self endpoint and names the company and agreement number it reached, so you can see straight away if you pasted a token for the wrong company. The same check runs from a terminal:

php craft econz/connection/test

Map the required settings

e-conomic won't accept a draft invoice without a layout and payment terms, and won't create a customer without a customer group. Econz doesn't guess any of these. Until they're set it refuses to push, and the refusal names the setting you need.

Open Econz → Settings → Mapping and pick them. The dropdowns are filled from your own agreement. To see the same lists in a terminal:

php craft econz/connection/catalog layouts
php craft econz/connection/catalog paymentTerms
php craft econz/connection/catalog customerGroups
php craft econz/connection/catalog vatZones

Then check Settings → VAT. Econz ships mapped to e-conomic's usual numbers (Domestic 1, EU 2, Abroad 3), but an agreement can have its own, so compare them with the vatZones list.

No tokens yet? Use demo mode

Turn on Demo mode and Econz connects to e-conomic's public demo agreement with the token demo. It's a real agreement with real reference data, which makes it a good place to learn the mapping screens. It is also read-only, so Econz refuses every push before the request leaves the plugin, rather than letting e-conomic reject it.

Your first draft

Preview before you send anything:

php craft econz/sync/preview 1042

That prints the exact payload Econz would send to /invoices/drafts and sends nothing. The Econz panel on Commerce's own order screen shows the same payload. Both come from one builder, so what you preview is byte-for-byte what gets sent.

When it looks right, press Send to e-conomic on the order, or:

php craft econz/sync/order 1042

The invoice arrives as a draft. Your bookkeeper can look at it in e-conomic before it's booked. That's the default, and many shops keep it that way.

Editions

Lite is free and it isn't a trial. It sends real invoices, one order at a time, with all the VAT and reconciliation logic included. Pro is $99 with a $49/year renewal. It adds automation, meaning the parts that act without anyone pressing a button.

	Lite	Pro
Price	Free	$99, $49/year renewal
Connection, connection test, agreement readout	✅	✅
Draft invoices: lines, shipping, discounts, adjustments	✅	✅
VAT zone resolution from country and VAT number	✅	✅
CVR, EU VAT and EAN capture with format validation	✅	✅
Customer find-or-create	✅	✅
Order-screen panel with the exact payload	✅	✅
Totals reconciliation against Commerce	✅	✅
Connection log, Twig API, console commands	✅	✅
Automatic push, queued, on completion or a chosen status		✅
Auto-booking, with e-invoicing or email hand-off		✅
Credit notes when a refund goes through		✅
Product catalogue sync, with a dry run		✅
Bulk push and econz/sync/retry		✅
Outstanding amounts read back off booked invoices		✅
Departments and projects on invoice lines		✅

Next

• Configuration: every setting, and which ones matter
• Usage: the order panel, checkout capture, Twig and the console