post https://app.ecwid.com/api/v3//profile/extrafields
Create a new extra field for a store.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization | string | 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, toggle_button_group, radio_buttons, datetime, empty. 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, radiobuttons or toggleButtonGroup 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 |
| options → surcharge | number | 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 |
Error response body (optional)
| Field | Type | Description |
|---|---|---|
| errorMessage | string | Error message |