About the Data Extension Schema API

A data extension schema is the JSON schema within a schema plugin extension defining extendedFields that are added to a Wix API's service object. For example, a data extension schema might add custom shipping data to the Wix eCommerce Checkout object.

The Data Extension Schema API enables you to:

Learn more about reading and writing schema plugin fields

User-defined data extension schemas

A user-defined data extension schema is created when a Wix user (site owner or collaborator) creates their own extended fields. For example, Wix users can add their own fields to the checkout flow in the site's dashboard under Settings > Checkout > Checkout form and editing the checkout form:

Checkout extended fields

Before you begin

It’s important to note the following points before starting to code:

  • App schema plugin extensions, including their JSON schemas, are created and maintained in your app dashboard. This API only supports creating and updating user-defined schemas.
  • Schema plugin extensions are supported by select Wix API service objects. Always check that the service object you would like to extend supports this functionality.
  • This API supports retrieving data extension schemas from multiple namespaces in a single call.
  • You can only retrieve schemas associated with extensions installed on the specific site authenticated in the API call.
  • Namespace name limitations:
    • Can't include "Wix".
    • Only lowercase letters, numbers, hyphens and underscores are supported.
    • Max length: 164 characters.
    • Once set, namespace names can't be changed.

Use cases

Terminology

  • Data extension schema: A JSON schema defining the fields to be added to a Wix service object.
  • FQDN: Fully qualified domain name, a unique identifier for a Wix service object. Learn more about FQDNs.
  • Namespace: A unique identifier for your app or project. Expected format is @myCompany/myAppName. See limitations in the Before you begin section above.
  • Schema plugin extension: Specific functionality that extends a Wix service object with custom fields, nested within the object called extendedFields.
  • User-defined schema: The schema created when a Wix user creates their own extended fields. This schema is created with the namespace: _user_fields.
Did this help?

Sample Flows

This article shares some possible use cases you could support, as well as an example flow that could support each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.

Retrieve a list of all data extension schemas for the Wix eCommerce Checkout object

If your functionality requires access to fields that have been added to an object, you might want to retrieve all of the schemas at once. For example, displaying the returned fields in a widget.

  1. Collect the FQDN of the relevant Wix API service object that supports schema plugin extensions. FQDNs are also returned as entityFqdn in most events. The Wix eCommerce Checkout FQDN is wix.ecom.v1.checkout.
  2. Choose the namespaces you would like to retrieve this data for. You can pass multiple namespaces in one call, or leave it blank to retrieve all available namespaces.
  3. Call List Data Extension Schemas with the FQDN and namespace data.
  4. Display the returned data in your extension as relevant.

Add a field to a user-defined data extension schema for the Wix eCommerce Order object

Display a site-specific field, such as alcohol by volume (ABV) for whiskey orders, alongside fields from Wix eCommerce Orders, in a widget.

  1. Collect the FQDN of the relevant Wix API service object that supports schema plugin extensions. FQDNs are also returned as entityFqdn in most events. The Wix eCommerce Order FQDN is wix.ecom.v1.order.
  2. Call List Data Extension Schemas with the wix.ecom.v1.order FQDN and _user_fields namespace to check if a user-defined schema exists.
  3. Create or update the _user_fields namespace, as relevant:
    1. If no _user_fields namespace schema exists, call Create Data Extension Schema with the wix.ecom.v1.order FQDN, the _user_fields namespace and the new JSON schema.
    2. If a _user_fields namespace schema already exists, call Update Data Extension Schema with the wix.ecom.v1.order FQDN, the _user_fields namespace and the updated JSON schema.
  4. Display the user-defined field in your widget.

Note: Once you have added at least one user-defined field, you should call List Data Extension Schemas every time a user navigates to your widget, to collect and display the user fields.

Did this help?

Data Extension Schema Object


Properties
idstringRead-onlyformat GUID

Schema ID.


fqdnstringmaxLength 255

FQDN of the entity this schema extends.


namespacestringmaxLength 164

Namespace for this schema. For example, an app creating schemas might use their app name as a namespace. When a site owner creates a user-defined schema, the namespace is: _user_fields.


jsonSchemastruct

