LogoLogo
Build appsContact API support
  • Build apps
  • Site Templates
  • API Reference
  • Changelog
  • REST API
    • REST API overview
    • Store Profile
      • Get store profile
      • Update store profile
      • Upload store logo image
      • Delete store logo image
      • Store reports
        • Get store reports
        • Get latest store update stats
        • Get deleted items history
    • Orders
      • Search orders
      • Get order
      • Get last order
      • Calculate order details
      • Update order
      • Create order
      • Delete order
      • Get repeat order URL
      • Order invoices
        • Get order receipt PDF
        • Get tax invoices for order
        • Generate tax invoice for order
      • Order statuses
        • Search order statuses
        • Get order status
        • Update custom order status
      • Order extra fields
        • Search order extra fields
        • Update order extra field
        • Add extra fields to order
        • Delete order extra field
      • Abandonned carts
        • Search abandoned carts
        • Get abandoned cart
        • Update abandoned cart
        • Convert abandoned cart to order
      • Recurring subscriptions
        • Search recurring subscriptions
        • Get recurring subscription
        • Update recurring subscription
    • Products
      • Search products
      • Get product
      • Update product
      • Create product
      • Delete product
      • Delete all products
      • Adjust product stock
      • Get product filters
      • Get recently used product swatches
      • Search product brands
      • Product images and videos
        • Upload main product image
        • Upload main product image (async)
        • Upload gallery product image
        • Upload gallery product image (async)
        • Delete main product image
        • Delete gallery product image
        • Delete all gallery product images
        • Upload main product video
        • Upload gallery product video
        • Upload cover for gallery video
        • Delete main product video
        • Delete gallery product video
        • Download gallery product video
        • Bulk update product images and videos
      • Product files
        • Upload product file
        • Download product file
        • Delete product file
        • Delete all product files
        • Change product file description
      • Product variations
        • Search product variations
        • Get product variation
        • Update product variation
        • Create product variation
        • Delete product variation
        • Delete all product variations
        • Adjust product variation stock
        • Upload product variation image
        • Upload product variation image (async)
        • Delete product variation image
      • Product types and attributes
        • Search product types
        • Get product type
        • Update product type and attributes
        • Create product type
        • Delete product type
      • Product reviews
        • Search product reviews
        • Get product reviews stats
        • Update product review status
        • Bulk update/delete product reviews
        • Delete product review
    • Categories
      • Search categories
      • Search categories by path
      • Get category
      • Update category
      • Create category
      • Delete category
      • Category images
        • Upload category image
        • Upload category image (async)
        • Delete category image
      • Manage order of categories in the store
        • Get order of categories
        • Update order of categories
      • Manage order of products in the category
        • Get order of products
        • Update order of products
        • Assign products to the category
        • Unassign products from the category
    • Customers
      • Search customers
      • Get customer
      • Update customer
      • Create customer
      • Delete customer
      • Customer groups
        • Search customer groups
        • Get customer group
        • Update customer group name
        • Create customer group
        • Delete customer group
      • Customer contacts
        • Search customer contacts
        • Get customer contact
        • Update customer contact
        • Create customer contact
        • Delete customer contact
      • Customer extra fields
        • Search customer extra fields
        • Get customer extra field
        • Update customer extra field
        • Create customer extra field
        • Delete customer extra field
    • Discounts
      • Promotions
        • Search promotions
        • Update promotion
        • Create promotion
        • Delete promotion
      • Discount coupons
        • Search discount coupons
        • Get discount coupon
        • Update discount coupon
        • Create discount coupon
        • Delete discount coupon
    • Domains
      • Search store domains
      • Update store domains
      • Search domains for purchase
      • Purchase domain
      • Send domain verification email
      • Reset domain password
    • Dictionaries
      • Country codes
      • Currency codes
      • Currency codes by country
      • State codes by country
      • Tax classes by country
    • Staff accounts
      • Search staff accounts
      • Get staff account
      • Get staff account scopes
      • Update staff account
      • Create staff account
      • Delete staff account
      • Resend staff account invite
      • Cancel staff account invite
    • Application
      • Get app subscription status
      • Cancel app subscription
      • Get all app storage data
      • Get specific app storage data
      • Update specific app storage data
      • Delete specific app storage data
      • Add app storage data
      • Custom charge with Ecwid billing
    • Batch requests
      • Create batch request
      • Get batch status
      • Search batch requests by status
      • Stop batch request
      • Stop and delete batch request
    • Shipping options
      • Search shipping options
      • Update shipping option
      • Create shipping option
      • Delete shipping option
    • Payment options
      • Search payment options
      • Get payment option
      • Update payment option
      • Create payment option
      • Delete payment option
    • Checkout extra fields
      • Add checkout extra fields with JavaScript
      • Manage checkout extra fields with REST API
        • Search checkout extra fields
        • Get checkout extra field
        • Update checkout extra field
        • Create checkout extra field
        • Delete checkout extra field
    • Storefront widget details
      • Get page slug and static code
      • Set base URL for storefront widgets
      • Optimize custom website SEO with better URLs
        • Enable Clean Store URLs on a custom website
        • Set Custom Page Slugs on a custom website
      • Dynamic loading for storefront widget
      • SSO (Single-Sign-On) for websites
        • Add SSO to the website
        • Customize SSO on the website
        • SSO code examples
      • Static store pages
        • Static code for home page
        • Static code for category page
        • Static code for product page

