Econz for Craft CMS

Troubleshooting

Start with the log

Econz → Log has a row for every API call: the endpoint, the status, how long it took, the order it was for, and e-conomic's own X-CallCost. When e-conomic rejects something, the row keeps its errorCode and message. The full error, including e-conomic's developerHint and the logId their support will ask for, is in the stored response body.

If something has gone quiet, the log answers "why is there no invoice for order 1042?" An integration that has stopped working looks exactly like one with nothing to do.

To see what was actually sent, turn on Store request and response bodies under Settings → Log. Turn it off again when you're done, because the bodies contain customer details.

"Econz needs a layout before it can raise an invoice"

e-conomic requires a layout and payment terms on every draft invoice. Pick them under Settings → Mapping. Creating a customer also needs a customer group, and creating a product needs a product group. Each of those refusals names the setting to fill in.

"Econz is in demo mode, which is read-only"

The demo agreement can be read, but nothing can be written to it. Turn Demo mode off and enter your own tokens under Settings → Connection.

A 401 when testing the connection

One of the two tokens is wrong, or the agreement has withdrawn access to your app. Econz shows e-conomic's own error code, which says which one it is. If you use $ENV_VAR references, check the variable is set in the environment Craft actually runs in. A queue worker started before you edited .env still has the old values.

"Econz computed a net total of X but Commerce holds Y"

The totals check found a gap bigger than your tolerance. The likely causes, most likely first:

  • Line discounts sent as a percentage. e-conomic rounds the percentage per line, and the order panel names the line that drifted. Switch Line discounts to Fold into the unit price and the invoice will always reconcile.
  • Order-level included tax with nothing to charge it against. The warning says so directly. It usually means a custom adjuster adds tax without a matching line.
  • A custom adjuster or plugin that changes the order total without recording an adjustment.

With When they disagree set to Send anyway and warn, the draft is created and the warning stays on the order. With Refuse to send, nothing is sent.

"Commerce charged no tax on this order, but the zone will charge it"

This is a VAT sanity warning. Econz never overrules Commerce on tax. It tells you when your Commerce tax zones and your VAT zone mapping disagree about an order, and leaves the fix to you.

The usual cause is an EU business customer. Commerce zero-rated the order, but the VAT number Econz found was malformed or missing, so Econz fell back to Domestic. Check the number on the order panel. If you're registered for OSS, you may also want EU addresses without a VAT number are still EU under Settings → VAT.

"The zone has not been mapped to an e-conomic vat zone number"

Set the Domestic, EU and Abroad numbers under Settings → VAT. php craft econz/connection/catalog vatZones lists the numbers your agreement uses.

"No e-conomic customer matches…, and Econz is not allowed to create one"

Create customers is off and nothing matched. Turn it on, or set a Fallback customer number for a catch-all debtor.

"No e-conomic product matches the SKU"

Require known products is on, and an order has a SKU with no product in e-conomic. Run php craft econz/products/sync to see what would be created, then again with --dry-run=0. You can also turn on Create products and let Econz create them as orders arrive.

"Invoice N is already booked"

A booked invoice can't be re-sent. It can only be credited. Use Raise credit note on the order, then send it again if you need to.

A push failed and I've fixed the cause

Press Re-send on the order, or retry every failure at once (Pro):

php craft econz/sync/retry

The retry reuses the same idempotency key while the payload hasn't changed. If e-conomic did create the draft before the failure, you get that same draft back, not a second one.

Throttled (429)

e-conomic allows a fixed number of call-cost tokens per minute. Econz reads the remaining budget from every response and slows itself down before it runs out, so a 429 usually means another integration on the same agreement is using the budget. Econz retries a 429 up to your Retries setting.

Automatic pushes never happen (Pro)

  • Check Push automatically is on and that the Trigger matches how your orders move.
  • Check the order total is above Minimum order total.
  • Automatic pushes are queued. Make sure the queue is running: php craft queue/run, or check Utilities → Queue Manager.
  • A plugin or module handling Sync::EVENT_BEFORE_PUSH can skip orders. Those show as Skipped.