===Invoicing Integration for FreeAgent and WooCommerce===
Contributors: devikit
Tags: freeagent, woocommerce, invoicing, vat, accounting
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.11
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html
WC requires at least: 5.0
WC tested up to: 9.7

FreeAgent invoices from WooCommerce: VAT capture, contacts, catalog line types, PDF downloads—HPOS compatible.

== Description ==

Connect WooCommerce to **FreeAgent.com** through the official OAuth API. Manage invoicing inside your WooCommerce admin: issue invoices from orders, keep contacts aligned with billing, capture VAT cleanly and expose invoice PDFs where shoppers and staff expect them.

https://youtu.be/5znuKcxHMSU

= Free plugin — what you already get =

* **OAuth connection** — connect from **WooCommerce → FreeAgent** with your Developer app credentials (`dev.freeagent.com`).
* **One-click invoicing per order** — create a FreeAgent invoice from the order screen (`Create Invoice`).
* **Find-or-create contacts** — maps billing profile to FreeAgent contacts (matching by email); updates addresses, company name, VAT number when invoicing again.
* **VAT number capture** — optional or mandatory checkout field (`classic checkout` **and** `Woo Blocks` supported); configurable label; **Hide** / **Always visible** on Blocks; optional “VAT invoice” checkbox reveal is classic-only.
* **FreeAgent line item types on catalog** — per simple, subscription **and variation** SKU: choose Hours through Expenses (`Products`, `Services`, …) so drafts match how you recognise revenue.
* **Line-level VAT detection** — net, gross and tax rates inferred from WooCommerce tax configuration; avoids double-counting.
* **EC / B2B reporting defaults** — auto classifies invoices as UK/Non-EC or Reverse Charge for EU VAT-registered billing countries; editable **dated on**, payment terms days, invoice comments merge-tags (`{order_id}`, `{order_number}`, `{customer_email}`, …) and EC status overrides before you issue from the metabox.
* **VAT exemption basis** — saves you retyping statute text every time (`VAT Exemption Basis` setting appended when a zero-rate line is invoiced).
* **Payment terms & bank detail** — set company-wide terms in days + pick FreeAgent bank account for remittance text on invoices.
* **Invoice status & warnings** — optional **Mark as Sent** (“Open”), **retry** failed creates via scheduled job, **`total mismatch`** flag when rounded FA vs Woo totals differ (including single minor-unit deltas), admin notice plus **orders list column** with links and mismatch styling.
* **Customer PDF access** — download PDF from the order metabox plus an **Invoices** tab inside **My Account** (customers only see own orders).
* **Security-minded logging** — optional WooCommerce Logger trail for troubleshooting with OAuth secrets redacted.
* **PRO-aware UI** — **Invoicing** tab PRO banners, **Automation** teaser, **bulk action** placeholders (shows what unlocks once PRO is licensed), and teaser rows for credits / MOSS presets so admins know exactly what activates with the add-on.

