Add checkout extra fields with JavaScript

With JavaScript, you have full control and flexibility over checkout extra fields. For example, you can call extra fields based on certain store/cart conditions or set up a datepicker tuned for your store's working hours and delivery schedule.

Pre-requirements

To set up checkout extra fields on the storefront and manage their content, you need:

  1. Custom application. You need a private app to be installed in your store. Without the app, it's impossible to ensure that your JS file always loads and executes on the storefront. Setup an app

  2. Access scope. Your custom app requires the following access scope: customize_storefront. Request an update

  3. Endpoint. The app requires one endpoint: customJsUrl leading to your JavaScript file. It is required for using the extra fields feature, and additionally grants access to Storefront JS API. Request an update

Set up basic checkout extra fields

Let's start with a basic text input in the shipping address form at checkout. This would be an optional request for a package sign. If customers type something in that field and place an order, you'll get the field in the extraFields field in order details. Optionally, you can make the field visible in order details for customers and in Ecwid admin.

Code example of the basic extra field
// Initialize extra fields
window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

// New optional question 'How should we sign the package?'
// visible on the shipping address page
ec.order.extraFields.wrapping_box_signature = {
    'title': 'How should we sign the package?',
    'textPlaceholder': 'Package sign',
    'type': 'text',
    'tip': 'We will put a label on a box so the recipient knows who it is from',
    'required': false,
    'checkoutDisplaySection': 'shipping_address'
};

window.Ecwid && Ecwid.refreshConfig();

The wrapping_box_signature in the example above is an internal ID for the extra field called key which can be used later on in REST API requests. You can create multiple checkout extra fields from the same JS file. However, every extra field must have its own unique key.

Checkout extra fields can be created from any store page with Ecwid object, for example, from category pages. However, you need to ensure that the function creating extra fields is not called at the checkout, as it can rewrite the customer's input.

Learn checkout extra field configuration

Ecwid offers flexible configuration settings for checkout customizations with extra fields. Build a unique UX with different field types, translations, and overrides.

Full description of available config settings for checkout extra fields:

Field
Type
Description

title

string

Title visible at the checkout above the extra field. Also appears in Ecwid admin and customer notifications (if added).

Required

titleTranslated

object translated

Available translations for the extra field title.

type

string

Extra field type that defines its functionality.

One of: text - Single-line text input. Supports placeholders and pre-defined values (default). textarea - Multiple-line text input. Supports placeholders and pre-defined values. select - Drop-down list, where customers can choose only one value. Requires options array. radio_buttons - A group of radio buttons, where customers can choose only one value. Requires options array. checkbox - A group of checkboxes, where customers can choose multiple values. Requires options array. toggle_button_group - A group of buttons, where customers can choose only one value. Requires options array. datetime - Customizable date and time picker in the form of a calendar widget on the checkout. empty - Non-editable text visible at the checkout and unavailable in customer notifications and Ecwid admin. Required

checkoutDisplaySection

string

Defines at which checkout step extra field shows to customers.

One of: email - First checkout step where customers enter their email and apply discounts. shipping_address - Second checkout step where customers enter their shipping address. pickup_details - Second checkout step where customers choose when and where they want to pick up an order. shipping_methods - Third checkout step where customers choose a shipping method. pickup_methods - Third checkout step where customers choose a pickup method. payment_details - Final checkout step where customers choose payment method and proceed to the payment.

If not specified, the extra field won't appear at the checkout, allowing you to store hidden order data or apply hidden extra charges to the order.

orderDetailsDisplaySection

string

Defines at which section the extra field shows in customer notifications and Ecwid admin.

One of: shipping_info - Shipping/pickup details. billing_info - Billing details. customer_info - Customer details. order_comments - Order comments left by a customer. hidden - Extra field is hidden from customer notifications and Ecwid admin.

If not specified, the extra field appears in the order_comments section.

textPlaceholder

string

Placeholder text for text and textarea field types. Does not affect the actual extra field value.

If not specified, the extra field won't have a placeholder.

textPlaceholderTranslated

object translated

Available translations for the text placeholder.