Schema definition in JSON schema format with the following vocab extension:

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://wixapis.com/v1/json-schema/extensions", "$vocabulary": { "https://wixapis.com/v1/json-schema/extensions/vocab/data-extensions": true }, "$dynamicAnchor": "meta", "title": "Wix' data-extensions vocabulary meta schema", "type": [ "object", "boolean" ], "properties": { "x-wix-permissions": { "type": "object", "description": "list of identity types that are allowed reading schema properties", "properties": { "read": { "type": "array", "items": { "type": "string", "enum": [ "apps", "owning-app", "users", "users-of-users" ] } }, "write": { "type": "array", "items": { "type": "string", "enum": [ "apps", "owning-app", "users", "users-of-users" ] } } } }, "x-wix-display": { "type": "object", "description": "field display properties", "schema": { "properties": { "placeholder": { "type": "string", "maxLength": 255, "description": "placeholder text for input fields" }, "label": { "type": "string", "maxLength": 255, "description": "label of the input fields" }, "hint": { "type": "string", "maxLength": 255, "description": "a short explanation that appears next to the input field" } } } } } }

updatedDatestringRead-onlyformat date-time

Date and time the schema was last updated.


createdDatestringRead-onlyformat date-time

Date and time the schema was created.


revisionintegerRead-onlyformat int64

Revision number, which increments by 1 each time the schema is updated. To prevent conflicting changes, the existing revision must be used when updating a schema.


maxLimitBytesintegerRead-onlyformat int32

Maximum allowed schema size in bytes.


currentSizeBytesintegerRead-onlyformat int32

Current schema size in bytes.

Did this help?

PUT

Update Data Extension Schema


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates a user-defined data extension schema, overriding the existing data.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Data Extensions Schemas
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
PUT
https://www.wixapis.com/schema-service/v1/schemas

Body Params
dataExtensionSchemaDataExtensionSchema

Schema to update.

Response Object
dataExtensionSchemaDataExtensionSchema

Updated schema.

Update Data Extension Schema Example 1
Request
cURL
curl -X PUT \ 'https://www.wixapis.com/schema-service/v1/schemas' \ -H 'Content-type: application/json' \ -H 'Authorization: <AUTH>' \ -d ' { "dataExtensionSchema": { "id": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "additionalProperties": false, "properties": { "myCustomField1": { "maxLength": 75, "type": "string", "x-wix-created-date": "2024-10-08T12:13:38.592731806Z", "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } }, "myCustomField2": { "maxLength": 100, "type": "string", "x-wix-created-date": "2024-10-08T12:13:38.592731806Z", "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } } } }, "revision": "2" } } '
Response
JSON
{ "dataExtensionSchema": { "id": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "properties": { "myCustomField1": { "type": "string", "maxLength": 75, "x-wix-permissions": { "read": ["users-of-users", "users", "apps"], "write": ["users"] }, "x-wix-created-date": "2024-10-08T12:13:38.592731806Z" }, "myCustomField2": { "type": "string", "maxLength": 100, "x-wix-permissions": { "read": ["users-of-users", "users", "apps"], "write": ["users"] }, "x-wix-created-date": "2024-10-08T12:30:44.854371962Z" } }, "additionalProperties": false }, "updatedDate": "2024-10-08T12:35:50.909Z", "createdDate": "2024-10-08T12:13:38.639Z", "revision": "3", "maxLimitBytes": 10000, "currentSizeBytes": 175, "extensionPoint": "ROOT" } }
Event TriggersThis method triggers the following events:
Did this help?

GET

List Data Extension Schemas


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of global and user-defined data extension schemas for a given FQDN.

Permissions
Manage Bookings Services and Settings
Manage Data Extensions Schemas
Manage Portfolio
Read Data Extensions Schemas
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/schema-service/v1/schemas

Query Params
fqdnstringRequired

namespacesArray <string>

Namespaces within the given entity.


fieldsArray <string>

Additional fields that are hidden by default. For example, fields with "x-wix-archived": true.


extensionPointsArray <string>

Extension points within the given entity.

Response Object
dataExtensionSchemasArray <DataExtensionSchema>

Requested schemas.

List Data Extension Schemas Example 1
Request
cURL
curl -X GET \ 'https://www.wixapis.com/schema-service/v1/schemas?fqdn=wix.ecom.%2A.order' \ -H 'Content-type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "dataExtensionSchemas": [ { "id": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "properties": { "myCustomField1": { "type": "string", "maxLength": 50, "x-wix-permissions": { "read": ["users-of-users", "users", "apps"], "write": ["users"] }, "x-wix-created-date": "2024-10-08T12:13:38.592731806Z" } }, "additionalProperties": false }, "updatedDate": "2024-10-08T12:13:38.639Z", "createdDate": "2024-10-08T12:13:38.639Z", "revision": "1", "maxLimitBytes": 10000, "currentSizeBytes": 50, "extensionPoint": "ROOT" } ] }
Did this help?

