website logo
SupportDashboardAbout SparkLayerSchedule Demo
📘Help Docs
⚙️Tech Docs
Navigate through spaces
⌘K
👋Introduction
How SparkLayer Works
Getting Started
📣Useful Links
What's New!
Roadmap
Support
Try our Demo
Troubleshooting
Policies & Data
🖥️Frontend
⭐Features
⚒️Backend
📊Dashboard
🌐Integrations
Docs powered by
Archbee
Features
Configurations

Cart & Checkout

Custom checkout fields

Custom checkout fields allow you to capture additional information from customers during the checkout process. It's a great way to allow customers to add data such as preferred shipping date, Purchase Order numbers, and more!

Document image


Once enabled, the custom checkout fields will display on the 'Shipping' step of the My Order Interface before the customer selects their shipping address.

How custom checkout field data is stored

When a customer completes a custom checkout field, these will be attached to their order data as special 'Notes'.

🛍️ Using Shopify
🌐 Other platforms

In the context of Shopify, these will display as "Additional details" within "Order Notes". This data can then be retrieved and used to display on packing slips, sent through to a backend system (via the API) and more.

Document image


No configurations applicable

How to add custom checkout fields

Custom checkout fields work by adding special code to your website within the SparkLayer Core Script.

In our example below, we've included how this would work with an example 'shipping date'. This can also be adapted with a wide range of other field types such as radios, date pickers, text fields (see below for the full list).

Updating the display You can update the default display by adding code to your Core Script. Learn more about how to update display settings on SparkLayer


Example with a shipping date
Example with multiple custom fields
JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
    name: "delivery-date",
    translations: {
      en: {
        title: "Delivery Date",
        detail:  "Delivery unavailable on weekends."
      }
    },
    attributes: {
      required: true,
      type: "date"
    }
  },
],
/* End of code */

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
{
  translations: {
      en: {
          title: "Text field",
          detail: "Explains what the field is for. Must be 2 letters followed by 2-4 digits"
      }
  },
  name: "text-field",
  attributes: {
      required: true,
      type: "text",
      placeholder: "Placeholder shows inside the empty input",
      minlength: 4,
      maxlength: 6,
      pattern: "[a-zA-Z]{2}[0-9]{2,4}"
  }
},
{
  translations: {
      en: {
          title: "Number field",
      }
  },
  name: "number-field",
  attributes: {
      type: "number",
      step: 5,
      min: 15,
      max: 25,
  }
},
{
  translations: {
      en: {
          title: "Date field",
      }
  },
  name: "date-field",
  attributes: {
      type: "date"
  }
},
{
  translations: {
      en: {
          title: "Time field",
      }
  },
  name: "time-field",
  attributes: {
      type: "time"
  }
},
{
  translations: {
      en: {
          title: "Week field",
      }
  },
  name: "week-field",
  attributes: {
      type: "week"
  }
},
{
  translations: {
      en: {
          title: "Datetime field",
      }
  },
  name: "datetime-field",
  attributes: {
      type: "datetime-local"
  }
},
{
  translations: {
      en: {
          title: "Checkbox field",
      }
  },
  name: "checkbox-field",
  attributes: {
      type: "checkbox"
  }
},
{
  translations: {
      en: {
          title: "Month field",
      }
  },
  name: "month-field",
  attributes: {
      type: "month"
  }
},
{
  translations: {
      en: {
          title: "Telephone field",
      }
  },
  name: "telephone-field",
  attributes: {
      type: "tel"
  }
},
{
  translations: {
      en: {
          title: "Email field",
      }
  },
  name: "email-field",
  attributes: {
      type: "email"
  }
},
{
  translations: {
      en: {
          title: "URL field",
      }
  },
  name: "url-field",
  attributes: {
      type: "url"
  }
},
],
/* End of code */


Custom element configuration options

Key

Details

name

The name of the custom field. This is shown in your eCommerce platform but is not visible to customers. (required)

translations

An object containing customer-facing strings. Keys must be 2 letter language codes (ISO 639-1). (required)

attributes

HTML attributes applied to the element. Use these to specify the type of input and validation rules.

title

It's also possible to customise the text that is shown to the customer using translations. Text shown in bold above the input (required)

detail

Small 'helper' text shown beneath the input. Useful for explaining what the field is for and acceptable values.

Supported element attributes Some attributes only apply to certain input types and you can find more detailed documentation can be found here.

Example custom checkout fields

To get started, we've included some of our most popular customer checkout field types.

Updating the display You can update the default display by adding code to your Core Script. Learn more about how to update display settings on SparkLayer



Date picker, e.g. 'Shipping date'

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
    name: "shipping-date",
    translations: {
      en: {
        title: "Shipping Date",
        detail:  "Please select your preferred shipping date"
      }
    },
    attributes: {
      required: true,
      type: "date"
    }
  },
],
/* End of code */




