# Commerce Customer Fields

Help4 Commerce uses one typed customer-field catalog across checkout, customer accounts, staff administration, orders, imports, exports, and WordPress privacy tools.

## Create fields

Open **Commerce > Customer Fields**. Every field has a stable key, label, group, type, placement, sort order, and status. Available types include text, long text, email, phone, URL, number, date, time, date and time, color, range slider, select, radio choices, checkbox, on/off toggle, multiple choices, country, and calculated value.

Use placements to decide whether a field appears in checkout, the customer account form, staff administration, or any combination. Enable **Customer editable** before an account field can be changed by a signed-in customer.

Quick-start packs create editable business-profile, service-intake, delivery-preference, or membership-onboarding fields without overwriting existing keys. Duplicate creates an inactive copy for safe editing. JSON export and import move definitions between sites without moving customer values.

## Validation and display rules

Fields can be required and can set minimum or maximum lengths, numbers, number steps, selection counts, dates, and date/time values. Select, radio, and multiple-choice fields use an explicit value allowlist. Up to five conditional rows can use AND or OR matching across equality, containment, emptiness, numeric comparison, and one-of rules.

Product IDs, product-type slugs, WordPress roles, countries, and minimum or maximum cart subtotals can limit fields to the relevant audience. Conditions and targeting are enforced on the server as well as in the browser. Unknown submitted keys are discarded.

Condition values can also reference another live customer field by its stable key in braces. For example, a rule with **Requested seats**, **is greater than**, and `{included_seats}` compares the two submitted values in real time and repeats the same comparison during server validation. Exact tokens only are resolved; arbitrary expressions are never executed. This supports confirmation flows, quote thresholds, and branching intake without exposing values in the field definition.

Autocomplete tokens improve browser autofill. Full, half, one-third, and two-thirds control widths use a responsive 12-column grid and collapse to one column on small screens.

## Calculated values

Calculated fields display a read-only result derived from other numeric customer fields. Reference a stable field key with braces, such as `round({seat_count} * {seat_rate}, 2)`. Formulas support parentheses, `+`, `-`, `*`, `/`, and the allowlisted functions `abs`, `ceil`, `floor`, `round`, `min`, and `max`. Display precision, prefix, and suffix are separate from the stored numeric value.

The formula engine is a bounded parser and never uses dynamic code execution. It rejects unknown references, self-references, dependency cycles, unsupported functions, invalid numeric input, non-finite results, and division by zero. A calculated field derived from a sensitive field must also be sensitive. Saved field keys are immutable, and a referenced source cannot be archived, deactivated, or newly protected until its active dependents are updated. If audience targeting intentionally removes a source from a checkout or account context, its optional calculated output is skipped instead of blocking the form.

Checkout and account forms update non-sensitive results while customers type. That browser result is for immediate feedback only: calculated fields do not render a named form input, submitted values for their keys are discarded, and the server recomputes every result in dependency order before storage or an order snapshot. Sensitive formulas are never placed in browser markup and are calculated only on the server.

Calculated definitions, formulas, display settings, and dependencies are preserved by duplication and JSON import/export. Imports validate the complete dependency graph before writing any definition, so an invalid catalog cannot leave a partially imported formula chain.

## Sensitive values

Set sensitivity to **Sensitive** for values that must receive the strongest handling. Sensitive values:

* have no plaintext default;
* are encrypted at rest with Sodium secretbox or OpenSSL AES-256-GCM;
* are never prefilled into checkout, account, or staff HTML;
* are omitted from customer search, routine CSV exports, REST customer lists, processor metadata, and order snapshots;
* remain available to the WordPress personal-data exporter and eraser.

Leaving an existing sensitive field blank in the account or staff editor preserves its encrypted value. Supplying a new value replaces it. Optional sensitive fields also show an explicit removal checkbox, and removal commits in the same transaction as other customer-field updates.

## Customer account form

Place `[h4_customer_account]` on a signed-in account page. The shortcode groups customer-editable account fields, renders accessible controls and conditional behavior, verifies saves with a nonce, and maps the current WordPress user to the Help4 Commerce customer record by email.

## Imports and exports

Customer JSON imports accept a `customer_fields` object keyed by the field catalog. CSV exports include a `customer_fields_json` column containing only fields marked exportable and not sensitive. Invalid choices and malformed typed values are rejected rather than stored.

## Extension hooks

* `h4bs_commerce_customer_field_definitions` filters normalized definitions for a placement and context.
* `h4bs_commerce_customer_field_validated_values` filters validated and server-calculated values after built-in allowlist and type validation.
* `h4bs_commerce_customer_fields_saved` runs after an atomic value transaction commits and receives the cleared keys as its fourth argument.
* `h4bs_commerce_customer_field_definition_saved` runs after a definition is created or updated.
* `h4bs_commerce_customer_field_archived` runs after a field is archived.
* `h4bs_commerce_customer_field_definitions_imported` runs after a portable catalog import.

Extensions should keep their field keys stable and must not expose sensitive values through logs, browser markup, exports, or remote requests.