value

string

Default value for the extra field. Any changes by customers or your scripts on the storefront override it.

If not specified, the extra field won't have any default value.

valueTranslated

object translated

Available translations for the extra field value.

subtitle

string

Subtitle visible under the extra field name at the checkout. If not specified, the extra field won't have a subtitle.

subtitleTranslated

object translated

Available translations for the extra field subtitle.

tip

string

Extra field tip for text and textarea field types visible inside the input at the checkout.

If not specified, the extra field won't have a tip.

tipTranslated

object translated

Available translations for the extra field tip.

available

boolean

Set false to disable the extra field.

If not specified, the extra field is enabled.

showInInvoice

boolean

Set true to display the extra field in order tax invoices generated by Ecwid.

If not specified, the extra field will not be displayed in order tax invoices.

showInNotifications

boolean

Set true to display the extra field in customer emails generated by Ecwid. If true, requires orderDetailsDisplaySection.

If not specified, the extra field will not be displayed in order tax invoices.

required

boolean

Set true, to make the extra field required at the checkout. This way, customers won't be able to continue checkout until they type/select a value in the field.

If not specified, the extra field is not required at the checkout.

showForPaymentMethodIds

array of strings

Make extra field available to only some payment methods by setting a list of payment method IDs. For example, you can collect additional data only for the specific online payment method by adding it alone to the list: "showForPaymentMethodIds": ["4959-2345934622523"].

If not specified, the extra field is not limited by any payment methods.

showForShippingMethodIds

array of strings

Make extra field available to only some shipping methods by setting a list of shipping method IDs. For example, you can collect additional data only for the store pickup method by adding it alone to the list: "showForShippingMethodIds": ["4959-2345934622523"].

If not specified, the extra field is not limited by any shipping methods.

showForCountry

array of strings

Make extra field available only for some countries by setting a list of country codes. Ecwid will automatically check customer's address details to display the field. For example, "showForCountry": ["BE", "US"].

If not specified, the extra field is not limited by the customer's address details.

options

array of objects options

Defines a list of available options for select, checkbox, radio_buttons, andtoggle_button_group field types.

If not specified, the field type is transformed to text.

datePickerOptions

Defines settings and conditions for the datepicker at the checkout. For example, limited working hours or disable weekends for the calendar.

Affects only datetime extra field type.

overrides

object overrides

Defines overrides for extra fields. This setting allows setting up logic and conditional changes for extra fields on the checkout without actual JavaScript code.

translated

Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:

{
    "en": "Sample text",
    "nl": "Voorbeeldtekst"
}

Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.

Collect tips with extra fields

The select, checkbox, radio_buttons, andtoggle_button_group field types allow you to set up a drop-down list, block of radio buttons, checkboxes, or buttons for customers. Use it to ask customers for additional delivery details or to add a "Leave a tip" block to the checkout.

The options field contains an array of objects, where each option can have the following fields:

Field
Type
Description

title

string

Option name visible at the checkout.

titleTranslated

object translated

Available translations for the option name.

subtitle

string

Subtitle visble under the option name at the checkout.

subtitleTranslated

object translated

Available translations for the option subtitle.

surcharge

number

Tip/surcharge value added to the order total cost.

surchargeType

string

Defines if a surcharge applies a fixed sum or a percentage increase to the cart total. One of: ABSOLUTE - Adds a fixed sum. PERCENT - Adds percentage increase.

surchargeTaxable

boolean

Defines if surcharge/tip is taxable.

showZeroSurchargeInTotal

boolean

Defines if zero-sum surcharge shows in order total breakdown.

Set false to hide zero-sum surcharges from customers at the checkout.

surchargeShortName

Defines how the surcharge shows in the "Shopping cart" block where the order total is calculated.

surchargeShortName

Field
Type
Description

name

string

Name of the surcharge for the "Shopping cart" block.

nameTranslated

object translated

Available translations for the surcharge short name.

showSurchargePercentValue

boolean

Defines if surcharge percentage value shows next to name. Default: true. Works only with PERCENT value in surchargeType.

Code example for setting up tips
window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

