Invoice Generation

FCHub Fakturownia automatically creates invoices in Fakturownia when FluentCart orders are paid. This page covers the complete invoice creation flow, data mapping, VAT rate handling, and correction invoices.

Invoice Creation Flow

The end-to-end process from payment to invoice:

B2B vs B2C Invoices

The plugin automatically determines whether to create a business (B2B) or consumer (B2C) invoice based on the checkout data.

Data Mapping Reference

Here's exactly how FluentCart order data maps to Fakturownia invoice fields.

Invoice Header

Buyer Information

Line Items (Positions)

Each order item becomes a position on the invoice:

If the order has shipping charges, a separate line item is added for shipping with its own VAT rate.

Polish VAT Rates

The plugin calculates the VAT rate for each line item from the order's tax data and maps it to the closest standard Polish rate.

Calculation

For each order item:

1. The tax amount and post-discount line total are extracted
2. The effective rate is calculated: (tax_amount / line_total) * 100
3. The result is rounded and mapped to the nearest standard rate

Using line_total (not subtotal) is critical — tax is calculated on the discounted amount. Using the pre-discount subtotal produced wrong rates for discounted items.

Standard Rates

If the tax amount is zero, the item gets a 0 rate (not zw — zero-rate and exempt are legally different in Polish tax law). If a rate cannot be determined, the default is 23%. When KSeF is enabled and any position uses zw, the plugin auto-sets exempt_tax_kind to prevent KSeF rejection.

Price Conversion

FluentCart stores prices in cents (integer values). Fakturownia expects prices in decimal format. The plugin converts automatically:

FluentCart: 9900 (cents) → Fakturownia: 99.00 (decimal)
FluentCart: 1550 (cents) → Fakturownia: 15.50 (decimal)

The conversion uses round($cents / 100, 2) to ensure precision to two decimal places.

Payment Type Mapping

The plugin maps FluentCart payment gateway slugs to Fakturownia payment type values. If the order's payment method matches a known gateway, the mapped value is used. Otherwise, the default from settings is applied.

Default Mapping

Custom Mapping

You can customize the mapping using the fchub_fakturownia/payment_type_map filter:

add_filter('fchub_fakturownia/payment_type_map', function ($map) {
    // Add a custom gateway mapping
    $map['my_custom_gateway'] = 'transfer';

    // Override an existing mapping
    $map['stripe'] = 'transfer';

    return $map;
});

Correction Invoices (Refunds)

When an order is fully refunded, the plugin automatically creates a correction invoice in Fakturownia.

Correction Flow

Admin Order View

When an order has a Fakturownia invoice, the plugin displays invoice information in the FluentCart admin order receipt view. This section appears below the standard order details and includes:

Error Handling

Invoice creation can fail for several reasons. The plugin handles errors gracefully:

• API connection failure -- logged as an error on the order. The invoice can be retried by re-triggering the payment event.
• Validation errors -- Fakturownia returns field-level validation errors. These are formatted into a readable string and logged on the order (e.g., "buyer_tax_no: is invalid").
• Duplicate invoice -- if an invoice already exists for the order, the creation is silently skipped with an error return.

All errors are recorded in the FluentCart order logs with the source "Fakturownia" for easy filtering.