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!
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.
Some third-party Shopify apps may also support displaying "Additional details" on the invoices they generate and we recommend speaking directly with the specific app to learn more.
From a B2B customer's perspective, any checkout custom fields you set up will also show against their orders when viewing order history within My Account Interface
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, 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).
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.
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. 'Tax ID Reference'
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:"Tax ID Reference",detail:"Please enter your Tax ID reference"}},name:"text-field",attributes:{required:false,type:"text",placeholder:"Enter Tax ID reference",minlength:4,maxlength:600}},],/* 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:false,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 requires date at least 1 day in future
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 date must be at least one day in future."}},attributes:{required:true,type:"date",min:((d)=>{
d.setDate(d.getDate()+1);return d.toISOString().slice(0,10);})(newDate())}},],
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 =newDate(val);const now =newDate()const ukTime = now.toLocaleString('en-GB',{hour:'2-digit',hour12:false,timeZone:'Europe/London'});const earliestDeliveryDate =newDate(
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 =newIntl.DateTimeFormat('en-GB',{dateStyle:'short'}).format(selectedDate);let messageTranslationKey
switch(true){// Date is in the pastcase selectedDate < earliestDeliveryDate:
messageTranslationKey ='select-date-in-future'break;// Day is weekendcase[0,6].includes(selectedDate.getDay()):
messageTranslationKey ='select-mon-fri'break;// Is bank holidaycase 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 (PO Number)
The Additional Information field is useful if you want to capture additional details from a customer whilst their placing an order.
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).
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.
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 */
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 */
Limiting characters of the "Additional information" field
It's possible to set a character limit for the additional information field should you have requirements to restrict what can be added.
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:{customerReferenceMaxLength:512,/* update 512 as required */},/* 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.
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 payment messages
On the final step of the My Order Interface, Review & Pay, it's possible to display a "custom payment messages" that let you add additional details about a payment method. For example, if a customer is paying by "Pay by Invoice", you could add some additional text to inform them on how this process works.
The "custom payment message" works by adding a special code snippet to the SparkLayer Core Script that lets you define the text you want to show.
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.payment-providers.paymentByInvoice.message":"This is a message for Payment by Invoice","cart.checkout.payment-providers.upfrontPayment.message":"This is a message for Pay Online by Card","cart.checkout.payment-providers.paymentOnAccount.message":"This is a message for Pay on Account","cart.checkout.payment-providers.quote.message":"This is a message for Request for Quote",}},/* 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.
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!
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.
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
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.
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.
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.
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 */
If your store is set up with multiple languages, you can also configure the code to show a different link based on the customer's location
🛍️ Using Shopify
🌐 Other platforms
JS
/* Add the below code into the SparkLayer Core Script *//* Please refer to our help guide on how to do this */{%-if shop.locale =="fr"-%}termsAndConditionsLink:'/policies/fr-terms-and-conditions',{%-else-%}termsAndConditionsLink:'/policies/terms-and-conditions',{%- endif -%}/* End of code */
No configurations applicable
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 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.
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.
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.
If you'd prefer to hide this, you can add the below CSS to your CSS overwrites.
CSS
--spark-cart-rrp-display: none;
Cart Image
It's possible to change how the product image is rendered in the My Order Interface by using special CSS overwrites. This is especially useful if your product images aren't square in ratio and you want to prevent the image being cropped.
Simply add one of the below options to your CSS overwrites.
CSS
--spark-cart-background-size: cover /* Set image to fill the space*/--spark-cart-background-size: contain /* Set image to be fully visible*/