Custom text, e.g. 'Promotion code'

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Promotional code",
              detail: "Please enter a promotional code above"
          }
      },
      name: "text-field",
      attributes: {
          required: true,
          type: "text",
          placeholder: "Enter promotional code here",
          minlength: 4,
          maxlength: 600
      }
  },
],
/* End of code */




Custom text, e.g. 'Shipping instructions'

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Shipping instructions field",
              detail: "Please confirm any shipping instructions for us"
          }
      },
      name: "text-field",
      attributes: {
          required: true,
          type: "text",
          placeholder: "Shipping instructions field",
          minlength: 4,
          maxlength: 600
      }
  },
],
/* End of code */




Number, e.g. 'Contact phone number'

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
      translations: {
          en: {
              title: "Contact phone number",
              detail:  "Please supply a phone number to allow us to contact you"
          }
      },
      name: "number-field",
      attributes: {
          type: "number",
          min: 10,
          max: 25,
      }
  },
],
/* End of code */




Date picker that restricts by weekends and specific dates

Date picker that restricts by weekends and specific dates

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
  translations: {
    en: {
      title: "Delivery Date",
      detail: "Delivery unavailable on weekends.",
      'select-mon-fri': "Date must be Monday-Friday",
      'select-date-in-future': "Select a date in the future",
      'select-non-bank-holiday': "Select another date which is not a UK bank holiday",
    },
  },
  name: "delivery-date-requested",
  attributes: {
    required: true,
    type: "date"
  },
  onChange(val, el) {
    const selectedDate = new Date(val);
    const now = new Date()
    const ukTime = now.toLocaleString(
      'en-GB',
      {
        hour: '2-digit',
        hour12: false,
        timeZone: 'Europe/London'
      }
    );

    const earliestDeliveryDate = new Date(
      now.getFullYear(),
      now.getMonth(),
      now.getDate() + (Number(ukTime) >= 12 ? 1 : 0)
    )

    const ukBankHolidays = [
      '07/04/2023',
      '10/04/2023',
      '01/05/2023',
      '08/05/2023',
      '29/05/2023',
      '28/08/2023',
      '25/12/2023',
      '26/12/2023',
    ];

    const selectedDateStr = new Intl.DateTimeFormat('en-GB', { dateStyle: 'short' })
      .format(selectedDate);

    let messageTranslationKey
    switch (true) {
      // Date is in the past
      case selectedDate < earliestDeliveryDate:
        messageTranslationKey = 'select-date-in-future'
        break;
      // Day is weekend
      case [0, 6].includes(selectedDate.getDay()):
        messageTranslationKey = 'select-mon-fri'
        break;
      // Is bank holiday
      case ukBankHolidays.includes(selectedDateStr):
        messageTranslationKey = 'select-non-bank-holiday'
        break;
    }

    return {
      valid: messageTranslationKey === undefined,
      messageTranslationKey
    }
  }
}
],
/* End of code */




Checkbox to require customer confirmation

JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
checkoutCustomElements: [
  {
    translations: {
      en: {
        title: "I agree to the terms and conditions",
        detail: "Please confirm you've read and agree to the terms and conditions",
      },
    },
    name: "confirmation",
    attributes: {
      required: true,
      type: "checkbox"
    },
  },
],
/* End of code */




Supported form field types

Custom checkout fields currently support the following field types:

Field Type

Notes

text

Freeform text entry

number

Number entry

date

Date, DD/MM/YYYY

time

Specific time, 00:00

week

Week (4)

month

Month of year (12)

datetime-local

DD/MM/YYY 00:00

checkbox

Allows multiple selections

tel

Number entry for phone

email

Email entry

url

Website URL entry






The "Additional Information" field

The Additional Information field is useful if you want to capture additional details from a customer whilst their placing an order.

Document image


Typical use-cases include capturing a Purchase Order number (sometimes referred to as PO number), delivery instructions, or instructions.

🛍️ Using Shopify
🌐 Other platforms

When completed by a customer, the data will then show within the Shopify order under the Notes section (this can also be sent to a backend system using the SparkLayer API).

Document image


Please refer to the SparkLayer Technical Docs

Please note The additional information is a separate field to the 'custom checkout fields' detailed above. The Additional Information field is also limited to 512 characters in total

Make "Additional information" mandatory

You can force customers to complete the 'Additional information' field before proceeding to place their order.

Document image


Updating the display You can update the default display by adding code to your Core Script. Learn more about how to update display settings on SparkLayer


JS
|
/* Add the below code into the display object within the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
display: {
  customerReferenceRequired: true,
},
/* End of code */


Updating language and text You can update the default text by adding code to your Core Script. Learn more about how to update text on SparkLayer.


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
translations: {
  en: {
    "cart.checkout.notes.label": "Additional Information",
    "cart.checkout.notes.placeholder": "Order notes e.g. PO Number",
    "cart.checkout.notes.helper-text": "Please note, this is required before placing your order",
  }
},  
/* End of code */


Hiding the "Additional information" field