POST

Create Data Extension Schema


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates a user-defined data extension schema.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Data Extensions Schemas
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/schema-service/v1/schemas

Body Params
dataExtensionSchemaDataExtensionSchemaRequired

Schema to create.

Response Object
dataExtensionSchemaDataExtensionSchema

Created schema.

Create Data Extension Schema Example 1
Request
cURL
curl -X POST \ 'https://www.wixapis.com/schema-service/v1/schemas' \ -H 'Content-type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "dataExtensionSchema": { "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "properties": { "myCustomField1": { "type": "string", "maxLength": 50, "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } } } } } }'
Response
JSON
{ "dataExtensionSchema": { "id": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "additionalProperties": false, "properties": { "myCustomField1": { "maxLength": 50, "type": "string", "x-wix-created-date": "2024-10-08T12:13:38.592731806Z", "x-wix-permissions": { "read": ["users-of-users", "users", "apps"], "write": ["users"] } } } }, "updatedDate": "2024-10-08T12:13:38.639Z", "createdDate": "2024-10-08T12:13:38.639Z", "revision": "1", "maxLimitBytes": 10000, "currentSizeBytes": 50, "extensionPoint": "ROOT" } }
Event TriggersThis method triggers the following events:
Did this help?

Data Extension Schema Created


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a data extension schema is created.

Permissions
Manage Bookings Services and Settings
Manage Data Extensions Schemas
Manage Portfolio
Read Data Extensions Schemas
Manage Restaurants - all permissions
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.data_extensions.v1.data_extension_schema_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

DataExtensionSchemaCreated
JSON
{ "id": "53eebc77-16ce-4bea-a558-3b793d01ed59", "entityFqdn": "wix.data_extensions.v1.data_extension_schema", "slug": "created", "entityId": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "createdEvent": { "entityAsJson": "{\"id\":\"01ea0c8d-80b8-46e3-bfda-611b3678545b\",\"fqdn\":\"wix.ecom.*.order\",\"namespace\":\"_user_fields\",\"jsonSchema\":{\"properties\":{\"myCustomField1\":{\"type\":\"string\",\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:13:38.592731806Z\",\"maxLength\":50.0}},\"additionalProperties\":false},\"updatedDate\":\"2024-10-08T12:13:38.639Z\",\"createdDate\":\"2024-10-08T12:13:38.639Z\",\"revision\":\"1\",\"maxLimitBytes\":10000,\"currentSizeBytes\":50,\"extensionPoint\":\"ROOT\"}" }, "eventTime": "2024-10-08T12:13:38.779083434Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "1" }
Did this help?

Data Extension Schema Deleted


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a data extension schema is deleted.

Permissions
Manage Bookings Services and Settings
Manage Data Extensions Schemas
Manage Portfolio
Read Data Extensions Schemas
Manage Restaurants - all permissions
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.data_extensions.v1.data_extension_schema_deleted", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?

Data Extension Schema Updated


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a data extension schema is updated.

Permissions
Manage Bookings Services and Settings
Manage Data Extensions Schemas
Manage Portfolio
Read Data Extensions Schemas
Manage Restaurants - all permissions
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.data_extensions.v1.data_extension_schema_updated", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }

DataExtensionSchemaUpdated
JSON
{ "id": "bf73a5be-d435-4402-a42a-8c041e9d659c", "entityFqdn": "wix.data_extensions.v1.data_extension_schema", "slug": "updated", "entityId": "01ea0c8d-80b8-46e3-bfda-611b3678545b", "updatedEvent": { "currentEntityAsJson": "{\"id\":\"01ea0c8d-80b8-46e3-bfda-611b3678545b\",\"fqdn\":\"wix.ecom.*.order\",\"namespace\":\"_user_fields\",\"jsonSchema\":{\"properties\":{\"myCustomField1\":{\"type\":\"string\",\"maxLength\":75.0,\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:13:38.592731806Z\"},\"myCustomField2\":{\"type\":\"string\",\"maxLength\":100.0,\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:30:44.854371962Z\"}},\"additionalProperties\":false},\"updatedDate\":\"2024-10-08T12:35:50.909Z\",\"createdDate\":\"2024-10-08T12:13:38.639Z\",\"revision\":\"3\",\"maxLimitBytes\":10000,\"currentSizeBytes\":175,\"extensionPoint\":\"ROOT\"}", "modifiedFields": { "updatedDate": "2024-10-08T12:30:45.011Z", "revision": "2" } }, "eventTime": "2024-10-08T12:35:50.996331444Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "3" }
Did this help?