Troubleshooting

This page covers the most common issues reported by Fakturownia Pro for Shopify users. For each issue, follow the diagnostic steps in order before attempting fixes.

Invoice Was Not Created

Symptom: An order transitioned to a configured status, but no invoice appeared in Fakturownia.

Diagnostic Step 1: Check the Activity Log

Open the order in Shopify admin
In the right sidebar under Apps, click "Fakturownia Pro"
The activity log shows every action attempted for this order, with timestamps and outcomes

Look for one of these entries:

| Entry type | What it means | |---|---| | Invoice created successfully | Invoice was created — check Fakturownia directly | | Duplicate prevented — invoice already exists | An invoice for this order already exists in Fakturownia | | Rule not configured for status: orders/paid | No rule exists for the status that fired | | API error: [error message] | API call to Fakturownia failed — see error message | | No entry | The webhook may not have fired at all |

Diagnostic Step 2: Check the Shopify Webhook Log

Go to Shopify Admin → Settings → Notifications → Webhooks
Find the relevant webhook topic (e.g., orders/paid)
Check the delivery history — look for failed deliveries (non-200 response codes)

Shopify retries failed webhooks up to 19 times over 48 hours. If all 19 retries fail, Shopify stops and the event is lost. The app's activity log will show no entry for this order.

To manually trigger the action: Go to the order in Shopify, open the Fakturownia Pro app section, and click "Regenerate Invoice". This bypasses webhooks and directly calls the invoice creation API.

Diagnostic Step 3: Verify Rule Configuration

Open Fakturownia Pro → Invoice Rules and confirm a rule exists for the exact status the order reached. Shopify webhook topics use specific slugs (orders/paid, not "Payment received"). Confirm the rule is configured with the correct technical slug, not a display-name variant.

Diagnostic Step 4: Test API Connection

Go to Settings → Connection and click "Test Connection". A failed connection means the API token has expired or been regenerated in Fakturownia. Re-enter the current token.

API Connection Fails

Symptom: "Connection failed" or "Invalid API token" error when clicking Test Connection.

Error: "Invalid API token"

Cause: Token was regenerated in Fakturownia without updating it in the app, or the token was pasted without the domain portion.

Fix:

Log in to Fakturownia → Settings → Account → Integration → API Authorization Code
Copy the full token: it is a string ending in /yourcompany.fakturownia.pl
In Fakturownia Pro → Settings → Connection, paste the complete token
Click Test Connection

Error: "Connection timeout"

Cause: Shopify's app infrastructure cannot reach the Fakturownia API. This is uncommon but can occur during Fakturownia service incidents.

Fix:

Check status.fakturownia.pl for reported outages
Wait 5 minutes and retry
If the issue persists beyond 30 minutes, contact Fakturownia support

Error: "Custom domain not found"

Cause: A custom domain is entered in the Custom Domain field but the domain is incorrect, or the domain is not active on Fakturownia's servers.

Fix: Delete the value from the Custom Domain field. The app will auto-detect the domain from the token string. If you genuinely use a custom domain, verify it against your Fakturownia account settings.

Duplicate Invoices

Symptom: Two invoices exist in Fakturownia for the same Shopify order.

Cause: This happens when a Shopify webhook fires twice in rapid succession (documented behavior during Shopify platform incidents) and the duplicate prevention check fails due to a transient API timeout.

Resolution:

Identify the duplicate: open the order in Fakturownia and check invoice history for that buyer
Cancel the duplicate invoice in Fakturownia (do not delete — cancelled invoices are kept for audit)
If the remaining invoice is correct, no further action is needed
If you are unsure which is the canonical invoice, check the Fakturownia Pro activity log for the creation timestamp and correlate with the Shopify webhook delivery time

Prevention: Duplicate prevention is enabled by default. Recurring duplicates indicate a timing issue with the API connection. Check Settings → Advanced → API Timeout — if the timeout is set very low (under 5 seconds), the duplicate check may be timing out before the existence query returns. Increase to 10 seconds.

Shopify-Specific Issues

Webhooks Failing Due to App Rate Limits

Shopify imposes API rate limits on app usage. For high-volume stores processing hundreds of orders per minute (e.g., during a flash sale), Fakturownia Pro may hit Shopify's rate limits when reading order details for invoice generation.

Symptoms: Invoices are created with a delay of several minutes after the order status change. Activity log shows 429 Too Many Requests errors followed by successful creation on retry.

What Fakturownia Pro does: Automatically retries on rate limit responses with exponential backoff. Invoices eventually create — they are just delayed.

To avoid during planned high-traffic events: Contact Fakturownia Pro support before a major sale to enable a higher-throughput API queue for your store.

Shopify Plus Checkout Extensibility

