Add new fields to checkout

With order extra fields you can also request additional information from a customer in storefront and show user responses in order details. This is helpful when a merchant needs to know some additional information like delivery date, delivery comments, company details and other. The responses will be shown in order details in Ecwid Control Panel.

📘

Extra fields need to be added to the source code of your website or via an app for Ecwid, that Adds custom JavaScript

The extra fields you add to checkout will be saved into a config object used by Ecwid: ec.order and ec.order.extraFields.

Adding extra field to checkout

Now let's create a new text input in the shipping address form at checkout:

// Initialize extra fields
window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

// Add a new optional text input 'How should we sign the package?' to shipping address form
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();

After an order gets placed, you will be able to get that field in the extraFields field when getting order details. Also, it will be visible to customer and merchant when viewing order details.

If your code executed successfully, these fields will be saved when a customer places their order in an Ecwid store. See Get extra fields in REST API section to access them afterwards.

Extra field attributes

An extra field at checkout has several attributes:

📘

Parameters in bold are mandatory to show the extra field at checkout. Parameters in italic are mandatory to show the extra field to customer and merchant after order is placed

options

Types of fields

There are eight types of fields: text, textarea, select, checkbox, toggleButtonGroup, radiobuttons, datetime and label:

• text is a standard text input field. It can accept any text without validation. You can use textPlaceholder attribute to add a placeholder to your extra field of type text. If value is set, this value is prefilled for the field.
• textarea is an expanded text input field.
• select adds a drop-down list of preset elements. The option elements for it have to be set in options array. If options is not set, field is transformed to text type
• checkbox is a group of checkboxes. The checkbox values have to be set in options array. If options is not set, field is transformed to text type
• toggleButtonGroup is a group of buttons. The buttons values have to be set in selectOptions array or options array. If selectOptions or options are not set, field is transformed to text type
• radiobuttons is a group of radio buttons. The radio buttons values have to be set in selectOptions array or options array. If selectOptions or options are not set, field is transformed to text type. If selectOptions or options have only one title value, field is transformed to checkbox type.
• datetime is a date picker element. It can be customized – more on that below
• label adds an element with plain not editable text. This type of field is not displayed anywhere in the order details

Checkout display section

You can add an extra field for customers in several parts of the checkout:

• shipping_address form at checkout (shipping select step). A new field will be added below the fields in the address form
• pickup_details form at checkout (shipping select step). If customer selects in-store pickup shipping method, a new field will be added below the fields in pickup details form
• shipping_methods page at the checkout process. A new field will be displayed below the available shipping methods for customer
• pickup_methods page at the checkout process. A new field will be displayed below the selected pickup method information
• payment_details form at checkout (payment select step). A new field will be added below the order comments block or billing address

If checkoutDisplaySection contains an unsupported value, the field will not be shown to a customer. If the corresponding form is not shown to customer (order comments are disabled, etc.) then the field will be ignored too, even if it's required.

Examples of other field types

Check out the examples of other field types you can add to storefront:

window.ec = window.ec || {};
ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

// The field "how_did_you_find_us" asks user about how they found the store. Drop down type
ec.order.extraFields.how_did_you_find_us = {
    'title': 'How did you find us?',
    'type': 'select',
    'required': false,
    // 'selectOptions': ['Google Ads', 'Friend told me', 'TV show', 'Other'],
    'options': [
        {'title': 'Google Ads'},
      {'title': 'Friend told me'},
      {'title': 'TV show'},
      {'title': 'Other'}
    ],
    'value': 'TV show', // Default value
    'checkoutDisplaySection': 'payment_details'
};

// 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': 'payment_details',
}

// Hidden field, which is not shown at checkout
ec.order.extraFields.my_custom_field = {
    'value': 'abcd12345'
};

Ecwid.refreshConfig && Ecwid.refreshConfig();

If your code executed successfully, these fields will be saved when a customer places their order in an Ecwid store. See Get extra fields in REST API section to access them afterwards.