Introduction

Collecting survey data from customers on an ecommerce site is crucial for business growth and customer satisfaction. It provides invaluable insights into the user experience, helping identify areas for improvement in website design, product offerings, and customer service. Survey responses can reveal customer preferences, pain points, and purchasing patterns, enabling businesses to tailor their strategies and offerings accordingly. This data-driven approach allows companies to make informed decisions, optimize their marketing efforts, and enhance overall customer engagement. Furthermore, by actively seeking customer feedback, businesses demonstrate that they value their customers' opinions, fostering loyalty and trust. In a competitive online marketplace, this continuous feedback loop can be the key differentiator that sets successful ecommerce sites apart from their rivals.

Native Survey Collection with SurveyJS

UltraCart, recognizing the critical importance of customer feedback for ecommerce success, made the strategic decision to leverage SurveyJS rather than reinventing the wheel for survey functionality. By integrating this proven solution, UltraCart empowers its merchants to easily implement professional, native-feeling surveys within their online stores. This choice allows UltraCart to focus on its core competencies while providing clients with a robust survey tool that offers a wide range of question types and customizable templates. The seamless integration of SurveyJS into the UltraCart platform enables merchants to gather valuable customer insights efficiently, without the need for extensive development resources. This approach not only saves time and effort for UltraCart and its clients but also ensures that merchants can quickly deploy surveys, leading to faster data collection and more agile decision-making. By choosing SurveyJS, UltraCart demonstrates its commitment to providing best-in-class solutions that help its merchants thrive in the competitive ecommerce landscape.

Building a Survey

SurveyJS simplifies the survey creation process by using JSON files to define survey structures. These JSON files, which contain all the necessary information about question types, layout, and logic, are stored directly on the StoreFront file system, making them easy to manage and version control. To create these survey definitions, SurveyJS provides a free, user-friendly online editor. This intuitive tool allows users to visually design their surveys, adding questions, setting up conditional logic, and customizing appearance without needing to write JSON manually. As users build their surveys in the editor, the corresponding JSON structure is generated automatically. Once satisfied with the design, users can simply copy the JSON file from the JSON Editor tab and save it to their StoreFront file system. This approach offers flexibility for developers, who can easily modify the JSON directly if needed, while also empowering non-technical team members to create and edit surveys through the visual interface. The combination of simple JSON files and a powerful free editor makes SurveyJS an accessible and efficient solution for implementing customer surveys in various applications.

An Example Survey to the File System

The following example survey is a post checkout questionnaire to gain additional insight into how the customer was marketed to.

{
  "title": "Post Checkout Questionnaire",
  "logoPosition": "right",
  "pages": [
    {
      "name": "page1",
      "title": "Page 1",
      "elements": [
        {
          "type": "radiogroup",
          "name": "whereDidYouHearAboutUs",
          "title": "Before you go... How did you first hear about us?",
          "hideNumber": true,
          "isRequired": true,
          "requiredErrorText": "At least ONE answer must be selected",
          "choices": [
            "Facebook",
            "From a friend, family member, or coworker",
            "Podcast/Radio",
            "Pinterest",
            "TikTok",
            "Snapchat",
            "Instagram",
            "TV",
            "Press or other article",
            "From an influencer",
            "In a retail store",
            "Google or other search engine"
          ],
          "showOtherItem": true
        },
        {
          "type": "radiogroup",
          "name": "whoPostedAboutUs",
          "visibleIf": "{whereDidYouHearAboutUs} anyof ['Facebook', 'Pinterest', 'TikTok', 'Instagram']",
          "title": "Who posted about us?",
          "hideNumber": true,
          "isRequired": true,
          "requiredErrorText": "At least ONE answer must be selected",
          "choices": [
            "You did!",
            "I saw an ad",
            "Someone I know",
            "An influencer I follow"
          ],
          "showOtherItem": true
        }
      ]
    },
    {
      "name": "page3",
      "title": "Page 3",
      "elements": [
        {
          "type": "checkbox",
          "name": "whatBroughtYouToOurSiteToday",
          "title": "And what brought you to our site today?",
          "hideNumber": true,
          "isRequired": true,
          "requiredErrorText": "At least ONE answer must be selected",
          "commentPlaceholder": "What Areas?",
          "choices": [
            "I received a text message",
            "I remember you from the past",
            "I saw an ad",
            "I received an email",
            "Someone told me about you",
            "I was searching something"
          ],
          "showOtherItem": true,
          "otherPlaceholder": "Other",
          "otherText": "Other"
        }
      ]
    },
    {
      "name": "page4",
      "title": "Page 4",
      "elements": [
        {
          "type": "radiogroup",
          "name": "howLongDidYouKnowAboutUs",
          "title": "How long did you know about us before making your first purchase?",
          "hideNumber": true,
          "isRequired": true,
          "requiredErrorText": "At least ONE answer must be selected",
          "choices": [
            "< 1 day",
            "< 1 week",
            "< 1 month",
            "1 - 3 months",
            "3 - 12 months",
            "> 12 months"
          ]
        }
      ]
    },
    {
      "name": "page5",
      "title": "Page 5",
      "elements": [
        {
          "type": "text",
          "name": "email",
          "title": "Your email address",
          "inputType": "email",
          "isRequired": true
        },
        {
          "type": "text",
          "name": "birthdate",
          "title": "One last thing, can we send you something on your birthday?",
          "inputType": "date"
        }
      ]
    }
  ],
  "showTitle": false,
  "showPageTitles": false,
  "goNextPageAutomatic": true,
  "startSurveyText": "Next",
  "pagePrevText": "Back",
  "completeText": "Finish",
  "questionTitlePattern": "numTitle",
  "firstPageIsStarted": true
}

