Checkout extra fields

Checkout extra fields are the core of Checkout API. With extra fields, you can request additional data from customers and save it to order details, which opens new opportunities for expanding checkout functionalities, like custom referral/loyalty tracking, delivery comments, etc.

Choose one of two ways of adding extra fields to checkout: use a no-code solution in Ecwid admin that supports most of the functionality or control these fields dynamically with custom JavaScript code.

With JavaScript, you have more control and flexibility with extra fields. For example, you can call extra fields based on certain store/cart conditions or precisely set up the datepicker type. We will talk about JavaScript way here.

Pre-requirements

To set up checkout extra fields on the storefront and manage their content, you need a custom app and an endpoint hosted on your side.

  1. Custom application. If you don't have a custom app yet, please refer to this instruction.
  2. Access scopes. The app requires the following access scope: customize_storefront.
  3. Endpoints. The app requires one endpoint:
    1. customJsUrl - link to your JavaScript file, required to use extra fields, also grants access to Storefront JS API.

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:

// 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();

You can add one or several extra fields from any store page where the Ecwid object is available.

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:

FieldTypeDescription
titlestringExtra field title. It is visible on the checkout, in customer notifications, and in Ecwid admin.

Required setting.
titleTranslatedobjectTranslations for the extra field title.

Optional setting.
typestringExtra field type that defines its functionality. Available values:
text - Single-line text input. Supports placeholders and pre-defined values. Default field type.
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 displayed on the storefront, but disabled in customer notifications or Ecwid admin.

Required setting.
checkoutDisplaySectionstringDefines at which checkout step extra field shows to customers. Available values:
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

Required setting.
orderDetailsDisplaySectionstringDefines at which section the extra field shows in customer notifications and Ecwid admin. Available values:
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.

Optional setting. If not specified, an extra field shows in the order comments section.
textPlaceholderstringPlaceholder text for text and textarea field types. This is not an actual value of the field.

Optional setting. If not specified, the field won't have a placeholder.
textPlaceholderTranslatedobjectTranslations for the extra field placeholder text.

Optional setting.
valuestringDefines the default value for the extra field when it's created. Any changes by customers or your scripts on the storefront override it.

Optional setting. If not specified, the default value will be empty.
valueTranslatedobjectTranslations for the default value of the extra field.

Optional setting.
subtitlestringExtra field subtitle. It is displayed under the extra field name on the storefront.

Optional setting. If not specified, the field won't have a subtitle.
subtitleTranslatedobjectTranslations for the extra field subtitle.

Optional setting.
tipstringExtra field tip for text and textarea field types. It shows under the input.

Optional setting. If not specified, the field won't have a tip displayed.
tipTranslatedobjectTranslations for the extra field tip text.

Optional setting.
availablebooleanDefines if the field is enabled. If true (default), the field is displayed on the storefront. If false, the field is disabled.

Optional setting. If not specified, an extra field is enabled.
showInInvoicebooleanDefines if the field shows in order tax invoices generated by Ecwid. If true, the field is displayed. If false (default), the field is not displayed.

Optional setting. The field will not be displayed in order tax invoices if not specified.
showInNotificationsbooleanDefines if the field is displayed in order receipts and customer emails generated by Ecwid. If true, the field is displayed in receipts and emails. If false (default), the field is not displayed in receipts and emails.

Optional setting. The field will not be displayed in order receipts and customer emails if not specified. The true value requires orderDetailsDisplaySection to have a value.
requiredbooleanDefines if the field is required or can be skipped on the checkout. If true, customers can't continue with an order until they type/select a value in the field. If false (default), customers can skip the field and continue shopping without interacting with the extra field.

Optional setting. If not specified, the field is not required on the checkout.
showForPaymentMethodIdsArray of stringsDefines a list of payment method IDs for which the field should be visible, for example, "showForPaymentMethodIds": ["4959-1595934622523","4959-2345934622523"].