Alternatively, if you'd prefer to hide the additional information field from showing, you can update this via the SparkLayer Core Script.

Updating the display You can update the default display by adding code to your Core Script. Learn more about how to update display settings on SparkLayer


JS
|
/* Add the below code into the display object within the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
display: {
  customerReferenceHidden: true,
},
/* End of code */







Custom checkout message

On the final step of the My Order Interface, Review & Pay, it's possible to display a "custom checkout message" that lets you inform customers of any special notes or information they need to be aware of. It's a great way to highlight information about shipping, payment, or anything else!

Document image


The "custom checkout message" works by adding a special code snippet to the SparkLayer Core Script that lets you define the text you want to show.

Updating language and text You can update the default text by adding code to your Core Script. Learn more about how to update text on SparkLayer.


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
translations: {
  en: {
    "cart.checkout.review-step.custom-message": "Add your custom checkout message here",
  }
},  
/* End of code */


Please note It's important to note that this text will show to all customers during the checkout process and it's not possible to vary it based on who the customer is.

Styling the message

Document image


If you'd like to customise how the message looks, you can do this by adding special CSS to your website. Simply add the below CSS to your website's CSS file and you can then set styling such as colours and spacing.

CSS
|
<style>
:root {
  --spark-message-checkout-review-message-color: #555;
  --spark-message-checkout-review-message-background: #fff;
  --spark-message-checkout-review-message-padding: 0.5em 0.75em;
  --spark-message-checkout-review-message-alignment: left;
  --spark-message-checkout-review-message-border: 1px solid #CCCCCC;
}
</style>







Terms and conditions

When customers checkout via the SparkLayer My Order Interface, they'll be asked to confirm the store's terms and conditions before completing their order.

Document image


By default, the terms and conditions link will point to a URL of policies/terms-of-service but it's possible to change this via the SparkLayer Core Script.

Updating the display You can update the default display by adding code to your Core Script. Learn more about how to update display settings on SparkLayer


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
termsAndConditionsLink: '/policies/terms-of-service',
/* End of code */


Updating language and text You can update the default text by adding code to your Core Script. Learn more about how to update text on SparkLayer.


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
translations: {
  en: {
    "cart.checkout.terms.start": "I agree to the ",
    "cart.checkout.terms.link": "terms and conditions",
    "cart.checkout.terms.end": " ",
  }
}, 
/* End of code */







Payment methods

Please refer to the Payment Methods guide for more information.






Tax & shipping messaging

Tax & shipping To learn more about how SparkLayer handles tax and shipping, see our guide here.

When a customer proceeds through the checkout, they'll be notified about tax and shipping with messaging beneath the main call to action.

This message is shown on the first step of the checkout
This message is shown on the first step of the checkout

This message is show on the 'Shipping' step of the checkout
This message is show on the 'Shipping' step of the checkout


If you'd like to modify what is shown here, you can do so by updating the default language within your store.

Updating language and text You can update the default text by adding code to your Core Script. Learn more about how to update text on SparkLayer.


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
translations: {
  en: {
    "cart.tax-shipping-note": "Tax and shipping costs calculated during checkout",
    "cart.tax-shipping-message": "Tax and shipping costs shown on next step",
  }
}, 
/* End of code */







The order complete screen

You can modify the confirmation screen that shows to the customer by adding the below to the language overwrites within the SparkLayer Core Script.

Document image


Updating language and text You can update the default text by adding code to your Core Script. Learn more about how to update text on SparkLayer.


JS
|
/* Add the below code into the SparkLayer Core Script */
/* Please refer to our help guide on how to do this */
translations: {
  en: {
    "cart.thanks.payment.main": "Thank you for your order!",
    "cart.thanks.payment.blurb": "Your order has now been placed and you will shortly receive email confirmation to {email}. You can check the status of your order at any time by going to 'My Account'.",
    "cart.thanks.quote.main": "Thank you for requesting a quote!",
    "cart.thanks.quote.blurb": "We can confirm that your request for a quote has been received and we'll be in touch once our team has reviewed it.",
  }
},
/* End of code */







Order limits (minimum and maximum order values)

It's possible to set minimum and maximum order values that a customer has to meet before being able to place an order. Please refer to our full guide here.






Pricing Display

If you have RRP pricing (MSRP) set up, by default the My Order Interface will display this below the main selling price.

Document image


If you'd prefer to hide this, you can add the below CSS to your CSS overwrites.

CSS
|
--spark-cart-rrp-display: none;




Updated 12 Sep 2023
Did this page help you?
PREVIOUS
Payment Methods
NEXT
Shipping & Tax
Docs powered by
Archbee
TABLE OF CONTENTS
Custom checkout fields
How custom checkout field data is stored
How to add custom checkout fields
Example custom checkout fields
Supported form field types
The "Additional Information" field
Custom checkout message
Styling the message
Terms and conditions
Payment methods
Tax & shipping messaging
The order complete screen
Order limits (minimum and maximum order values)
Pricing Display
Docs powered by
Archbee