Custom Fields

Custom Fields allow you to collect additional information from customers during checkout. This data can be used for personalization, fulfillment requirements, regulatory compliance, or marketing purposes.

Use Sparingly

Each additional field adds friction to checkout. Only collect information that's truly necessary. Every required field can reduce conversion by 1-3%.

Available Field Types

Text Fields

Text Input Types

Single-line text — Short responses
Multi-line textarea — Longer responses like instructions
Email — With validation
Phone number — With formatting
Number — Numeric input only

Selection Fields

Selection Types

Dropdown select — Single choice from a list
Radio buttons — Single choice, all options visible
Checkboxes — Multiple selections allowed
Toggle switch — Yes/no binary choice

Special Fields

Special Input Types

Date picker — Calendar selection
Time picker — Time slot selection
File upload — Document/image uploads
Signature — Digital signature capture

Common Use Cases

Delivery Instructions

Delivery Instructions Field

{
  "field": {
    "id": "delivery_instructions",
    "type": "textarea",
    "label": "Delivery Instructions",
    "placeholder": "Gate code, leave at door, etc.",
    "required": false,
    "max_length": 200,
    "placement": "shipping_address"
  }
}

Age Verification

Age Verification Field

{
  "field": {
    "id": "age_verification",
    "type": "date",
    "label": "Date of Birth",
    "required": true,
    "validation": {
      "min_age": 21,
      "error_message": "You must be 21 or older to purchase this product"
    },
    "conditional": {
      "show_when": "cart_contains_tag",
      "tag": "age-restricted"
    }
  }
}

Business/Tax Information

Business Fields

{
  "fields": [
    {
      "id": "company_name",
      "type": "text",
      "label": "Company Name",
      "required": false
    },
    {
      "id": "vat_number",
      "type": "text",
      "label": "VAT Number",
      "required": false,
      "validation": "vat",
      "conditional": {
        "show_when": "country_in",
        "countries": ["DE", "FR", "IT", "ES", "NL"]
      }
    }
  ]
}

Product Personalization

Personalization Fields

{
  "field": {
    "id": "engraving_text",
    "type": "text",
    "label": "Engraving Text",
    "placeholder": "Enter text to engrave (max 20 characters)",
    "required": true,
    "max_length": 20,
    "conditional": {
      "show_when": "cart_contains_product",
      "product_ids": ["ring-001", "bracelet-002"]
    }
  }
}

Setting Up Custom Fields

Create New Field

Go to CheckoutOS → Checkout Extensions → Custom Fields → Add Field.

Select Field Type

Choose the appropriate input type for your data.

Configure Properties

Set label, placeholder, validation rules, and requirements.

Set Conditions (Optional)

Define when the field should appear based on cart or customer.

Choose Placement

Select where in checkout the field appears.

Map Data Destination

Configure where the collected data is stored and sent.

Validation Options

Ensure data quality with built-in validation:

Validation Configuration

{
  "validation": {
    "required": true,
    "min_length": 2,
    "max_length": 100,
    "pattern": "^[A-Za-z ]+quot;,
    "pattern_message": "Only letters and spaces allowed",
    "custom_validator": "validate_phone_number",
    "validate_on": "blur"
  }
}

Conditional Display

Show fields only when relevant conditions are met:

Conditional Logic

{
  "conditions": {
    "logic": "AND",
    "rules": [
      {
        "type": "cart_total",
        "operator": "greater_than",
        "value": 100
      },
      {
        "type": "shipping_country",
        "operator": "in",
        "value": ["US", "CA"]
      }
    ]
  }
}

Data Handling

Custom field data can be sent to multiple destinations:

Data Destinations

Shopify order attributes — Visible in order admin
Shopify order notes — Concatenated into notes field
Shopify metafields — Structured data storage
Webhooks — Send to external systems
Email — Include in order confirmation
Fulfillment apps — ShipStation, etc.

PII Handling

If collecting sensitive personal information (SSN, health data, etc.), ensure your data handling complies with applicable regulations (GDPR, CCPA, HIPAA). Consider encryption and access controls.

Styling Custom Fields

Field Styling

{
  "styling": {
    "label_position": "above",
    "label_size": "small",
    "input_style": "outlined",
    "error_style": "inline",
    "help_text_position": "below",
    "required_indicator": "*",
    "group_fields": true,
    "group_title": "Additional Information"
  }
}

Best Practices

Optimization Tips

Minimize required fields — Every field adds friction
Use conditional display — Only show relevant fields
Provide clear labels — Users should know why you're asking
Use appropriate field types — Date pickers for dates, dropdowns for fixed options
Set sensible defaults — Pre-fill when possible
Test on mobile — Ensure fields work well on touch devices