Skip to content

Add docs page: Tax IDs — how WCPOS stores them as customer custom fields #174

Description

@kilbot

What we need

A user-facing docs page at /docs/tax-ids (or wherever fits the existing IA) that explains how WCPOS handles customer tax IDs end-to-end.

The settings UI in Settings → General → Customers → Tax IDs will link to this page via a "Learn more" link, so users can drill in when they need to understand what WCPOS is doing under the hood.

What the page should cover

  1. What tax IDs are in WCPOS

    • The 14 supported types (EU VAT, GB VAT, AU ABN, BR CPF, BR CNPJ, IN GST, IT CF, IT P.IVA, ES NIF, AR CUIT, SA VAT, CA GST/HST, US EIN, Other)
    • Format-only validation today (no live verification — that's a separate feature)
  2. How storage works

    • Tax IDs are stored as a custom field on the customer record (WordPress user meta + WooCommerce billing meta)
    • At checkout, WCPOS copies the value onto the order so it appears on invoices, exports, and is readable by other plugins / accountants
    • This mirrors how WC stores billing address fields — nothing exotic
  3. Plugin detection

    • WCPOS auto-detects compatible plugins on activation and on every settings load
    • List each detected plugin, the meta key it uses, and which tax-ID types it covers:
      • WooCommerce EU VAT Number → _billing_vat_number (VAT-shaped types)
      • Aelia EU VAT Assistant → vat_number
      • WPFactory EU/UK VAT Manager → _billing_eu_vat_number
      • WooCommerce Germanized → German tax types
      • Brazilian Market on WooCommerce → _billing_cpf / _billing_cnpj
      • NIF/CIF Spain for WooCommerce → _billing_nif
    • Source: `includes/Services/Tax_Id_Detector.php`
  4. Built-in defaults

    • When no plugin is detected, what WCPOS falls back to — table of all 14 types and their default meta keys
    • Source: `Tax_Id_Settings::default_write_map()`
  5. Override priority

    • Resolution order: user override → detected plugin → built-in default
    • When and why a user might override (e.g. they have a custom plugin or non-standard meta key)
    • How to find an existing custom field name: WP admin → Order → Custom Fields panel
  6. Receipts / orders

    • The tax ID is stored on both the customer record and the order
    • Templates that opt in (e.g. Tax Invoice template) render `customer.tax_ids[]` on receipts
    • Default receipt templates do NOT show tax IDs — users edit their template (Settings → Receipts → Template Studio) to surface them

Settings UI link

The settings page links to this doc with a "Learn more" link in the lead paragraph of the Tax IDs subsection. The slug `/docs/tax-ids` is hardcoded in the settings UI — pick the final URL during writing and let me know if it should differ so we can update the link.

Source repos for reference

  • Settings UI: `woocommerce-pos/packages/settings/src/screens/general/index.tsx` (Tax IDs subsection)
  • Detection logic: `woocommerce-pos/includes/Services/Tax_Id_Detector.php`
  • Type registry: `woocommerce-pos/includes/Services/Tax_Id_Types.php`
  • Default write map: `woocommerce-pos/includes/Services/Tax_Id_Settings.php`
  • Writer: `woocommerce-pos/includes/Services/Tax_Id_Writer.php`

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions