Extend an Existing Object with a Site-Specific Field

This tutorial shows you how to add custom fields to a Wix API object for a specific site using the Data Extension Schema API to access and manage the site's _user_fields namespace. Unlike schema plugins that affect all your app's users, this approach creates a field that only affects the specified site.

For example, if you're building a product management app used by many different stores, and one specific wine store wants to add an "Alcohol by Volume (ABV)" field to their orders. Other stores using your app (like clothing stores or electronics shops) won't see this field. This is perfect for site-specific customizations that don't apply globally.

As your app grows and serves diverse businesses, you may find that one-size-fits-all fields don't work for every client. When users request custom fields for their specific business needs, site-specific fields allow you to offer personalized functionality without cluttering the interface for users who don't need those features, or when different industries require different data structures.

This tutorial demonstrates how to:

1. Identify the FQDN (Fully Qualified Domain Name) for the target API object. For purposes of this tutorial, we will use the eCommerce Order object FQDN.
2. Check for existing site-specific data extension schemas for the specific site.
3. Create or update the schema with custom fields for that site.
4. Display the custom fields in your application.

Step 1 | Identify the API object FQDN

First, determine the FQDN of the Wix API object you want to extend for the specific site.

FQDNs are available in most event payloads. Events that return FQDNs will have the entityFqdn field documented in their event reference, and the FQDN is returned as entityFqdn in the event data.

Common FQDNs include:

• Wix eCommerce Orders: wix.ecom.*.order
• Wix eCommerce Checkout: wix.ecom.*.checkout
• Wix Bookings Services: wix.bookings.*.service

Step 2 | Check for an existing site-specific schema

Call List Data Extension Schemas to check if a site-specific schema already exists for the specific FQDN on the site by and for a _user_fields namespace. The _user_fields namespace is a special namespace reserved for site-specific custom fields. If the _user_fields namespace exists, collect the data extension schema ID and its existing data for the next step.

Step 3 | Create or update the user-defined schema

Based on whether a site-specific _user_fields schema exists, you'll either create a new one or update the existing one.

Create a new schema

If no _user_fields namespace schema exists for the site, call Create Data Extension Schema to create one, and include your custom field. This example creates a field called alcoholByVolume for tracking wine ABV:

Update an existing schema

If a _user_fields namespace schema already exists for the site, call Update Data Extension Schema to update it with your new field. This example adds the alcoholByVolume field to an existing schema that already has other fields:

Step 4 | Display site-specific fields

Once you've added a site-specific field to the site's schema, you should call the relevant GET call for the target API object, in this case, Get Order, every time a visitor navigates to your UI to collect and display the user fields.

The custom fields will be available in the extendedFields property of the API object. For example, when querying an eCommerce order, the custom fields will appear as:

See also

• JSON Schema validation rules
• Schema Plugin FAQ
• Data extension API