FAIR

Federated and Independent Repositories

FreeInvoice API

Plugin Banner

FreeInvoice API

by Cloud Finance

Download
Description

FreeInvoice API connects your WooCommerce store to the FreeInvoice service, automating the generation and transmission of Italian electronic invoices and commercial documents.

Key Features

  • SDI Invoices — Generate FatturaPA XML and send invoices through the SDI (Sistema di Interscambio) with full status tracking (states 4–9).
  • FreeInvoice Documents — Send ordini and ricevute through the FreeInvoice document flow with status tracking (states 17 and 33).
  • Ricevute for private customers — Private customers without a fiscal code are automatically routed to ricevute using the FreeInvoice Lead receiver — no fake fiscal code needed.
  • WooCommerce Checkout Block support — Full compatibility with the WooCommerce Checkout Block via the Additional Checkout Fields API, including conditional fiscal fields based on customer type.
  • Classic checkout support — Works with both the traditional WooCommerce checkout and the Checkout Block.
  • HPOS compatible — Full support for WooCommerce High-Performance Order Storage.
  • Auto-send on order completion — Optionally send invoices or documents automatically when an order is marked as completed.
  • Manual send from admin — Send invoices or documents on demand from the order admin screen with dedicated actions.
  • Webhook status tracking — Receive real-time status updates from the FreeInvoice service via webhook integration.
  • Conditional checkout fields — Fiscal fields (VAT number, fiscal code, recipient code / PEC) appear dynamically based on whether the customer selects “Individual” or “Company/Professional”.
  • Guest checkout — Fiscal fields are collected during checkout and stored on the order; no user account required.
  • Sandbox mode — Test the entire flow in the FreeInvoice sandbox environment before going live.
  • Invoice numbering — Automatic or manual invoice numbering with configurable settings.
  • 0% VAT rate management — Configure natura codes for 0% VAT rates according to FatturaPA requirements.
  • Admin order list — View invoice/document status directly in the WooCommerce orders list with clear labels and Auto/Manual badges.
  • Italian and English UI — The plugin interface is available in both Italian and English.

Prerequisites

Documentation

Minimum requirements

  • WordPress 5.2 or later
  • PHP 7.2 or later
  • WooCommerce installed and active
  • An active FreeInvoice API account

Automatic installation

  1. Go to Plugins Add New in your WordPress admin.
  2. Search for “FreeInvoice API”.
  3. Click Install Now and then Activate.

Manual installation via WordPress admin

  1. Download the plugin zip file.
  2. Go to Plugins Add New Upload Plugin.
  3. Choose the zip file and click Install Now.
  4. Click Activate.

Manual installation via FTP

  1. Download and unzip the plugin.
  2. Upload the freeinvoice-api folder to /wp-content/plugins/.
  3. Activate the plugin from the Plugins menu.

After activation

  1. Go to WooCommerce Settings FreeInvoice API.
  2. Enter your FreeInvoice API credentials.
  3. Configure your seller data, tax regime, and VAT rates.
  4. Choose whether to use sandbox or production mode.
  1. General plugin settings

    General plugin settings

  2. Seller data configuration

    Seller data configuration

  3. Invoice management setup

    Invoice management setup

  4. 0% VAT rate management

    0% VAT rate management

  5. Payment method configuration

    Payment method configuration

  6. Invoice/document send dialog

    Invoice/document send dialog

  7. Invoice batch purchase

    Invoice batch purchase

  8. Invoice numbering settings

    Invoice numbering settings

  9. Fiscal fields during WooCommerce checkout

    Fiscal fields during WooCommerce checkout

  10. Fiscal data in WooCommerce order detail

    Fiscal data in WooCommerce order detail

  11. Invoice/document status in WooCommerce orders list

    Invoice/document status in WooCommerce orders list

What do I need to use this plugin?

You need a WordPress site with WooCommerce installed and an active FreeInvoice API account. You can sign up at cloudfinance.it.

Does this plugin support the WooCommerce Checkout Block?

Yes. The plugin uses the WooCommerce Additional Checkout Fields API to add fiscal fields to both the classic checkout and the WooCommerce Checkout Block. Fields appear conditionally based on customer type.