Optional setting. If not specified, the field will be visible for all payment methods available on the storefront.
showForShippingMethodIdsArray of stringsDefines a list of shipping method IDs for which the field should be visible, for example, "showForShippingMethodIds": ["4969-1534934622531","4969-2348834622511"].

Optional setting. If not specified, the field will be visible for all shipping methods available on the storefront.
showForCountryArray of stringsDefines a list of country codes for which the field should be visible, for example, "showForCountry": ["BE", "US"].

Optional setting. If not specified, the field will be visible for all countries.
optionsArray{options}Defines a list of available options for select, checkbox, radio_buttons, andtoggle_button_group field types.

Optional setting. If not specified, the field type is transformed to text.
datePickerOptionsarray{datePickerOptions}Defines settings and conditions for the datepicker on the checkout. For example, limited working hours or disable weekends for the calendar.

Required only for datetime field type.
overridesarray{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.

Add tips with options

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:

FieldTypeDescription
titlestringOption title.
titleTranslatedobjectTranslations for the option title.
subtitlestringOption subtitle. Available only for the toggle_button_group type.
subtitleTranslatedobjectTranslations for the option subtitle.
surchargenumberSurcharge/tip value added to the cart.
surchargeTypestringDefines if a surcharge applies a fixed sum or a percentage increase to the cart total.
Available values:
ABSOLUTE - Adds a fixed sum.
PERCENT - Adds percentage increase.
surchargeTaxablebooleanDefines if surcharge/tip is taxable.
showZeroSurchargeInTotalbooleanDefines if zero-sum surcharge shows in cart total. Default: true.
surchargeShortNameobject{surchargeShortName}Defines how the surcharge shows in the "Shopping cart" block where the order total is calculated.

surchargeShortName

FieldTypeDescription
namestringNames for the "Shopping cart" block.
showSurchargePercentValuebooleanDefines if surcharge percentage value shows next to name. Default: true. Works only with PERCENT value in surchargeType.
nameTranslatedobjName translations for the "Shopping cart" block.

Code example:

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();

Advanced datepicker settings and overrides

With the JavaScript code, you can customize datepicker settings: set up your working hours or disable weekdays and holidays.

With overrides, you can change extra field settings based on certain conditions. For example, use different datepicker settings depending on the selected shipping or pickup method.

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.
showtimebooleanDefines if datepicker allows users to select the time. If true, time selection is enabled.
incrementMinuteBynumberIncrements 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.
limitAvailableHoursWeeklyobject{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.
disallowDatesarrayDisables specific ranges of date and time. For example, you can make the datepicker required and disable or limit holiday working hours.

limitAvailableHoursWeekly

FieldTypeDescription
MONarr{arr{string}}Monday working hours. Set up several time ranges if you have, for example, lunch hour.

Code example:
'MON': [ ['08:30', '13:30'], ['14:00', '17:30'] ]
TUEarr{arr{string}}Tuesday working hours. Set up several time ranges if you have, for example, lunch hour.
WEDarr{arr{string}}Wednesday working hours. Set up several time ranges if you have, for example, lunch hour.
THUarr{arr{string}}Thursday working hours. Set up several time ranges if you have, for example, lunch hour.
FRIarr{arr{string}}Friday working hours. Set up several time ranges if you have, for example, lunch hour.
SATarr{arr{string}}Saturday working hours. Set up several time ranges if you have, for example, lunch hour.
SUNarr{arr{string}}Sunday working hours. Set up several time ranges if you have, for example, lunch hour.

disallowDates

FieldTypeDescription
disallowDatesarr{arr{string}}Date and time range when datepicker is disabled. Code example:
'disallowDates': [ ['2023-03-30 18:00', '2023-03-31 20:30'] ]

overrides

FieldTypeDescription
conditionsobject{Conditions}Conditions to trigger the override.
fieldsToOverrideobject{FieldsToOverride}Fields for the override.

conditions

FieldTypeDescription
shippingMethodstringShipping method name, e.g. '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 (must not be hidden). Read more on the customization of customer emails.

Code example:

<#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 want to always have the same extra field on the checkout, it is easier to set up with REST API once.

Find a list of available methods below.