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:

FieldTypeDescription
titlestringTitle of a new field. It prompts user to enter the value
checkoutDisplaySectionstringAccepts several values: email, shipping_address, pickup_details, shipping_methods, pickup_methods, payment_details. If the field is missing or an unsupported value is used, the field will be hidden from customer and merchant
orderDetailsDisplaySectionstringDefines where the extra field values will be shown to customer and merchant. Supported values: shipping_info, billing_info, customer_info, order_comments, hidden. More on this in Show extra fields in an order section.
valuestringDefault value used to prefill the extra field's value for user
subtitlestringSubtitle of a new field
typestringAccepts several values: text, textarea, select, checkbox, toggle_button_group, radio_buttons, datetime, empty. Default is text. More on this below
tipstringShow a tip for filling the field under the input (ignored if type is textarea or checkbox)
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 and textarea input fields
showInInvoicebooleanIf not specified the default value is false. Set true to show extra field in order invoices.
showInNotificationsbooleanIf not specified the default value is false. Set true to show extra field in order emails. orderDetailsDisplaySection sets the part where the extra field will appear.
selectOptionsArray<string>Depricated, use options instead. Several options to choose from the select field, checkbox, radio_buttons or toggle_button_group buttons. If selectOptions is not set, field is transformed to text type. If selectOptions or options have only one title value, radiobuttons field is transformed to checkbox type.
optionsArray<options>Several options to choose from the select field, checkbox, radio_buttons or toggle_button_group buttons. If options is not set, field is transformed to text type
requiredbooleanIf not specified the default value is false. Set true to prevent continuing checkout if an extra field is ignored by customers.
showForPaymentMethodIdsArray of stringsDetects whether an extra field should be visible for some certain payment methods only. Contains payment method IDs for which an extra field should be visible. E.g. "showForPaymentMethodIds": ["4959-1595934622523","4959-2345934622523"].
showForShippingMethodIdsArray of stringsDetects whether an extra field should be visible for some certain shipping methods only. Contains shipping method IDs for which an extra field should be visible. E.g. "showForShippingMethodIds": ["4969-1534934622531","4969-2348834622511"].
showForCountryArray of stringsDetects whether an extra field should be visible for certain countries only. Contains ISO country codes for which an extra field should be visible. E.g. "showForCountry": ["BE", "US"].
datePickerOptions<DatePickerOptions>Additional options for date picker.
overrides<Overrides>An array of objects representing the overrides.

📘

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

FieldTypeDescription
titlestringselect field, checkbox, radio_buttons or toggle_button_group button option title
subtitlestringtoggle_button_group button option subtitle
surchargenumberadds a surcharge to the cart when an option is chosen. More on that here: Add surcharge to extra fields' values

DatePickerOptions

FieldTypeDescription
minDatedateThe earliest selectable date. Users can choose dates starting from this minimum date. Use a valid Date object.
maxDatedateThe latest selectable date. Users cannot choose dates beyond this maximum date. Use a valid Date object.
showtimebooleanenable/disable time selection.
incrementMinuteBynumberSets selectable time frames in minutes.
limitAvailableHoursWeekly<limitAvailableHoursWeekly>Allows to set weekdays and timeframes for working hours.
disallowDatesarrayDisallow specific time ranges

limitAvailableHoursWeekly

FieldTypeDescription
MONarrayAn array specifying the available hours for Monday. Each element represents a time range with a start and end time. Example:
'MON': [ ['08:30', '13:30'], ['14:00', '17:30'] ]
TUEarrayAn array specifying the available hours for Monday. Each element represents a time range with a start and end time.
WEDarrayAn array specifying the available hours for Tuesday. Each element represents a time range with a start and end time.
THUarrayAn array specifying the available hours for Thursday. Each element represents a time range with a start and end time.
FRIarrayAn array specifying the available hours for Friday. Each element represents a time range with a start and end time.
SATarrayAn array specifying the available hours for Saturday. Each element represents a time range with a start and end time.
SUNarrayAn array specifying the available hours for Sunday. Each element represents a time range with a start and end time.

disallowDates

FieldTypeDescription
disallowDatesarrayAn array specifying a disallowed time interval. The start and end elements represent the start and end date and time for the disallowed interval. Example:
// Disallow specific time interval (e.g. if you're booked at that time)
'disallowDates': [ ['2023-03-30 18:00', '2023-03-31 20:30'] ]

Also, a specific date or a part of working hours can be disallowed:

'disallowDates': ['2017-04-25']

['2017-04-25 15:00:00', '2017-04-25 23:59:59']

Overrides

FieldTypeDescription
conditions<Conditions>Conditions for the override.
fieldsToOverride<FieldsToOverride>Determines which fields should be overridden.

Example:

'fieldsToOverride': {

<DatePickerOptions>

}

Conditions

FieldTypeDescription
shippingMethodstringShipping method name, e.g. 'Pickup at North st'

Types of fields

There are eight types of fields: text, textarea, select, checkbox, toggle_button_group, radio_buttons, datetime and empty:

  • 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
  • toggle_button_group 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
  • radio_buttons 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
  • empty 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': 'order_comments',
  'datePickerOptions': {
    minDate: new Date(new Date().getTime() + 2*60*60*1000), // Add order preparation (fulfillment) 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(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']
            ]
          },

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

            // Disallow specific time interval (e.g. if you're booked at that time)
            ['2017-04-26 08:30', '2017-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(2020, 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
      }
    }
  ]
};

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