Surface-by-surface tutorial

Each surface below shows how to (1) create the field in admin, (2) verify it renders on the storefront, and (3) confirm the value persists in DB.

1. Product Detail Page — engraving text field

Use case: jewelry / personalisation; “Custom engraving text” appears on PDP, value follows the item through cart → order → email → invoice.

Create field

1. Admin → CDA Custom Fields → Fields → Add New Field
2. Code: engrave_text · Label: Custom engraving text · Type: Text Field
3. Applies To: Product — Product detail page (per-product bindings)
4. Required: Yes · Sort Order: 10 · Placeholder: Up to 20 characters
5. Product Page Bindings section: pick one or more attribute sets (e.g. Top, Bottom), or paste SKUs into the Include list.
6. Save.

Storefront test

• Open any product in the bound attribute set.
• Scroll to the Add-to-Cart section — the engrave text field appears as “Custom engraving text” with the placeholder set in step 4.
• Fill in Veronica '26, select size/color, click Add to Cart.

Verify persistence

SELECT field_code, value
FROM cda_custom_field_quote_value
WHERE quote_id = <your-cart-id>;

After place-order, the same value lands in cda_custom_field_order_value keyed by order_id. It also shows in the cart line-item as Custom engraving text: Veronica '26 via Magento’s native additional_options rendering.

2. Cart Page — gift message field

Use case: customer enters a gift message that applies to the whole order (vs PDP fields which are per-item).

Create field

1. Add new field
2. Code: cart_gift_note · Label: Gift message for this cart · Type: Text Area · Applies To: Cart — Shopping cart page · Placeholder: e.g. Happy Birthday Mom!
3. Save.

Storefront test

• Add any product to cart, visit /checkout/cart.
• An “Order Information” section appears with a textarea.
• Type a message, click Update Shopping Cart.

Verify persistence

SELECT quote_id, value FROM cda_custom_field_quote_value
WHERE field_code = 'cart_gift_note';

3. Checkout Shipping step — multi-field engraving

Use case: collect engraving details during checkout instead of per-product (better UX for a single-item shipping engraving service).

Create three fields

Code	Label	Type	Required
engrave_text	Text to Engrave	Text Field	Yes
engrave_font	Font Style	Dropdown (Script, Serif, Sans Serif, Block Capitals)	Yes
engrave_position	Placement	Radio (Front, Back, Side)	No

All three: Applies To = Checkout — Shipping step.

Storefront test

• Add product → checkout. Shipping step renders the 3 CDA fields under the shipping address form.
• Fill in, pick shipping method, click Next.
• Side-channel JS POSTs values to /cda_customfields_checkout/checkout/save immediately on click.

Verify persistence

SELECT field_code, value FROM cda_custom_field_quote_value
WHERE quote_id = <your-cart-id> AND field_code LIKE 'engrave_%';

4. Customer Address Book — per-address fields

Use case: B2B / international stores need per-address VAT ID or delivery instructions that differ between billing and shipping.

Create fields

Code	Label	Type
address_vat_id	VAT / Tax ID	Text Field
address_delivery_instructions	Delivery Instructions	Text Area

Applies To = Customer — Address book (per-address).

Storefront test

• Log in as a customer → My Account → Address Book → Edit Address
• Scroll below the standard fields — the two CDA fields appear, splicing in via AddressEditPlugin::afterToHtml.
• Fill in, click Save Address.

Verify persistence

SELECT address_id, field_code, value FROM cda_custom_field_address_value;

Each address has its OWN values — billing’s VAT ID can differ from shipping’s.

5. Contact Us form — inquiry subject

Use case: classify support inquiries before they reach the inbox.

Create field

• Code: contact_subject · Label: Subject of your inquiry · Type: Text Field · Applies To: Contact Us form

Storefront test

• Visit /contact, fill in Name / Email / Comment + the new Subject field.
• Click Submit.

Verify persistence

1. Database audit log:

SELECT submission_id, submitter_email, field_code, value, created_at
FROM cda_custom_field_contact_value
ORDER BY created_at DESC LIMIT 5;

2. Admin email also appends:

--- Additional Information ---
Subject of your inquiry: <whatever the customer typed>

…to the bottom of the standard contact email body, so the merchant sees it in the inbox without needing a custom email template.

6. Product Review — verified purchase flag

Use case: customer self-declares whether they bought the product (vs reading from order history; useful for “verified” badges).

Create field

• Code: review_purchase_verified · Label: Verified purchase? · Type: Yes / No · Applies To: Product Review form

Storefront test

• Open any product, scroll to Reviews tab, click Add Your Review.
• The new dropdown appears alongside Nickname / Summary / Review.

Verify persistence

SELECT review_id, field_code, value FROM cda_custom_field_review_value;

7. Newsletter — first name

Use case: ESPs (Mailchimp, Klaviyo) want first name for personalised subject lines. Magento’s stock newsletter is just an email field.

Create field

• Code: newsletter_first_name · Label: Your first name · Type: Text Field · Applies To: Newsletter signup

Storefront test

• Visit any storefront page, scroll to the footer newsletter block.
• Type email + first name, click Subscribe.

Verify persistence

SELECT s.subscriber_email, v.field_code, v.value
FROM newsletter_subscriber s
JOIN cda_custom_field_subscriber_value v ON v.subscriber_id = s.subscriber_id
ORDER BY s.subscriber_id DESC LIMIT 5;

8. Wishlist — priority

Use case: customer flags items by “must-have” vs “nice-to-have” priority for their own organisation; merchants can then surface high-priority wishes in re-engagement emails.

Create field

• Code: wishlist_priority · Label: Priority · Type: Dropdown · Applies To: Wishlist — per-item notes
• Options: low (Low), med (Medium), high (High — top of my list)

Storefront test

• Log in as customer, visit any PDP. The “Wishlist Notes” fieldset renders with the Priority dropdown.
• Pick “High”, click Add to Wish List.

Verify persistence

SELECT wishlist_item_id, field_code, value
FROM cda_custom_field_wishlist_item_value
ORDER BY value_id DESC LIMIT 5;

9. Admin Order View — see all values

For any order placed, navigate to Admin → Sales → Orders → <Order #>. Scroll past Payment & Shipping Method — a Custom Fields section displays every CDA value associated with the order in a 3-column table (Field name / Code / Value).

This block always shows, regardless of theme.

10. Transactional emails — order confirmation

CDA values from cda_custom_field_order_value are appended to the sales_email_order_items, sales_email_order_invoice_items, sales_email_order_shipment_items, and sales_email_order_creditmemo_items layout handles, after the items block. No template forking needed — values are listed as Label: Value pairs above the order grand total.

11. PDF Invoice + Credit Memo

The pdf.xml <totals> mechanism includes CDA values as a totals row above the grand total. Native to Magento’s PDF generator — no font/asset configuration required.

(Shipment PDFs intentionally don’t render totals in Magento core; CDA values on shipments are visible in admin shipment view but not in the shipment PDF. On the roadmap.)