ec.order.extraFields.tips = {
    'title': 'Tips',
    'type': 'toggleButtonGroup',
    'options': [
    { 
      'title': 'No tips',
    },
    {
      'title': '5%',
      'subtitle': 'Tip 5% from your order total',  
      'surcharge': 5
    },
    {
      'title': '10%',
      'subtitle': 'Tip 10% from your order total',
      'surcharge': 10
    }
  ],
  'surchargeType': 'PERCENT',
  'surchargeShortName': {
    'name': 'Tips',
    'showSurchargePercentValue': true,
    'nameTranslated': {
      'en': 'Tips',
      'nl': 'Tips'
    }
  },
  'showZeroSurchargeInTotal' : false,
  'required': true,
  'checkoutDisplaySection': 'payment_details'
};

window.Ecwid && Ecwid.refreshConfig();

Apply hidden surcharges with extra fields

With extra fields, you can apply a hidden surcharge to the order, for example, as an extra processing cost for some shipping methods.

To do so, you need to create an extra field with only 4 attributes and no others:

  • value with an internal name for the surcharge (customers won't be able to see it).

  • surchargeShortName with showSurchargePercentValue set to false.

  • options with only one option that has a surcharge value.

  • surchargeType that defines if the surcharge is calculated as a flat value (absolute) or percentage from the order total (percent).

Code example for setting up a hidden 5% surcharge
// Initialize extra fields
window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};
// Set order surcharge
ec.order.extraFields.surcharge = {
    'value': 'Custom charge',
    "options": [
    { 
        "title": "Custom charge",
        "surcharge": 5
    },
    ],
    "surchargeShortName": {
        "name": "Surcharge",
         "showSurchargePercentValue": false
    },
    'surchargeType': 'PERCENT'
}
window.Ecwid && Ecwid.refreshConfig();

This code will apply a 5% surcharge at the checkout invisible to the customers.

Advanced datepicker settings

You can customize datepicker settings with the datePickerOptions setting: set up your working hours, limit shipping dates, disable weekdays and holidays, etc.

With overrides, you can further customize datepicker settings based on the selected shipping/pickup method. For example, set up different schedules for pickup points.

datePickerOptions

Field
Type
Description

minDate

date

The earliest selectable date. Users can choose dates starting from this minimum date. Use a valid Date object.

maxDate

date

The latest selectable date. Users cannot choose dates beyond this maximum date. Use a valid Date object.

showtime

boolean

Defines if datepicker allows users to select the time. If true, time selection is enabled.

incrementMinuteBy

number

Increments for datepicker time frames (in minutes). For example, 30 means that customers can only choose from 17:00, 17:30, 18:00... on the checkout.

limitAvailableHoursWeekly

Set working hours for each day of the week. If this setting is added but some days are missing, Ecwid counts such days as disabled.

disallowDates

Disables specific ranges of date and time. For example, you can make the datepicker required and disable or limit holiday working hours.

limitAvailableHoursWeekly

Limit working hours by setting daily time ranges when the store is open. You can add several time ranges to one day if you have a lunch hour, for example.

Format: JSON object with one or several weekdays, each having an array of time ranges (also in the array format).

Code example
{
    "MON": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "TUE": [
        ["08: 30", "17: 30"]
    ],
    "WED": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "THU": [
        ["08: 30", "17: 30"]
    ],
    "FRI": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "SAT": [
        ["08: 30", "17: 30"]
    ],
    "SUN": [
        ["10: 00", "14: 00"]
    ]
}

disallowDates

Disable specific dates or date ranges to close the store for holidays, for example.

Format: JSON array with one or several arrays, each having a date or datetime range formatted to the "YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD HH:MM:SS" string.

Code example
{
    "disallowDates": [
        // Disallow placing/shipping orders for the specific day after 3 PM.
        ["2024-04-25 15:00:00", "2024-04-25 23:59:59"],
        // Close the store for 3 days.
        ["2024-04-26 00:00", "2024-04-29 00:00"]
    ]
}

overrides

Field
Type
Description

conditions

object conditions

