> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> 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)