NAV

Get additional info from a customer

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.

Step #1: Modify Ecwid integration code

Initialize extra fields object

ec.order = ec.order || {};
ec.order.extraFields = ec.order.extraFields || {};

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.

Step #2: Create new fields at checkout

Init and display your custom field at checkout

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'
};

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:

FieldTypeDescription
titlestringTitle of a new field. It prompts user to enter the value
checkoutDisplaySectionstringAccepts several values: shipping_address, pickup_details, billing_address, order_comments. More on this below
orderDetailsDisplaySectionstringWhere the extra field will be shown to customer and merchant. Supported values: shipping_info, billing_info, customer_info, order_comments
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

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
  • billing_address form at checkout (payment select step). A new field will be added below the fields in the address form
  • order_comments form at checkout (payment select step). A new field will be added below the order comments field

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.

To show the field and value to merchant and customer successfully, all requirements must be met:

  • title is not empty
  • value is not empty
  • orderDetailsDisplaySection contains supported value: shipping_info, billing_info, customer_info, order_comments

If orderDetailsDisplaySection contains an unsupported value, the field will still be saved in an order, but it will not be shown.

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

<script>
// 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': 'order_comments'
};

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

// Hidden field, which is not shown at checkout
ec.order.extraFields.my_custom_field = {
    'value': 'abcd12345'
};
</script>

Step #3: Ecwid saves the values to order details when it gets placed

If your code executed successfully, these fields will be saved when a customer places their order in an Ecwid store. See below on how you can access them afterwards.