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.

Creating new fields at checkout

Init and display your custom field at checkout

// Initialize extra fields
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'


The extra fields you add to checkout will be saved into a config object used by Ecwid: ec.order and ec.order.extraFields. Start by initializing the objects using the code on the right.

Now that we’ve initialized the extra fields object, we can create a new text input in the shipping address form at checkout. See example on the right.

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.

Extra field attributes

An extra field at checkout has several attributes:

titlestringTitle of a new field. It prompts user to enter the value
checkoutDisplaySectionstringAccepts several values: shipping_address, pickup_details, shipping_methods, pickup_methods, payment_details. More on this below
orderDetailsDisplaySectionstringDefines where the extra field will be shown to customer and merchant. Supported values: shipping_info, billing_info, customer_info, order_comments. If an unsupported value is used, the field will be hidden from customer and merchant
valuestringDefault value used to prefill the extra field’s value for user
typestringAccepts several values: text, select, datetime. Default is text. More on this below
tipstringShow a tip for filling the field under the input
availablebooleanIf true, the field is shown and saved as an extra field. If false, the field completely ignored. true is default
textPlaceholderstringA text placeholder for text input field
selectOptionsArray<string>Several options to choose from the select field. If selectOptions is not set, field is transformed to text type
requiredbooleantrue if required, false otherwise

Types of fields

There are three types of fields: text, select, datetime

  • 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.

  • select is a drop down element. The options for it have to be set in selectOptions array. If selectOptions is not set, field is transformed to text type

  • datetime is a date picker element. It can be customized – more on that below

  • label is a plain text element. It cannot be shown 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 on the right.

Various extra fields added to checkout examples

// 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'],
    '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'


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.

We use cookies and similar technologies to remember your preferences, measure effectiveness of our campaigns, and analyze depersonalized data to improve performance of our site. By choosing «Accept», you consent to the use of cookies.