Take the example JSON contents and place them on your StoreFront file system as a file named /postcheckoutsurvey.json in the root of the file system as shown below.

Embedding the Survey on the Page

Within the StoreFront visual builder, add a SurveyJS element to the page. Within the settings of the SurveyJS element you will need to select the location of the JSON file on the file system.

Reserved Question Names

Most SurveyJS question name values you choose are stored verbatim in the raw JSON column of the uc_surveys table in BigQuery — you can name them whatever is most descriptive for your reporting.

A small set of question names are reserved: if you use one of these names, UltraCart will additionally copy the answer into a dedicated column on uc_surveys and, in some cases, wire it into other systems like the real-time analytics identify event.

Reserved `name`	Column populated	Additional behavior

Reserved `name`	Column populated	Additional behavior
`email` (lowercase)	`uc_surveys.email`	Fires real-time `identify` event to the analytics bus as soon as it is filled in; writes the value to the shopper's cart so it is available to abandoned-cart flows and downstream integrations (Northbeam, Klaviyo, GA4).

Requirements when using a reserved name

The name field must be an exact case-sensitive match (for example, email — not Email, emailAddress, or customer_email). If the name does not match, the value is still captured as a normal survey answer inside raw, but the dedicated column stays empty.
The reserved question must be declared at the top level of a page. Nesting it inside a paneldynamic, matrixdynamic, or other container changes the key SurveyJS emits, and the reserved-name match will not fire.
The title of the question is the visible label — you can set it to anything. The title has no effect on column mapping. Only name matters.

Example — email capture question

{
  "type": "text",
  "name": "email",
  "title": "Your email address",
  "inputType": "email",
  "isRequired": true
}

Survey Type: Marketing vs PII

The SurveyJS element settings include a Type dropdown with two options:

Marketing — the default. The survey is treated as standard marketing/feedback content. Session-recording tools capture the survey form and its contents as they would any other page element.
PII — use when the survey collects personally identifiable information (email, phone number, date of birth, health information, etc.). UltraCart adds the rr-block class to the survey element so session-recording tools will not capture its contents.

If a survey contains any of the reserved question names, or any free-text field that a shopper might use to enter personal information, set the Type to PII.

How are the Surveys Stored?

UltraCart stores the completed Surveys into the BigQuery Data Warehouse. If the Survey is configured to add an item ID to the cart at completion then an item level property named "survey_uuid" is added which references the Survey and allows the tie together between the individual survey and the item on the order. This is useful for surveys involved with buying specific products.

If the Survey is embedded in the context of an order element (for example on the receipt) then the survey will be tied to the order using a property named "survey_uuid" at the order level.

If the Survey is embedded in the context of an order item list element on the receipt, then the survey will be tied to the order item using a property named "survey_uuid" at the order item level.

The only way to access the survey data is through the BigQuery Data Warehouse. Within the data warehouse you can write SQL queries to aggregate the survey information and the include that within your custom Google Looker reports.

The uc_surveys Table

Each survey submission becomes one row in the uc_surveys table in BigQuery. The table has the following columns:

survey_uuid — unique identifier for the survey submission. Used as the survey_uuid property on cart items / orders / order items to link a submission back to its context.
survey_name — the name configured in the SurveyJS element settings.
survey_type — Marketing or PII. PII marks the survey for exclusion from screen recording.
uri — page path on which the survey was submitted.
widget_id — the ID of the SurveyJS page-builder element, if set.
email — populated only when the survey contains a question with name: "email" (see Reserved Question Names).
raw — the full SurveyJS answer payload as JSON. Keys are question name values.
question_definitions — array of metadata for each question (type, title, page number, position, visible choices).
ucacid — UltraCart anonymous customer id cookie value at time of submission; lets you join against identify/activity data.
order_id_token / order_item_token — set when the survey element is nested under an order or order-item element (for example on a receipt).
add_item_id / add_coupon_code — populated when the survey is configured to add an item or coupon on completion.
correct_answer_count / incorrect_answer_count / correctly_answered / incorrectly_answered — populated when the survey uses SurveyJS correctAnswer values (quiz-style surveys).

