> 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 Object with Custom Fields

## Article: Extend an Object with Custom Fields

## Article Link: https://dev.wix.com/docs/develop-websites-sdk/code-your-site/extend-wix-business-solutions/data-extension-schemas/extend-an-object-with-custom-fields.md

## Article Content:

# Extend an Existing Object with Custom Fields

This article shows you how to add custom fields to a Wix API object using [data extension schemas](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/extend-wix-business-solutions/data-extension-schemas/about-data-extension-schemas.md) and the [Data Extension Schema API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction.md).

## 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 [supported Wix API object](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/extend-wix-business-solutions/data-extension-schemas/about-data-extension-schemas.md#supported-objects) you want to extend.

The examples in this article use the [eCommerce Order object](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/introduction.md) FQDN:

```js
wix.ecom.*.order
```

## Step 2 | Check for an existing data extension 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 data extension schema already exists for the FQDN, and whether the `_user_fields` namespace is present. The `_user_fields` namespace is reserved for site-specific custom fields. If it exists, collect the data extension schema ID and its existing data for the next step.

```
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.

::::tabs

:::Create

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:

```
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

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.

> **Note**: You must include all existing custom fields when you update a schema. To remove fields, call [Delete User Defined Fields](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/delete-user-defined-fields.md).


 This example adds the `alcoholByVolume` field to an existing schema that already has other fields:

```
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 | Set and display custom fields

Once you've added a custom field to an object, call the relevant method for the target API object to set the values of your custom fields. For example, when calling [Create Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/create-order.md), include your custom field values in the method parameters: 

```json
{
  "order": {
    "lineItems": [...],
    "channelInfo": {...},
    "priceSummary": {...},
    "extendedFields": {
      "namespaces": {
        "_user_fields": {
          "alcoholByVolume": 14.5,
          "specialInstructions": "Handle with care - fragile"
        }
      }
    }
  }
}
```

As a result, the custom fields will be available in the `extendedFields` property of the API object. To access, call the relevant method for the target API object to get the values of your custom fields.

For example, when calling [Get Order](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md), the custom fields will appear as:


```json
{
  "id": "order123",
  "buyerInfo": { ... },
  "extendedFields": {
    "namespaces": {
      "_user_fields": {
        "specialInstructions": "Handle with care - fragile",
        "alcoholByVolume": 14.5
      }
    }
  }
}
```

## See also

- [About Data Extension Schemas](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/extend-wix-business-solutions/data-extension-schemas/about-data-extension-schemas.md)
- [Data Extension Schema API](https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction.md)
- [JSON Schema reference](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/extend-wix-business-solutions/data-extension-schemas/the-json-schema.md)