> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: Extend an Existing Object with a Site-Specific Field ## Article: Extend an Existing Object with a Site-Specific Field ## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/extend-an-existing-object-with-a-site-specific-field.md ## Article Content: # 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](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction.md) to access and manage the site's `_user_fields` namespace. Unlike [schema plugins](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) 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. > **Note:** This tutorial focuses on site-specific fields. For global schema plugins that affect all users, see [About Schema Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) and [Extend an Existing Object](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/extend-an-existing-object.md). This tutorial demonstrates how to: 1. Identify the [FQDN (Fully Qualified Domain Name)](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-fqdns.md) 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](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-fqdns.md) 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.services.*.service` ## Step 2 | Check for an existing site-specific schema Call [List Data Extension Schemas](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/list-data-extension-schemas.md) 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. ::::tabs :::REST ``` curl -X GET \ 'https://www.wixapis.com/schema-service/v1/schemas?fqdn=wix.ecom.*.order' \ -H 'Content-type: application/json' \ -H 'Authorization: ' ``` ::: :::SDK ``` import { schemas } from "@wix/data-extension-schema"; async function listDataExtensionSchemas() { const response = await schemas.listDataExtensionSchemas({ fqdn: "wix.ecom.*.order" }); // Check if _user_fields namespace exists const userFieldsSchema = response.dataExtensionSchemas.find(schema => schema.namespace === "_user_fields" ); return userFieldsSchema || null; } ``` ::: :::: ## 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](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/create-data-extension-schema.md) to create one, and include your custom field. This example creates a field called `alcoholByVolume` for tracking wine ABV: ::::tabs :::REST ``` curl -X POST \ 'https://www.wixapis.com/schema-service/v1/schemas' \ -H 'Content-type: application/json' \ -H 'Authorization: ' \ -d '{ "dataExtensionSchema": { "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "properties": { "alcoholByVolume": { "type": "number", "minimum": 0, "maximum": 100, "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } } } } } }' ``` ::: :::SDK ``` import { schemas } from "@wix/data-extension-schema"; async function createDataExtensionSchema() { const response = await schemas.createDataExtensionSchema({ dataExtensionSchema: { fqdn: "wix.ecom.*.order", namespace: "_user_fields", jsonSchema: { properties: { alcoholByVolume: { type: "number", minimum: 0, maximum: 100, "x-wix-permissions": { read: ["users-of-users", "users", "apps"], write: ["users"] } } } } } }); return response; } ``` ::: :::: ### Update an existing schema If a `_user_fields` namespace schema already exists for the site, call [Update Data Extension Schema](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/update-data-extension-schema.md) to update it with your new field. This example adds the `alcoholByVolume` field to an existing schema that already has other fields: ::::tabs :::REST ``` curl -X PUT \ 'https://www.wixapis.com/schema-service/v1/schemas' \ -H 'Content-type: application/json' \ -H 'Authorization: ' \ -d ' { "dataExtensionSchema": { "id": "01ea0c8d-80b8-46e3-bfda-611b3678545b", // Get this from the existing schema response "fqdn": "wix.ecom.*.order", "namespace": "_user_fields", "jsonSchema": { "additionalProperties": false, "properties": { "specialInstructions": { "maxLength": 500, "type": "string", "x-wix-created-date": "2024-10-08T12:13:38.592731806Z", "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } }, "alcoholByVolume": { "minimum": 0, "maximum": 100, "type": "number", "x-wix-created-date": "2024-10-08T12:13:38.592731806Z", "x-wix-permissions": { "read": [ "users-of-users", "users", "apps" ], "write": [ "users" ] } } } }, "revision": "2" } } ' ``` ::: :::SDK ``` import { schemas } from "@wix/data-extension-schema"; async function updateDataExtensionSchema(schemaId, existingSchema) { // Get the current revision and increment it const currentRevision = parseInt(existingSchema.revision) + 1; const response = await schemas.updateDataExtensionSchema({ dataExtensionSchema: { id: schemaId, // Passed from Step 2 fqdn: "wix.ecom.*.order", namespace: "_user_fields", jsonSchema: { additionalProperties: false, properties: { // Include existing fields from the schema. Existing fields keep their original `x-wix-created-date metadata` ...existingSchema.jsonSchema.properties, // Add the new field alcoholByVolume: { minimum: 0, maximum: 100, type: "number", "x-wix-created-date": new Date().toISOString(), "x-wix-permissions": { read: ["users-of-users", "users", "apps"], write: ["users"] } } } }, revision: currentRevision.toString() } }); return response; } // Usage: Call this after getting the schema data from Step 2 const existingSchema = await listDataExtensionSchemas(); if (existingSchema) { await updateDataExtensionSchema(existingSchema.id, existingSchema); } ``` ::: :::: ## 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md), 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: ```json { "id": "order123", "buyerInfo": { ... }, "extendedFields": { "namespaces": { "_user_fields": { "specialInstructions": "Handle with care - fragile", "alcoholByVolume": 14.5 } } } } ``` Note that you can delete your custom fields as necessary by calling [Delete User Defined Fields](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/delete-user-defined-fields.md). ## See also - [JSON Schema validation rules](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/the-json-schema.md) - [Schema Plugin FAQ](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/schema-plugin-faq.md) - [Data extension API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction.md)