E-Paragony setup in festiware (E-Receipts in Poland)

E-Paragony Setup Guide

Automatic fiscal receipt (paragon) printing for orders placed through the festiware ticket shop, using Polish e-paragon regulations.

Overview

When a customer completes a purchase in the ticket shop, festiware can automatically issue a fiscal receipt (paragon) via an external receipt printer. This is achieved by combining three festiware features:

1. Complex tax rules on offers (to split prices across multiple tax rates)
2. A trigger that fires when an order is paid
3. A webhook that sends order + tax data to n8n, which communicates with the printer

Prerequisites

• Please make sure that the 'Complex Tax rules' feature is included in your festiware subscription and enabled for your instance
• An n8n instance with a webhook endpoint configured to receive order data and forward it to the receipt printer API
• A compatible fiscal receipt printer

Step 1: Configure Complex Tax Rules on Offers

Each offer (ticket) in the shop needs tax rules that reflect the correct tax split for your jurisdiction.

1. Go to All settings > Offers and edit an offer
2. Under Tax rules, add one rule per tax rate. Each rule has:

• Description (label): The name printed on the receipt. Max 40 characters. (See Label naming rules below.)
• Split (percent): What portion of the ticket price this rule covers (as a percentage, e.g. 50.9 for 50.9%)
• Tax rate (rate): The tax rate for this portion (as a percentage, e.g. 8 for 8%)

3. The splits across all rules must add up to 100%

Example

A festival ticket sold in Poland costs 39 EUR. Part of the revenue is taxed in Germany (0% entertainment tax exemption) and part in Poland (8% VAT):

| Label | Split | Tax rate | |---|---|---| | Hamburg > Fest Thu 0800 / Tax DE       | 50.9% | 0% | | Hamburg > Fest Thu 0800 / Tax PL       | 49.1% | 8% |

Step 2: Create a Trigger

Set up a trigger that fires when an order reaches "paid" status:

1. Go to All settings > Triggers
2. Create a new trigger with:

• Model: Order
• Event: Updated
• Conditions: Order status equals "paid" (or your equivalent paid status)

3. Attach a Webhook action to this trigger (see Step 3)

Step 3: Configure the Webhook

The webhook sends the order data (including complex tax lines) to your n8n endpoint:

1. Go to All settings > Webhooks
2. Create a new webhook with:

• URL: Your n8n webhook endpoint URL
• Method: POST
• Payload: The order data including order positions with their tax_lines      

3. Link this webhook to the trigger from Step 2

The tax_lines       on each order position contain the pre-calculated tax breakdown:

json [ { "label": "Hamburg > Fest Thu 0800 / Tax DE", "tax_rate": 0, "base_amount": 19.85, "tax_amount": 0 }, { "label": "Hamburg > Fest Thu 0800 / Tax PL", "tax_rate": 0.08, "base_amount": 17.73, "tax_amount": 1.42 } ]      

The label       field is passed to n8n as-is and ultimately printed on the paragon. n8n should forward these labels unchanged to the printer API.

Label Naming Rules

This is critical for avoiding fiscal errors:

40-character limit

Receipt printers store product names in an internal database, truncated to 40 characters (exact limit depends on printer model). If your label exceeds 40 characters, the printer stores only the first 40.

Labels must be unique per tax rate

The printer's internal database maps each product name to a tax rate. If two different tax rules produce the same truncated name but have different tax rates, the printer will reject the receipt with:

> Error 18 — Schodek podatkowy (tax shortfall)

This happens because the printer sees the same product name it already knows, but with a different tax rate than what's stored.

If Error 18 occurs

You must use a completely new label that has never been used before. The old label is permanently cached in the printer's memory with the wrong tax rate. Simply fixing the tax rate while keeping the same label will not resolve the error.

For example, if Hamburg > Festival Thu 0800 / Tax PL       caused Error 18, change it to something like HH > Fest 2026 Thu 0800 / Tax PL       — a name the printer has never seen.

Recommended naming pattern

Use short, distinctive labels that include: - Location abbreviation - Event/date identifier - Tax jurisdiction

Examples: - HH > Fest 2026 Fri 1200 / Tax DE       - HH > Fest 2026 Fri 1200 / Tax PL 8%      

Reissuing Receipts for Past Orders

If Error 18 prevented a receipt from being issued for a paid order, you can reissue it:

1. Go to the order
2. Use the Reissue paragon action
3. This will resend the order data to n8n with the current tax line labels

Make sure you have updated the offer's tax rule labels to new, unique names before reissuing.