Lightspeed® 2025

On this page
  • Required access scopes
  • Path params
  • Headers
  • Request JSON
  • Response JSON

Was this helpful?

  1. REST API
  2. Checkout extra fields
  3. Manage checkout extra fields with REST API

Create checkout extra field

POST https://app.ecwid.com/api/v3/{storeId}/profile/extrafields

Required access scopes

Your app must have the following access scopes to make this request: update_store_profile

Path params

All path params are required.

Param
Type
Description

storeId

number

Ecwid store ID.

Headers

The Authorization header is required.

Header
Format
Description

Authorization

Bearer secret_ab***cd

Access token of the application.

Request JSON

A JSON object with the following fields:

Field
Type
Description

key

string

Specify unique extra field identificator, for example, "custom_question_1". Required

title

string

Title visible at the checkout above the extra field. Also appears in Ecwid admin and customer notifications (if added).

titleTranslated

Available translations for the extra field title.

type

string

Extra field type that defines its functionality.

One of: text - Single-line text input. Supports placeholders and pre-defined values (default). textarea - Multiple-line text input. Supports placeholders and pre-defined values. select - Drop-down list, where customers can choose only one value. Requires options array. radio_buttons - A group of radio buttons, where customers can choose only one value. Requires options array. checkbox - A group of checkboxes, where customers can choose multiple values. Requires options array. toggle_button_group - A group of buttons, where customers can choose only one value. Requires options array. datetime - Customizable date and time picker in the form of a calendar widget on the checkout. empty - Non-editable text visible at the checkout and unavailable in customer notifications and Ecwid admin.

textPlaceholder

string

Placeholder text for text and textarea field types. Does not affect the actual extra field value.

If not specified, the extra field won't have a placeholder.

textPlaceholderTranslated

Available translations for the text placeholder.

available

boolean

Set false to disable the extra field.

If not specified, the extra field is enabled.

required

boolean

Set true, to make the extra field required at the checkout. This way, customers won't be able to continue checkout until they type/select a value in the field.

If not specified, the extra field is not required at the checkout.

checkoutDisplaySection

string

Defines at which checkout step extra field shows to customers.

One of: email - First checkout step where customers enter their email and apply discounts. shipping_address - Second checkout step where customers enter their shipping address. pickup_details - Second checkout step where customers choose when and where they want to pick up an order. shipping_methods - Third checkout step where customers choose a shipping method. pickup_methods - Third checkout step where customers choose a pickup method. payment_details - Final checkout step where customers choose payment method and proceed to the payment.

If not specified, the extra field won't appear at the checkout, allowing you to store hidden order data or apply hidden extra charges to the order.

orderDetailsDisplaySection

string

Defines at which section the extra field shows in customer notifications and Ecwid admin.

One of: shipping_info - Shipping/pickup details. billing_info - Billing details. customer_info - Customer details. order_comments - Order comments left by a customer. hidden - Extra field is hidden from customer notifications and Ecwid admin.

If not specified, the extra field appears in the order_comments section.

showInInvoice

boolean

Set true to display the extra field in order tax invoices generated by Ecwid.

If not specified, the extra field will not be displayed in order tax invoices.

showInNotifications

boolean

Set true to display the extra field in customer emails generated by Ecwid. If true, requires orderDetailsDisplaySection.

If not specified, the extra field will not be displayed in order tax invoices.

value

string

Default value for the extra field. Any changes by customers or your scripts on the storefront override it.

If not specified, the extra field won't have any default value.

valueTranslated

Available translations for the extra field value.

subtitle

string

Subtitle visible under the extra field name at the checkout. If not specified, the extra field won't have a subtitle.

subtitleTranslated

Available translations for the extra field subtitle.

tip

string

Extra field tip for text and textarea field types visible inside the input at the checkout.

If not specified, the extra field won't have a tip.

tipTranslated

Available translations for the extra field tip.

showForPaymentMethodIds

array of strings

Make extra field available to only some payment methods by setting a list of payment method IDs. For example, you can collect additional data only for the specific online payment method by adding it alone to the list: "showForPaymentMethodIds": ["4959-2345934622523"].

If not specified, the extra field is not limited by any payment methods.

showForShippingMethodIds

array of strings

Make extra field available to only some shipping methods by setting a list of shipping method IDs. For example, you can collect additional data only for the store pickup method by adding it alone to the list: "showForShippingMethodIds": ["4959-2345934622523"].

If not specified, the extra field is not limited by any shipping methods.

showForCountry

array of strings

