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.
- Custom application. If you don't have a custom app yet, please refer to this instruction.
- Access scopes. The app requires the following access scope:
customize_storefront
. - Endpoints. The app requires one endpoint:
- 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:
Field | Type | Description |
---|---|---|
title | string | Extra field title. It is visible on the checkout, in customer notifications, and in Ecwid admin. Required setting. |
titleTranslated | object | Translations for the extra field title. Optional setting. |
type | string | Extra 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. |
checkoutDisplaySection | string | Defines 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 paymentRequired setting. |
orderDetailsDisplaySection | string | Defines 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 customerhidden - Extra field is hidden from customer notifications and Ecwid admin.Optional setting. If not specified, an extra field shows in the order comments section. |
textPlaceholder | string | Placeholder 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. |
textPlaceholderTranslated | object | Translations for the extra field placeholder text. Optional setting. |
value | string | Defines 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. |
valueTranslated | object | Translations for the default value of the extra field. Optional setting. |
subtitle | string | Extra 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. |
subtitleTranslated | object | Translations for the extra field subtitle. Optional setting. |
tip | string | Extra 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. |
tipTranslated | object | Translations for the extra field tip text. Optional setting. |
available | boolean | Defines 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. |
showInInvoice | boolean | Defines 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. |
showInNotifications | boolean | Defines 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. |
required | boolean | Defines 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. |
showForPaymentMethodIds | Array of strings | Defines 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. |
showForShippingMethodIds | Array of strings | Defines 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. |
showForCountry | Array of strings | Defines 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. |
options | Array{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 . |
datePickerOptions | array{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. |
overrides | array{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
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:
Field | Type | Description |
---|---|---|
title | string | Option title. |
titleTranslated | object | Translations for the option title. |
subtitle | string | Option subtitle. Available only for the toggle_button_group type. |
subtitleTranslated | object | Translations for the option subtitle. |
surcharge | number | Surcharge/tip value added to the cart. |
surchargeType | string | Defines 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. |
surchargeTaxable | boolean | Defines if surcharge/tip is taxable. |
showZeroSurchargeInTotal | boolean | Defines if zero-sum surcharge shows in cart total. Default: true . |
surchargeShortName | object{surchargeShortName} | Defines how the surcharge shows in the "Shopping cart" block where the order total is calculated. |
surchargeShortName
surchargeShortName
Field | Type | Description |
---|---|---|
name | string | Names for the "Shopping cart" block. |
showSurchargePercentValue | boolean | Defines if surcharge percentage value shows next to name . Default: true . Works only with PERCENT value in surchargeType . |
nameTranslated | obj | Name 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
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 | object{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 | array | Disables specific ranges of date and time. For example, you can make the datepicker required and disable or limit holiday working hours. |
limitAvailableHoursWeekly
limitAvailableHoursWeekly
Field | Type | Description |
---|---|---|
MON | arr{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'] ] |
TUE | arr{arr{string}} | Tuesday working hours. Set up several time ranges if you have, for example, lunch hour. |
WED | arr{arr{string}} | Wednesday working hours. Set up several time ranges if you have, for example, lunch hour. |
THU | arr{arr{string}} | Thursday working hours. Set up several time ranges if you have, for example, lunch hour. |
FRI | arr{arr{string}} | Friday working hours. Set up several time ranges if you have, for example, lunch hour. |
SAT | arr{arr{string}} | Saturday working hours. Set up several time ranges if you have, for example, lunch hour. |
SUN | arr{arr{string}} | Sunday working hours. Set up several time ranges if you have, for example, lunch hour. |
disallowDates
disallowDates
Field | Type | Description |
---|---|---|
disallowDates | arr{arr{string}} | Date and time range when datepicker is disabled. Code example:'disallowDates': [ ['2023-03-30 18:00', '2023-03-31 20:30'] ] |
overrides
overrides
Field | Type | Description |
---|---|---|
conditions | object{Conditions} | Conditions to trigger the override. |
fieldsToOverride | object{FieldsToOverride} | Fields for the override. |
conditions
conditions
Field | Type | Description |
---|---|---|
shippingMethod | string | Shipping 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.