If you recently upgraded to Shopify Plus and enabled the new checkout extensibility system, the NIP field injection may behave differently. The legacy additional_scripts approach (used for non-Plus checkout customization) is not supported on the new checkout. Re-enable the NIP field under Settings → Compliance and follow the Shopify Plus-specific setup instructions.

Order Archived Before Invoice Created

Shopify allows merchants to archive orders after a configurable number of days. Archived orders are locked from further modifications. If an invoice rule fires on a status change that occurs after the order is archived (uncommon but possible with long fulfillment times and slow rule configurations), the invoice will be created in Fakturownia but cannot be written back to the Shopify order.

Symptom: Invoice exists in Fakturownia but does not appear in the Shopify order's app section.

Fix: There is no automatic resolution — the order record in Shopify is read-only. The invoice is correct in Fakturownia and can be accessed there or via the customer portal. Consider adjusting Shopify's auto-archive setting to a longer window.

Invoice Not Showing in Customer Portal

Symptom: Customer logs in and sees no Invoices section, or invoices are missing.

Check 1: New Customer Accounts

The portal requires Shopify's new customer accounts. Go to Shopify Admin → Settings → Customer accounts and confirm "New customer accounts" is active. If you see "Classic customer accounts," the portal will not work.

Check 2: Portal Is Enabled

Go to Fakturownia Pro → Settings → Customer Portal and confirm the toggle is on.

Check 3: Email Address Mismatch

The portal matches invoices to customer accounts by email. If the order was placed with a different email than the customer's Shopify account email (common in B2B orders where a purchasing email differs from the account holder's email), the invoice will not appear.

Diagnose: Open the invoice in Fakturownia and check the buyer email. Compare it to the customer's Shopify account email under Shopify Admin → Customers → [Customer].

Check 4: Plan Restriction

The customer portal is not available on the Free plan. Upgrade to Starter or higher.

Check 5: Invoice Recently Created

The portal reads invoices from Fakturownia in real time. If an invoice was created within the last 60 seconds, it may not yet appear in the portal. Ask the customer to refresh the page after 1–2 minutes.

PDF Download Fails or Times Out

Most likely cause: Temporary Fakturownia API slowness — PDF generation is real-time.

Steps:

Ask the customer to try again after 2–3 minutes
Check status.fakturownia.pl for any reported PDF generation issues
Download the PDF directly from Fakturownia admin and email it to the customer as a workaround

If the PDF consistently fails to download for a specific invoice (not all invoices), the invoice may be in a state that prevents PDF generation in Fakturownia (e.g., a cancelled invoice that is no longer renderable). Log into Fakturownia directly to check the invoice status.

Credit Note Not Created on Refund

Check 1: Credit note rule exists

Open Invoice Rules and confirm a rule for refunds/create with action Create Credit Note is configured.

Check 2: Original invoice exists

Fakturownia requires an original invoice to create a credit note against. If no invoice exists for the order (e.g., the order was placed before Fakturownia Pro was installed), the credit note cannot be created automatically.

Workaround: Create the credit note manually in Fakturownia against the customer's account.

Check 3: Partial refund from Shopify

Partial refunds are handled correctly by Fakturownia Pro. If a partial refund created a credit note with an unexpected amount, check the refund line items in Shopify — the credit note mirrors exactly what was refunded.

Wrong VAT Rate on Invoice

Symptom: An EU cross-border invoice shows Polish VAT (23%) instead of the destination country rate.

Most likely cause: EU OSS is not enabled, or the customer's destination country could not be determined from the order.

Check:

Confirm OSS is enabled: Settings → Compliance → EU OSS
Check the Shopify order's billing address country — this is the OSS destination country
Confirm the billing country is an EU member state (not UK, Norway, Switzerland)
If the customer entered an incorrect billing country at checkout, the invoice must be corrected manually in Fakturownia

Shopify Flow Actions Not Executing

Symptom: A Flow automation calling Create Invoice or Send Invoice does not result in the expected action.

Check 1: App permissions

Fakturownia Pro must have permission to receive Flow actions. Go to Shopify Admin → Settings → Apps and sales channels → Fakturownia Pro → Permissions and verify Flow is listed.

Check 2: Flow run history

In Shopify Admin → Apps → Flow, open the automation and check the Run history tab. Each run shows the full execution trace — look for condition failures (step skipped) or action errors (step failed).

Check 3: Flow trigger conditions

Review whether the trigger conditions restrict when the automation fires. A condition like "Order tag equals X" may be filtering out most orders.

Getting Support

If none of the above resolves your issue:

Note the Shopify order number and the approximate time the issue occurred
Copy the complete error message from the Fakturownia Pro activity log on the affected order
Note your Shopify plan and Fakturownia plan
Contact support at support@plugkit.io with all three items

Response times: 1 business day on paid plans. Free plan support is provided via community forum only.

Next Steps

Changelog — check recent releases for bug fixes
Invoice Rules — review rule configuration
Compliance — OSS, GTU, split payment setup