> To build or manage a Wix site with an AI agent, follow https://www.wix.com/headless/skill.md
> It builds a new Wix site or puts your own site online, from a prompt, and keeps changing it afterwards. The pages are code in any web technology, and Wix runs the backend.
> It works through the Wix plugin (the Wix MCP and the Wix skills), the Wix CLI or no Wix login, and puts the site live on Wix hosting or on another host.
> Business features include a store, bookings, events and tickets, a restaurant, a blog, forms, members and many more.
> Read the Wix skills online at https://www.wix.com/skills
> 
> 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`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - 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: Add Custom Fields to a Wix Object in Studio Two

## Article: Add Custom Fields to a Wix Object in Studio Two

## Article Link: https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/schema-plugins/add-custom-fields-to-a-wix-object-in-studio-two.md

## Article Content:

# Add Custom Fields to a Wix Object in Studio Two

Add custom fields to a Wix object, such as a product or a booking, with a [schema plugin](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/schema-plugins/about-schema-plugins.md). An [HTTP endpoint](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/http-endpoints/about-http-endpoints.md) in your site project adds the fields to the object's schema. Your code then sets and reads the fields' values through the object's own API.

The examples add a `warranty` field to Wix Stores products, so they need a site that uses Wix Stores Catalog V3. For the other objects you can extend, see [Supported Objects](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/supported-objects.md).

Follow the instructions below to:

1. Install the schema plugin package.
2. Add an HTTP endpoint that adds the fields.
3. Call the endpoint from a dashboard page.
4. Set and read the field values.

## Step 1 | Install the schema plugin package

The endpoint calls the Data Extension Schema API from `@wix/data-extension-schema`. If your project doesn't include that package, [install the package](https://dev.wix.com/docs/studio-two/code-your-site/developer-environment/packages/work-with-npm-packages.md). On the **Code** tab, open the terminal and run `npm install @wix/data-extension-schema`. Step 4 also uses `@wix/stores`, which a site project includes when it's created.

## Step 2 | Add an HTTP endpoint that adds the fields

A site has at most one schema for its own fields on each object, in the `_user_fields` namespace. The endpoint creates that schema the first time and adds your fields to it after that. Your endpoint needs to:

- Allow only Wix users and reject every other caller with a `403` response. See [Check the caller](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/http-endpoints/build-an-http-endpoint-in-studio-two.md#step-4--check-the-caller).
- Define the fields in code. Don't take a field definition from the request.
- Call the schema API with the caller's own permissions, so Wix checks that the caller's role allows the change.

To add the endpoint:

1. Add an HTTP endpoint extension, as in Step 1 of [Add an HTTP Endpoint Extension in Studio Two](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/http-endpoints/add-an-http-endpoint-extension-in-studio-two.md#step-1--add-an-http-endpoint). The examples use `product-fields` as the endpoint's **Name**.
2. Replace the contents of `src/api/product-fields.ts` with the following code, which adds a `warranty` field to products:

   ```ts
   import type { APIRoute } from '@wix/custom-extensions/types';
   import { auth } from '@wix/essentials';
   import { schemas } from '@wix/data-extension-schema';

   const FQDN = 'wix.stores.catalog.*.product';

   const FIELDS = {
     warranty: {
       type: 'string',
       maxLength: 50,
       'x-wix-permissions': {
         read: ['users-of-users', 'users', 'apps'],
         write: ['users', 'apps'],
       },
     },
   };

   export const POST: APIRoute = async () => {
     const tokenInfo = await auth.getTokenInfo();
     if (tokenInfo.subjectType !== 'USER') {
       return Response.json({ error: 'Only Wix users can add fields.' }, { status: 403 });
     }

     const { dataExtensionSchemas } = await schemas.listDataExtensionSchemas(FQDN, { namespaces: ['_user_fields'] });
     const existing = dataExtensionSchemas?.[0];

     if (!existing) {
       const created = await schemas.createDataExtensionSchema({
         fqdn: FQDN,
         namespace: '_user_fields',
         jsonSchema: { properties: FIELDS },
       });
       return Response.json({ schemaId: created._id });
     }

     const { dataExtensionSchema } = await schemas.updateDataExtensionSchema({
       _id: existing._id!,
       revision: existing.revision!,
       jsonSchema: {
         ...existing.jsonSchema,
         properties: { ...existing.jsonSchema?.properties, ...FIELDS },
       },
     });
     return Response.json({ schemaId: dataExtensionSchema?._id });
   };
   ```

3. Save the file.

`FQDN` names the object to extend. `wix.stores.catalog.*.product` is the FQDN for Wix Stores products.

The code defines each field with a `type` and `x-wix-permissions`. A string field also needs a `maxLength`. In `x-wix-permissions`, `read` lets site visitors, Wix users, and apps read the value, and `write` lets Wix users and apps set it. Leave out `users-of-users` for data that site visitors shouldn't see. For every field type and rule, see [The JSON Schema](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/the-json-schema.md). For each permission value, see [Field permissions](https://dev.wix.com/docs/backend-extensions/schema-plugins/about-schema-plugins.md#field-permissions).

[List Data Extension Schemas](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/list-data-extension-schemas.md) finds the object's `_user_fields` schema. If there isn't one, [Create Data Extension Schema](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/create-data-extension-schema.md) creates it. Otherwise, [Update Data Extension Schema](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/update-data-extension-schema.md) adds your fields. The update specifies the schema's current `revision` and keeps every field the schema already has, because an update that drops a field fails. If a field is already in the schema, change it only in ways the [rules for changing a schema](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/schema-plugins/about-schema-plugins.md#rules-for-changing-a-schema) allow.

At the end of this step, your site project has an endpoint that adds the `warranty` field to products.

## Step 3 | Call the endpoint from a dashboard page

Call the endpoint when you add or change fields. Call it from a [dashboard page](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-dashboard/dashboard-pages/about-dashboard-pages.md), which opens only for Wix users and whose calls carry their identity.

In the code of your dashboard page, call the endpoint with `httpClient.fetchWithAuth()` from `@wix/essentials`, for example from a button's click handler:

```ts
import { httpClient } from '@wix/essentials';