Conditions for the override. When conditions are met, override happens automatically.

fieldsToOverride

Set up the datePickerOptions object with a new logic inside. When conditions are met, it will override defult datepicker behavior.

conditions

Field
Type
Description

shippingMethod

string

Selected shipping method name, for example. 'Pickup at North st'

Code example for advanced datepicker settings and overrides
window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

// Add pickup time selection for customer
ec.order.extraFields.ecwid_pickup_time = {
  'title': '_msg_ShippingDetails.pickup.customer_header',
  'required': true,
  'type': 'datetime',
  'checkoutDisplaySection': 'pickup_details',
  'orderDetailsDisplaySection': 'order_comments',
  'datePickerOptions': {
    minDate: new Date(new Date().getTime() + 2*60*60*1000), // Add 2h order preparation time
    maxDate: new Date(2020, 12, 31),
    showTime: true,
    autoClose: false,
    use24hour: true,
    incrementMinuteBy: 30,
    limitAvailableHoursWeekly: {
      'MON': [
        ['08:30', '13:30'],
        ['14:00', '17:30']
      ],
      'TUE': [
        ['14:00', '17:30']
      ],
      'WED': [
        ['01:00', '13:30']
      ],
      'THU': [
        ['14:00', '23:30']
      ],
      'FRI': [
        ['14:00', '17:30']
      ]
    }
  },
  'overrides': [
    {
      'conditions': {
        'shippingMethod': 'Pickup at North st'
      },
      'fieldsToOverride': {
        'datePickerOptions': {
          minDate: new Date(new Date().getTime() + 2*60*60*1000),
          maxDate: new Date(2024, 12, 31),
          showTime: true,
          autoClose: false,
          use24hour: true,
          incrementMinuteBy: 30,
          limitAvailableHoursWeekly: {
            'MON': [
              ['08:30', '13:30'],
              ['14:00', '17:30']
            ],
            'TUE': [
              ['14:00', '17:30']
            ]
          },

          // Disallow specific dates
          'disallowDates': [
            // Disallow same-day pickup after 3PM
            ['2024-04-25 15:00:00', '2024-04-25 23:59:59'],

            // Disallow specific time interval (e.g. if you're booked at that time)
            ['2024-04-26 08:30', '2024-04-26 10:00']
          ]
        }
      }
    },
    {
      'conditions': {
        'shippingMethod': 'Pickup at East st'
      },
      'fieldsToOverride': {
        'datePickerOptions': {
          minDate: new Date(new Date().getTime() + 2*60*60*1000),
          maxDate: new Date(2024, 12, 31),
          showTime: true,
          autoClose: false,
          use24hour: true,
          incrementMinuteBy: 30,
          limitAvailableHoursWeekly: {
            SAT: [
              ['08:30', '13:30'],
              ['14:00', '17:30']
            ],
            SUN: [
              ['14:00', '17:30']
            ]
          }
        }
      }
    },
    {
      'conditions': {
        'shippingMethod': 'Pickup at West st'
      },
      'fieldsToOverride': {
        'available': false
      }
    }
  ]
};

Ecwid.refreshConfig && Ecwid.refreshConfig();

Data size limits of extra fields

When using checkout extra fields, do not exceed the following limits:

  • The length of a specific setting in the JavaScript configuration of an extra field must not exceed 255 characters.

  • The total data size saved as extra fields for one order must not exceed 8Kb.

Show extra fields in invoices and emails

You can add order extra fields to customer notifications manually. The field could be optional (the code will check if it exists in the order), but it must have a title and orderDetailsDisplaySection value (any value other than hidden). Read more on the customization of customer emails.

Code example for adding an extra field to invoices/emails
<#list order.extraFields as extraField>
    <#if extraField.title?has_content && extraField.orderDisplaySection?has_content>
        ${extraField.title}: ${extraField.value}
    </#if>
</#list>

Manage checkout extra fields with REST API

With the JavaScript code, you can dynamically call checkout extra fields. However, if you need the same extra field to always appear at the checkout, it is easier to set up with REST API once.

Find a list of available methods below.

Last updated

Was this helpful?