oAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token.
Request
A JSON array with elements of type 'ExtraField' with the following fields:
ExtraField
Field
Type
Description
key
string
Key of the custom checkout field in a store
title
string
Custom field title at checkout
checkoutDisplaySection
string
Accepts several values: email, shipping_address, pickup_details, shipping_methods, pickup_methods, payment_details. If the field is missing or an unsupported value is used, the field will be hidden from customer and merchant
orderDetailsDisplaySection
string
Defines where the extra field values will be shown to customer and merchant. Supported values: shipping_info, billing_info, customer_info, order_comments. More on this in Show extra fields in an order section.
value
string
Default value used to prefill the extra field's value for user
type
string
Accepts several values: text, textarea, select, checkbox, toggleButtonGroup, radiobuttons, datetime, label. Default is text. More on this below
tip
string
Show a tip for filling the field under the input (ignored if type is textarea or checkbox)
available
boolean
If true, the field is shown and saved as an extra field. If false, the field completely ignored. true is default
textPlaceholder
string
A text placeholder for text and textarea input fields
options
Array<options>
Several options to choose from the select field, checkbox, radio_buttons or toggle_button_group buttons. If selectOptions is not set, field is transformed to text type
required
boolean
If not specified the default value is false. Set true to prevent continuing checkout if an extra field is ignored by customers
showInInvoice
boolean
If not specified the default value is false. Set true to show extra field in order invoices.
showInNotifications
boolean
If not specified the default value is false. Set true to show extra field in order emails. orderDetailsDisplaySection sets the part where the extra field will appear.
surcharge
number
Surcharge numerical value
surchargeType
string
This attribute allows setting surcharge as a fixed sum to the cart total or a percentage sum depending on the cart total. Accepts ABSOLUTE and PERCENT values.
surchargeShortName
Obj<surchargeShortName>
Surcharge name in the cart details section (where subtotal, discount, total, etc values are shown). If this attribute is not specified, the default !Surcharge.default_text! name will be shown on the cart details section
Surcharge attribute can be specified in each object inside options array. If the extra field surchargeType is ABSOLUTE, Ecwid will add a fixed sum to the order total specified in the surcharge attribute. If the extra field surchargeType is PERCENT, Ecwid will calculate the sum for a surcharge based on the order total and percentage value specified in the surcharge attribute.
showZeroSurchargeInTotal
boolean
If not specified, the default value is true. If true, the surcharge name and its 0 value will be shown on the cart details section (if the surcharge attribute is set to 0 or not specified inside the options array). If false, 0 surcharge name and its value won't be shown on the cart details section.
surchargeTaxable
boolean
Defines if taxes should be applied to the surcharge.
showForPaymentMethodIds
Array of strings
Detects whether an extra field should be visible for some certain payment methods only. Contains payment method IDs for which an extra field should be visible. E.g. "showForPaymentMethodIds": ["4959-1595934622523","4959-2345934622523"].
showForShippingMethodIds
Array of strings
Detects whether an extra field should be visible for some certain shipping methods only. Contains shipping method IDs for which an extra field should be visible. E.g. "showForShippingMethodIds": ["4969-1534934622531","4969-2348834622511"].
showForCountry
Array of strings
Detects whether an extra field should be visible for certain countries only. Contains ISO country codes for which an extra field should be visible. E.g. "showForCountry": ["RU", "US"].
titleTranslated
obj<Translations>
keeps the translations for extra field title
tipTranslated
obj<Translations>
keeps the translations for extra field tip
valueTranslated
obj<Translations>
keeps the translations for extra field value
textPlaceholderTranslated
obj<Translations>
keeps the translations for extra field textPlaceholder
selectOptionsTranslated
obj<Translations>
keeps the translations for extra field selectOptionsTranslated
surchargeShortNameTranslated
obj<Translations>
keeps the translations for extra field surchargeShortNameTranslated
Translations
Field
Type
Description
<ISO_LANG_CODE>
string
Translations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings
Errors
Error response example:
HTTP/1.1 400 Field Extrafields.title is absent
Content-Type application/json; charset=utf-8
In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description
HTTP codes
HTTP Status
Description
400
Request parameters are invalid
403
Access token doesn't have update_store_profile scope
500
Cannot perform a request because of an error on the server
