Adding Additional Checkout Fields for Delivery Methods

  • Published on Dec 16, 2025
  • 4 minute(s) read
Prev Next

This guide explains how to add extra fields (e.g., delivery accessorials, instructions) shown below the selected delivery method during checkout. Configuration is done via metadata and delivery method settings—no code changes are required.

Overview

  • You define a Field Set (via Custom Metadata) describing which shipment fields to show and how.
  • You reference that Field Set on a Delivery Method using the Additional_Checkout_Fields__c attribute.
  • The system loads those fields dynamically and renders them under the selected delivery method with validation and persistence.

Note: This is a managed package feature; administrators configure metadata and delivery methods as described below. The internal implementation details are abstracted and not required for configuration.

Prerequisites

  • You have an active Delivery Method set up in Delivery_Method__mdt.
  • You know which shipment fields (on Shipment__c) you want customers to complete.
  • You have admin access to create and edit Custom Metadata in your org.

Step 1: Create a Field Set Definition

Create a new Field Set Definition in Custom Metadata to group the additional fields.

  1. Go to Setup → Custom Metadata Types.
  2. Find Field_Set_Definition__mdt and click "Manage Records".
  3. Click "New" and fill out:
    • Label: A human-readable name (e.g., "Freight Accessorials").
    • QualifiedApiName: A unique API name (e.g., Freight_Accessorials).
    • Type: Choose the type relevant to checkout field sets (consult your environment’s available types). If unsure, leave as configured for generic field sets.
    • Default__c: Leave unchecked unless this is intended as the default for its type.
    • Optional: Sorting fields – If you want items sorted or tied to an object type.
  4. Save the record.

Notes:

  • Remember the QualifiedApiName; you will reference it from the Delivery Method.
  • The feature uses caching; changes may require a UI refresh or cache clear (see Troubleshooting).

Step 2: Add Field Set Items (Fields to Display)

Define the fields that will appear under the selected delivery method.

  1. In Custom Metadata Types, open Field_Set_Item__mdt → "Manage Records" → "New".
  2. For each field you want to display:
    • Label: The label shown to users (optional; system can generate when omitted).
    • QualifiedApiName: Unique per item (e.g., Liftgate_Service).
    • Field_Set_Definition__c: Lookup to the Field Set Definition created in Step 1.
    • Field__c: Select the Shipment__c field to render (e.g., Requires_Liftgate__c).
    • Active__c: Check to include this field.
    • Applicable_Categories__c: Optional filtering tags.
    • Value_Provider__c: Optional provider class if the field’s value is computed.
    • Optional display metadata (order, button label, inline help text) depending on your org’s metadata model.
  3. Repeat for all desired fields.

Constraints and limits:

  • Up to 15 fields per update block are supported by the deployment logic.
  • Do not exceed UI space; use coherent grouping and help text.

Step 3: Reference the Field Set on a Delivery Method

Bind the Field Set to the Delivery Method so it appears at checkout:

  1. Open Delivery_Method__mdt → "Manage Records".
  2. Edit the Delivery Method you want to augment.
  3. Set Additional_Checkout_Fields__c to the QualifiedApiName of your Field Set Definition (from Step 1), e.g., Freight_Accessorials.
  4. Ensure the Delivery Method is Active and visible for the target network and pricebooks.
  5. Save.

Technical behavior:

  • The system reads Additional_Checkout_Fields__c on the delivery method, loads the corresponding Field Set, and renders those fields under the selected delivery method.

What Customers See

  • On the shipping step, when they select a delivery method, a footer area appears with pop-over buttons for additional input.
  • Clicking a button opens a form showing the configured shipment fields.
  • Required field validation is enforced; customers must complete required fields before proceeding.

UI details:

  • A loading indicator appears during method load or refresh.
  • Help text indicates validation issues when required fields are missing.
  • Pop-over size adapts to the number of columns in the field form.
  • Only changed values are saved when you click Save.

Validation and Save Flow

  • The component validates via reportValidity(); missing required fields display inline help or a generic message.
  • Only changed values are submitted back (optimization).
  • Values update the shipment record fields as part of the shipping method selection flow.

Troubleshooting

  • Fields not appearing:

    • Verify Additional_Checkout_Fields__c matches the exact QualifiedApiName of the Field Set Definition.
    • Ensure Field_Set_Item__mdt.Active__c is checked for each item.
    • Confirm Delivery Method is active for the current network and pricebooks.

  • Cache appears stale (old or missing fields):

    • The service caches Field Sets. Trigger a UI refresh (e.g., re-open the checkout step or use the component’s reload()), or clear org cache per your environment procedures.

  • Validation not enforcing:

    • Ensure the underlying Shipment__c field is marked required in the Field Set Item configuration or enforced by the field component.

  • Currency display issues:

    • For multi-currency orgs, prices convert based on Delivery_Method__mdt.Currency_Iso_Code__c; verify that field is set appropriately.

Best Practices

  • Keep field labels concise and domain-specific.
  • Use inline help text to guide customers on what to enter.
  • Limit the number of fields to what’s essential (ideally ≤ 6) to avoid UI clutter.
  • Group related inputs into a single pop-over when possible.

Example Configuration

  • Field Set Definition:

    • Label: "Freight Accessorials"
    • QualifiedApiName: Freight_Accessorials

  • Field Set Items:

    • Liftgate_Service → Shipment__c.Requires_Liftgate__c (Active)
    • Inside_Delivery → Shipment__c.Inside_Delivery__c (Active)
    • Delivery_Instructions → Shipment__c.Delivery_Instructions__c (Active)

  • Delivery Method:

    • Label: "Freight"
    • Additional_Checkout_Fields__c: Freight_Accessorials
    • Active and visible for the target network/pricebooks

Once saved, these fields render below the Freight method and must be completed if required.