What is HPOS and is it supported?

HPOS (High-Performance Order Storage) is WooCommerce’s modern order data storage system. This plugin fully supports HPOS and works correctly with it enabled or disabled.

What types of documents can I send?

The plugin supports three document types:
* SDI Invoices (fatture elettroniche) — sent through the SDI, for companies and private individuals with a fiscal code.
* Ordini (orders) — sent through the FreeInvoice document flow, for companies and private individuals with a fiscal code.
* Ricevute (receipts) — sent through the FreeInvoice document flow, for private individuals without a fiscal code.

How does the ricevute flow work for private customers without a fiscal code?

When a private customer does not provide a fiscal code at checkout, the plugin automatically routes the document as a ricevuta. The FreeInvoice backend creates or matches a Lead receiver using the customer’s email address — no fake fiscal code is used.

Can I test the plugin before going live?

Yes. Enable sandbox mode in the plugin settings to test the entire invoice and document flow against the FreeInvoice sandbox environment. No real invoices will be transmitted.

Does the plugin send invoices automatically?

Yes, if auto-send is enabled in the settings, the plugin will automatically send the appropriate invoice or document when a WooCommerce order is marked as completed. You can also send manually from the order admin screen at any time.

How do I track invoice status?

Invoice and document status is updated in real time via webhook. You can see the current status in the WooCommerce order admin screen and in the orders list.

Can I disable invoicing for private individuals?

Yes. In the plugin settings you can enable or disable electronic invoicing for private individuals. When disabled, the fiscal fields will not appear for private customers during checkout.

Where can I manage the tax regime?

In the plugin settings (WooCommerce Settings FreeInvoice API) you can select your business tax regime from a drop-down list.

Does the plugin generate PDF invoices?

No. The plugin generates FatturaPA XML and transmits it through the FreeInvoice service. PDF invoices are available on your FreeInvoice account.

Can I manage 0% VAT rates?

Yes. The plugin settings include a dedicated section for managing 0% VAT rates with their corresponding FatturaPA natura codes.

Where can I configure invoice numbering?

Invoice numbering settings are available in the plugin settings. You can choose between automatic or manual numbering.

1.1.1

  • Fix incorrect split payment flag on zero-VAT/Natura XML summaries sent to SDI

1.1.0

  • Add WooCommerce Checkout Block support via Additional Checkout Fields API
  • Add HPOS (High-Performance Order Storage) compatibility
  • Add FreeInvoice document flow: ordini and ricevute
  • Add automatic routing of private customers without fiscal code to ricevute via Lead receiver
  • Add auto-send on order completion with tracking
  • Add manual send for both SDI invoices and FreeInvoice documents from order admin
  • Add webhook status tracking for invoices and documents
  • Add conditional checkout fields based on customer type (individual/company)
  • Add guest checkout support for fiscal fields
  • Add customer email to API payload for document sending
  • Improve admin metabox with route-aware labels (Invia Fattura / Invia Ricevuta / Invia Ordine)
  • Improve order list status display with single primary label and Auto/Manual badge
  • Fix shipping data in XML generation
  • Fix admin error messages: separate SDI and document errors, no false CF blocker for ricevute
  • Update Plugin URI to owner site
  • Rename README.txt to readme.txt for WordPress.org compliance

1.0.3

  • Fix invoice sending errors and WordPress 6.9 compatibility
  • Fix 0% VAT rate handling
  • Add user-configurable API endpoints
  • Add sandbox/production endpoint toggle
  • Improve invoice error display in admin UI
  • Fix address/province error when PEC destinatario is missing

1.0.0

  • First public release of the FreeInvoice API plugin
  • Generation and sending of FatturaPA XML electronic invoices
  • Fiscal checkout fields (VAT number, fiscal code, recipient code/PEC)
  • Customer data persistence on orders
  • Enable/disable invoicing for private individuals
  • Dynamic checkout field management
  • VAT number and fiscal code validation
  • Invoice numbering (automatic/manual)
  • 0% VAT rate management with natura codes
  • Payment method configuration
  • Sandbox mode for testing
Back to top