async function addProductFields() {
  const response = await httpClient.fetchWithAuth('/product-fields', { method: 'POST' });
  if (!response.ok) {
    throw new Error(`Couldn't add the fields. The endpoint returned status ${response.status}.`);
  }
}
```

A dashboard page can call an endpoint by its path, such as `/product-fields`. For how to add a dashboard page, see [Add a Dashboard Page Extension in Studio Two](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-dashboard/dashboard-pages/add-a-dashboard-page-extension-in-studio-two.md).

When the call succeeds, the endpoint returns the schema's ID, and products have a `warranty` field.

## Step 4 | Set and read the field values

A field's value is part of the object. Set and read it through the object's own API, under `extendedFields.namespaces._user_fields`.

For example, an endpoint can set a product's warranty with [Update Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/update-product.md) and return the saved value. It calls the product API with the caller's own permissions.

To add the endpoint:

1. Add another HTTP endpoint extension, as in Step 2, named `product-warranty`.
2. Replace the contents of `src/api/product-warranty.ts` with the following code:

   ```ts
   import type { APIRoute } from '@wix/custom-extensions/types';
   import { auth } from '@wix/essentials';
   import { productsV3 } from '@wix/stores';

   export const POST: APIRoute = async ({ request }) => {
     const tokenInfo = await auth.getTokenInfo();
     if (tokenInfo.subjectType !== 'USER') {
       return Response.json({ error: 'Only Wix users can set the warranty.' }, { status: 403 });
     }

     let body;
     try {
       body = await request.json();
     } catch {
       return Response.json({ error: 'Send the request body as JSON.' }, { status: 400 });
     }

     const productId = body?.productId;
     const warranty = body?.warranty;
     if (typeof productId !== 'string' || typeof warranty !== 'string' || warranty.length > 50) {
       return Response.json(
         { error: 'Send a product ID and a warranty of up to 50 characters.' },
         { status: 400 },
       );
     }

     const product = await productsV3.getProduct(productId);
     const updated = await productsV3.updateProduct(productId, {
       revision: product.revision,
       extendedFields: { namespaces: { _user_fields: { warranty } } },
     });

     return Response.json({ warranty: updated.extendedFields?.namespaces?._user_fields?.warranty });
   };
   ```

3. Save the file. Then call the endpoint from your dashboard page as in Step 3, and send the product ID and the warranty in the request body:

   ```ts
   const response = await httpClient.fetchWithAuth('/product-warranty', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ productId, warranty }),
   });
   ```

To read the value, get the product with [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product.md). The value is in `product.extendedFields.namespaces._user_fields.warranty`.

To remove a field later, call [Delete User Defined Fields](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/delete-user-defined-fields.md) with the schema ID and the field's name.

## See also

- [About Schema Plugins](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/schema-plugins/about-schema-plugins.md)
- [Build an HTTP Endpoint in Studio Two](https://dev.wix.com/docs/studio-two/code-your-site/build-a-custom-backend/http-endpoints/build-an-http-endpoint-in-studio-two.md)
- [Data Extension Schema API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction.md)