Example: Contact Form with All Question Types

The following worked example demonstrates a two-page contact/inquiry form that covers all five core SurveyJS question types: text, radiogroup, checkbox, dropdown, and comment. A live version is available at demo4.ultracartstore.com/survey-demo.html.

Step 1: Create the JSON template

In the StoreFront File Manager, create a new file named /contact-form.json at the root of the file system and paste the following content:

{
  "title": "Contact & Meeting Request Form",
  "logoPosition": "right",
  "pages": [
    {
      "name": "page1",
      "title": "Contact Information",
      "elements": [
        {"type": "text", "name": "name", "title": "Full Name", "isRequired": true},
        {"type": "text", "name": "email", "title": "Email Address", "inputType": "email", "isRequired": true},
        {"type": "text", "name": "phone", "title": "Phone Number", "inputType": "tel"},
        {"type": "text", "name": "company", "title": "Company / Organization"}
      ]
    },
    {
      "name": "page2",
      "title": "Your Inquiry",
      "elements": [
        {
          "type": "radiogroup",
          "name": "inquiryType",
          "title": "What best describes your inquiry? (choose one)",
          "isRequired": true,
          "choices": ["Product information", "Pricing / purchasing", "Schedule a meeting", "General question"],
          "showOtherItem": true,
          "otherText": "Other"
        },
        {
          "type": "checkbox",
          "name": "areasOfInterest",
          "title": "Which areas are you interested in? (select all that apply)",
          "choices": ["Leadership development", "Team training", "Executive coaching", "Online programs", "In-person events"],
          "showOtherItem": true,
          "otherText": "Other"
        },
        {
          "type": "dropdown",
          "name": "preferredContact",
          "title": "Preferred contact method",
          "choices": ["Email", "Phone", "Either"]
        },
        {
          "type": "comment",
          "name": "message",
          "title": "Additional comments or questions",
          "rows": 4
        }
      ]
    }
  ],
  "showTitle": false,
  "showPageTitles": false,
  "goNextPageAutomatic": false,
  "pagePrevText": "Back",
  "completeText": "Submit",
  "firstPageIsStarted": false
}

This form uses name: "email" on page 1. UltraCart treats email as a reserved question name: the submitted value is written to uc_surveys.email in BigQuery and fires a real-time identify event that makes the address available to Conversations flows and abandoned-cart integrations. See Reserved Question Names for details.

Step 2: Add the Survey element to your page

In the StoreFront Visual Builder, open the page where the form should appear. Select the body container, click ADD NEW ELEMENT, type survey in the search box, and click the Survey tile to insert it.

Step 3: Configure the Survey element settings

Click the gear icon on the Survey element to open its settings panel. Fill in the following fields:

Field	Value	Notes

Field	Value	Notes
Name	`contact-form`	Becomes `survey_name` in the `uc_surveys` BigQuery table.
Type	PII	Required when the form collects name, email, or other personal data.
SurveyJS JSON File	`/contact-form.json`	Path to the JSON file on the StoreFront file system.

Step 4: Save and preview

Click Save in the visual builder toolbar. The survey renders immediately. Page 1 collects contact information (four text inputs, two required). Page 2 collects inquiry details using radiogroup, checkbox, dropdown, and comment question types, with Back and Submit navigation.

Connecting completions to a Conversations flow

Once the survey is live, you can automate follow-up using UltraCart Conversations:

In Conversations, create a new Segment for survey respondents.
Create a Flow and select the trigger Survey - When someone has completed a survey. Filter by survey name (contact-form) to target only this form.
Add flow steps to send a follow-up email, assign a tag, or add the contact to a list.

The Conversations survey trigger and Segment creation require a minimum account age and activity level. If these options are not yet available in your account, contact UltraCart support to confirm eligibility.

Troubleshooting

The email column in uc_surveys is empty

Your email question's name field is probably not email. Open the SurveyJS JSON and check the name — not the title — of your email question. It must be exactly email, lowercase, and not nested inside a panel or matrix. The title is only the label shown to the shopper.

The answers appear in raw but not in the columns I expected

Only the reserved question names listed above get their own column. Everything else lives in the raw JSON payload, where you can still query it with BigQuery's JSON functions (for example JSON_VALUE(raw, "$.whereDidYouHearAboutUs")).

The survey submits, but nothing appears in BigQuery at all

The data warehouse is loaded on a delay. Give it a few minutes, then query again. If rows still do not appear, check the browser devtools Network tab for the PUT /rest/site/survey request — a non-200 response there indicates the submission itself failed before it reached the warehouse.

I want the survey excluded from session recording

Set the survey Type to PII in the SurveyJS element settings. This adds the rr-block class to the survey element so session-recording tools will not capture its contents.

Adding a Survey to StoreFronts