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:
Field | Type | Description |
---|---|---|
title | string | Title of a new field. It prompts user to enter the value |
checkoutDisplaySection | string | Accepts 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 |
orderDetailsDisplaySection | string | Defines 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. |
value | string | Default value used to prefill the extra field's value for user |
subtitle | string | Subtitle of a new field |
type | string | Accepts several values: text , textarea , select , checkbox , toggleButtonGroup , radiobuttons , datetime , label . Default is text . More on this below |
tip | string | Show a tip for filling the field under the input (ignored if type is textarea or checkbox ) |
available | boolean | If true , the field is shown and saved as an extra field. If false , the field completely ignored. true is default |
textPlaceholder | string | A text placeholder for text and textarea input fields |
showInInvoice | boolean | If not specified the default value is false . Set true to show extra field in order invoices. |
showInNotifications | boolean | If 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. |
selectOptions | Array<string> | Depricated, use options instead. Several options to choose from the select field, checkbox , radiobuttons or toggleButtonGroup 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. |
options | Array<options> | Several options to choose from the select field, checkbox , radiobuttons or toggleButtonGroup buttons. If selectOptions is not set, field is transformed to text type |
required | boolean | If not specified the default value is false . Set true to prevent continuing checkout if an extra field is ignored by customers. |
showForPaymentMethodIds | Array of strings | Detects 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"] . |
showForShippingMethodIds | Array of strings | Detects 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"] . |
showForCountry | Array of strings | Detects 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"] . |
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
Field | Type | Description |
---|---|---|
title | string | select field, checkbox , radiobuttons or toggleButtonGroup button option title |
subtitle | string | toggleButtonGroup button option subtitle |
surcharge | number | adds a surcharge to the cart when an option is chosen. More on that here: Add surcharge to extra fields' values |
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 usetextPlaceholder
attribute to add a placeholder to your extra field of typetext
. Ifvalue
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 inoptions
array. Ifoptions
is not set, field is transformed totext
typecheckbox
is a group of checkboxes. The checkbox values have to be set inoptions
array. Ifoptions
is not set, field is transformed totext
typetoggleButtonGroup
is a group of buttons. The buttons values have to be set inselectOptions
array oroptions
array. IfselectOptions
oroptions
are not set, field is transformed totext
typeradiobuttons
is a group of radio buttons. The radio buttons values have to be set inselectOptions
array oroptions
array. IfselectOptions
oroptions
are not set, field is transformed totext
type. IfselectOptions
oroptions
have only onetitle
value, field is transformed tocheckbox
type.datetime
is a date picker element. It can be customized – more on that belowlabel
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 formpickup_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 formshipping_methods
page at the checkout process. A new field will be displayed below the available shipping methods for customerpickup_methods
page at the checkout process. A new field will be displayed below the selected pickup method informationpayment_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.