Make extra field available only for some countries by setting a list of country codes. Ecwid will automatically check customer's address details to display the field. For example, "showForCountry": ["BE", "US"].

If not specified, the extra field is not limited by the customer's address details.

options

Defines a list of available options for select, checkbox, radio_buttons, andtoggle_button_group field types.

If not specified, the field type is transformed to text.

datepickerOptions

Defines settings and conditions for the datepicker at the checkout. For example, limited working hours or disable weekends for the calendar.

Affects only datetime extra field type.

overrides

Defines overrides for extra fields. This setting allows setting up logic and conditional changes for extra fields on the checkout without actual JavaScript code.

orderBy

number

Sorting order for checkout extra fields in Sorting order for checkout extra fields on the order details page in Ecwid admin and in customer emails. Does not affect extra field's order at the checkout.

shownOnOrderDetails

boolean

Defines if the extra field should be visible on the order details page in Ecwid admin.

saveToCustomerProfile

boolean

Defines if the extra field should also be saved to customer extra fields.

options

Field
Type
Description

title

string

Option name visible at the checkout.

titleTranslated

Available translations for the option name.

subtitle

string

Subtitle visble under the option name at the checkout.

subtitleTranslated

Available translations for the option subtitle.

surcharge

number

Tip/surcharge value added to the order total cost.

surchargeType

string

Defines if a surcharge applies a fixed sum or a percentage increase to the cart total. One of: ABSOLUTE - Adds a fixed sum. PERCENT - Adds percentage increase.

surchargeTaxable

boolean

Defines if surcharge/tip is taxable.

showZeroSurchargeInTotal

boolean

Defines if zero-sum surcharge shows in order total breakdown.

Set false to hide zero-sum surcharges from customers at the checkout.

surchargeShortName

Defines how the surcharge shows in the "Shopping cart" block where the order total is calculated.

surchargeShortName

Field
Type
Description

name

string

Name of the surcharge for the "Shopping cart" block.

nameTranslated

Available translations for the surcharge short name.

showSurchargePercentValue

boolean

Defines if surcharge percentage value shows next to name. Default: true. Works only with PERCENT value in surchargeType.

datepickerOptions

Field
Type
Description

minDate

date

The earliest selectable date. Users can choose dates starting from this minimum date. Use a valid Date object.

maxDate

date

The latest selectable date. Users cannot choose dates beyond this maximum date. Use a valid Date object.

showtime

boolean

Defines if datepicker allows users to select the time. If true, time selection is enabled.

incrementMinuteBy

number

Increments for datepicker time frames (in minutes). For example, 30 means that customers can only choose from 17:00, 17:30, 18:00... on the checkout.

limitAvailableHoursWeekly

Set working hours for each day of the week. If this setting is added but some days are missing, Ecwid counts such days as disabled.

disallowDates

Disables specific ranges of date and time. For example, you can make the datepicker required and disable or limit holiday working hours.

limitAvailableHoursWeekly

Limit working hours by setting daily time ranges when the store is open. You can add several time ranges to one day if you have a lunch hour, for example.

Format: JSON object with one or several weekdays, each having an array of time ranges (also in the array format.

Code example
{
    "MON": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "TUE": [
        ["08: 30", "17: 30"]
    ],
    "WED": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "THU": [
        ["08: 30", "17: 30"]
    ],
    "FRI": [
        ["08: 30", "13: 30"],
        ["14: 00", "17: 30"]
    ],
    "SAT": [
        ["08: 30", "17: 30"]
    ],
    "SUN": [
        ["10: 00", "14: 00"]
    ]
}

disallowDates

Disable specific dates or date ranges to close the store for holidays, for example.

Format: JSON array with one or several arrays, each having a date or datetime range formatted to the "YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD HH:MM:SS" string.

Code example
{
    "disallowDates": [
        // Disallow placing/shipping orders for the specific day after 3 PM.
        ["2024-04-25 15:00:00", "2024-04-25 23:59:59"],
        // Close the store for 3 days.
        ["2024-04-26 00:00", "2024-04-29 00:00"]
    ]
}

overrides

Field
Type
Description

conditions

Conditions for the override. When conditions are met, override happens automatically.

fieldsToOverride

Set up the datePickerOptions object with a new logic inside. When conditions are met, it will override defult datepicker behavior.

conditions

Field
Type
Description

shippingMethod

string

Selected shipping method name, for example. 'Pickup at North st'

translated

Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:

{
    "en": "Sample text",
    "nl": "Voorbeeldtekst"
}

Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.

Response JSON

A JSON object with the following fields:

Field
Type
Description

createCount

number

The number of created items that defines if the request was successful.

1 if the item was created

Last updated 3 months ago

Was this helpful?

object

object

object

object

object

array of objects

object

object

object

oobject

object

object

object

array

object

object

translated
translated
translated
translated
translated
options
datepickerOptions
translated
translated
translated
surchargeShortName
translated
limitAvailableHoursWeekly
disallowDates
conditions
datePickerOptions