= PRO add-on — optional automation & scale =
**[Invoicing Integration PRO](https://devikit.co.uk/product/freeagent-woocommerce-pro/)** is a companion plugin (sold & licensed separately) that registers only when a valid license is active. Add it when you are ready for:

* **Automatic invoice queueing** — runs when orders reach the statuses you configure; optional rollup mode queues work for nightly consolidated postings instead.
* **Automatic credit notes** — refund-driven credit documents with matching automation flags.
* **Daily rollup / grouped mode** — batch many orders + refunds into consolidated FreeAgent sales invoices and credit clusters (VAT-grouped, multi-currency aware) on a dedicated contact.
* **Automatic payment recording** — once Woo marks an order paid, book the equivalent bank receipt in FreeAgent (mirrors manual “record payment”).
* **Automation delivery** — optional FreeAgent template emails plus WooCommerce customer emails; optional Action Scheduler spacing via the `devikit_freeagent_invoice_email_delay_minutes` filter.
* **Dedicated WooCommerce email types** — invoice + credit-note templates with **PDF attachments** pulled from FreeAgent.
* **Order & bulk customer comms** — send invoice or credit note from the order screen **or** run **bulk** “create”, “email via FA”, “email via Woo”, **ZIP many PDFs** from the orders list.
* **Custom references** — invoice reference patterns with `{order_id}`, `{order_number}`, etc.
* **Accounting category + default line type** — FreeAgent income nominal per line + store default item type when a product does not override.
* **Online payment links** — toggles API `payment_methods` hash for Stripe, PayPal, GoCardless (mandate + Instant Bank Pay), Tyl (subject to what you enable inside FreeAgent).
* **EC VAT MOSS defaults** — store-wide MOSS toggle plus per-product / per-variation MOSS flags so EU digital services orders can resolve to `EC VAT MOSS` automatically.
* **Licensed plugin updates** — delivered through Devikit’s updater once your PRO license is active (plus any support channels bundled with your purchase).

**[Feature list and licensing on Devikit](https://devikit.co.uk/product/freeagent-woocommerce-pro/)**

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate via **Plugins > Installed Plugins**.
3. Go to **WooCommerce → FreeAgent** and connect your FreeAgent account via OAuth.
4. Configure invoicing settings and you are ready to go.

== Frequently Asked Questions ==

= Do I need a FreeAgent account? =

Yes. You need an active FreeAgent account and you must create an OAuth application at https://dev.freeagent.com/

= Where do I get the OAuth Client ID and Secret? =

Log in to FreeAgent, go to **Developer > My Apps > Create new app**. Copy the Client ID and Secret, then paste them on the plugin's Connection tab.

= Is the plugin compatible with HPOS (High-Performance Order Storage)? =

Yes. The plugin is declared compatible with WooCommerce HPOS.

= Does the plugin support Block Checkout? =

Yes. The VAT number field works in WooCommerce Block checkout for **Hide** and **Always visible**. The optional “I want a VAT invoice” checkbox that reveals the field first is only available on classic shortcode checkout.

= Can my customers download their invoices? =

Yes. An "Invoices" tab is added to My Account pages. Each customer can only see and download documents for their own orders.

= What happens if the invoice total does not match the order total? =

The plugin flags a mismatch in the order metabox and in the orders list (with the delta stored in order meta). The **automatic “FreeAgent Invoice” WooCommerce email (PRO)** is skipped until totals reconcile — fix the discrepancy in Woo or tweak the invoice in FreeAgent, then investigate/resend manually as needed (other workflows may still send).

== Screenshots ==

1. Plugin settings
2. Plugin settings
3. Plugin settings
4. Plugin settings
5. Plugin settings
6. Plugin settings
7. Plugin settings
8. Plugin settings
9. Plugin settings

== Changelog ==

= 1.0.11 =
* Fixed: PRO upgrade banner CSS loading on plugins screen (logo size and button styles).
* Fixed: Care banner "Don't remind me" uses the same link style as "Remind me later".

= 1.0.10 =
* Add: Devikit Care banner in WordPress admin with dismiss options
* Add: Devikit Care sidebar widget on plugin settings page
* Add: Devikit Care dashboard widget
* Fix: Pro upgrade banner restyled to match Care banner style

= 1.0.9 =
* Fixed: PRO banner CSS now loads in admin head so button styles apply correctly on WordPress 7.0.
* Fixed: Remind/dismiss actions render as text links with proper spacing (no bordered button look).

= 1.0.8 =
* Fixed: PRO upgrade banner now shows on all wp-admin screens (not only WooCommerce pages).
* Fixed: PRO banner button styling on WordPress 7.0 (link actions without borders).

= 1.0.7 =
* Fixed: PRO upgrade banner styling for WordPress 7.0 admin refresh (dedicated CSS, button-link actions).

= 1.0.6 =
* Fix: VAT number field now saves correctly in WP Admin user profile and synchronises with My Account edit address (bidirectional sync).
* Fix: VAT number is now populated when selecting a customer or clicking "Load billing address" in admin order edit screen.

= 1.0.5 =
* Readme: Tested up to WordPress 7.0.

= 1.0.4 =
* Readme: removed “Why upgrade to PRO?” FAQ entry.

= 1.0.3 =
* Readme: updated YouTube overview link, removed outdated paragraph, refreshed screenshot asset.

= 1.0.2 =
* Store: clarify WooCommerce Block checkout — Hide and Always visible apply in Blocks; the optional “VAT invoice” checkbox reveal is classic checkout only. Readme FAQ and listing copy aligned.

= 1.0.1 =
* Readme: plugin directory short description within 150 characters; Description and Bottom line layout tweaks.

= 1.0.0 =
* Initial release.

== External Services ==

This plugin connects to the **FreeAgent API** to create and manage invoices and contacts. An active FreeAgent account is required.

**What data is sent and when:**

* When you connect the plugin via OAuth, your OAuth credentials are exchanged for an access token with FreeAgent's authentication servers.
* When an invoice is created, WooCommerce order data (customer name, address, VAT number, line items, amounts) is sent to FreeAgent to create the invoice.
* When a customer's contact record is created or updated, their billing details (name, address, email, phone, VAT number) are sent to FreeAgent.
* When you reload the accounting categories or bank accounts list in the settings, a read request is made to the FreeAgent API.
* PDF invoice downloads are fetched from FreeAgent's servers on demand.

The **free plugin** triggers FreeAgent exclusively when staff or shoppers take explicit actions (connecting, reloading lists, issuing an invoice).

The **optional PRO companion** additionally talks to FreeAgent when automation rules queue invoices/credit notes, bulk actions run or delayed emails fire — mirrors the workloads you manually perform today.

**FreeAgent service information:**

* Service website: [https://www.freeagent.com](https://www.freeagent.com)
* Terms of Service: [https://www.freeagent.com/terms/](https://www.freeagent.com/terms/)
* Privacy Policy: [https://www.freeagent.com/privacy/](https://www.freeagent.com/privacy/)
* API documentation: [https://dev.freeagent.com/docs/introduction](https://dev.freeagent.com/docs/introduction)

== Upgrade Notice ==

= 1.0.11 =
Fixes PRO and Care admin banner styling (CSS load, care dismiss link color).

= 1.0.10 =
Adds Devikit Care promotion widgets (admin banner, settings sidebar, dashboard widget) and restyled Pro banner.

= 1.0.9 =
Fixes PRO banner button styling when CSS loads correctly in wp-admin.

= 1.0.8 =
PRO upgrade banner visibility and button styling fixes for WordPress 7.0.

= 1.0.5 =
Compatibility metadata only; no functional changes. Safe to update from 1.0.4.

= 1.0.4 =
Readme FAQ only; no functional changes. Safe to update from 1.0.3.

= 1.0.3 =
Readme and asset updates only; no functional changes. Safe to update from 1.0.2.

= 1.0.2 =
Documentation and admin copy only; behaviour unchanged. Safe to update from 1.0.1.

= 1.0.1 =
Listing copy only; no functional changes. Safe to update from 1.0.0.

= 1.0.0 =
Initial public release.
