{ "openapi": "3.0.0", "info": { "title": "Custom Fields API", "description": "The Custom Fields API allows you to create, manage, and apply custom fields to contracts and orders in VTEX. Custom fields enable you to capture additional business-specific information at different levels: `item`, `order`, or `address`.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\nThis API is divided into three main sections:\r\n\r\n### Custom field settings\r\nConfigure custom field definitions for contracts, including field name, type, level, and validation rules.\r\n\r\n- `GET` [Get custom field settings](https://developers.vtex.com/docs/api-reference/custom-fields-api#get-/api/dataentities/customFieldSettings/search)\r\n- `POST` [Create custom field setting](https://developers.vtex.com/docs/api-reference/custom-fields-api#post-/api/dataentities/customFieldSettings/documents)\r\n- `PATCH` [Update custom field setting](https://developers.vtex.com/docs/api-reference/custom-fields-api#patch-/api/dataentities/customFieldSettings/documents/-documentId-)\r\n- `DELETE` [Delete custom field setting](https://developers.vtex.com/docs/api-reference/custom-fields-api#delete-/api/dataentities/customFieldSettings/documents/-documentId-)\r\n\r\n### Custom field values\r\nManage the actual values assigned to custom fields for specific contracts.\r\n- `POST` [Create custom field value](https://developers.vtex.com/docs/api-reference/custom-fields-api#post-/api/dataentities/customFieldValues/documents)\r\n- `GET` [Get custom field value](https://developers.vtex.com/docs/api-reference/custom-fields-api#get-/api/dataentities/customFieldValues/documents/-customFieldValueId-)\r\n- `PATCH` [Update custom field value](https://developers.vtex.com/docs/api-reference/custom-fields-api#patch-/api/dataentities/customFieldValues/documents/-customFieldValueId-)\r\n- `DELETE` [Delete custom field value](https://developers.vtex.com/docs/api-reference/custom-fields-api#delete-/api/dataentities/customFieldValues/documents/-customFieldValueId-)\r\n- `GET` [Search custom field values](https://developers.vtex.com/docs/api-reference/custom-fields-api#get-/api/dataentities/customFieldValues/search)", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": ["myvtex"], "default": "myvtex" } } } ], "paths": { "/api/dataentities/customFieldSettings/search": { "get": { "tags": ["Custom field settings"], "summary": "Get custom field settings", "description": "Retrieves the settings of custom fields for a given contract. The response includes field configuration details such as name, type, level, and whether the field is enabled or required.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/Content-Type" }, { "name": "_schema", "in": "query", "description": "Schema version to use for the request. This query string defines which schema version to apply when retrieving data. Learn more about [Master Data schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "v1" } }, { "name": "_fields", "in": "query", "description": "Comma-separated list of field names to be returned in the response. Use `_all` to return all fields, or specify individual fields like `id,contractId,name`. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "_all" } }, { "name": "_where", "in": "query", "description": "Filter expression to search documents using Master Data v2 query syntax. Use `contractId={{contractId}}` to filter custom field settings by contract. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "contractId={{contractId}}" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of custom fields settings objects.", "items": { "type": "object", "description": "Custom fields settings object.", "properties": { "id": { "type": "string", "description": "Unique identifier of the custom field instance." }, "dataEntityId": { "type": "string", "description": "Identifier of the data entity to which the field belongs." }, "accountId": { "type": "string", "description": "Identifier of the account associated with the field." }, "accountName": { "type": "string", "description": "Name of the account associated with the field." }, "followers": { "type": "array", "description": "List of users following this field (usually empty).", "items": { "type": "string", "description": "User identifier." } }, "schemas": { "type": "array", "description": "List of applicable schema versions for this field.", "items": { "type": "string", "description": "Schema version." } }, "contractId": { "type": "string", "description": "Identifier of the contract associated with the field." }, "name": { "type": "string", "description": "Name of the custom fields." }, "enabled": { "type": "boolean", "description": "Indicates whether the field is enabled." }, "required": { "type": "boolean", "description": "Indicates whether the field is mandatory." }, "level": { "type": "string", "description": "Level at which the field is applied. Possible values: `item`, `order`, `address`." }, "type": { "type": "string", "description": "Type of the field. Possible values: `text`, `number`, `option`." }, "additionalData": { "type": "string", "description": "Additional field for extra information.", "nullable": true }, "createdBy": { "type": "string", "description": "ID of the user who created the field." }, "createdBy_USER": { "type": "object", "description": "Details of the user who created the field.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the user." }, "Login": { "type": "string", "description": "Login email of the user." }, "Name": { "type": "string", "description": "Name of the user.", "nullable": true } } }, "createdIn": { "type": "string", "format": "date-time", "description": "Date and time when the field was created (ISO 8601 format)." }, "lastInteractionBy": { "type": "string", "description": "ID of the user who last interacted with the field." }, "lastInteractionBy_USER": { "type": "object", "description": "Details of the user who last interacted with the field.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the user." }, "Login": { "type": "string", "description": "Login email of the user." }, "Name": { "type": "string", "description": "Name of the user.", "nullable": true } } }, "lastInteractionIn": { "type": "string", "format": "date-time", "description": "Date and time of the last interaction with the field (ISO 8601 format)." }, "tags": { "type": "array", "description": "List of tags associated with the field (usually empty).", "items": { "type": "string", "description": "Tag value." } }, "dataInstanceId": { "type": "string", "description": "Identifier of the data instance (usually equal to `id`)." } } } }, "example": [ { "id": "34575ee8-80c1-458d-b75a-7492b36513e3", "dataEntityId": "customFieldSettings", "accountId": "6e41729c-a5ca-4f37-a46f-62315ef3a56a", "accountName": "connections", "followers": [], "schemas": ["v1"], "contractId": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1", "name": "PO Number", "enabled": true, "required": false, "level": "item", "type": "option", "additionalData": "teste", "createdBy": "6ce199d2-8a85-4e83-831c-389dcb64c0c1", "createdBy_USER": { "Id": "6ce199d2-8a85-4e83-831c-389dcb64c0c1", "Login": "user@vtex.com", "Name": null }, "createdIn": "2025-09-24T12:32:08.6879184Z", "lastInteractionBy": "6ce199d2-8a85-4e83-831c-389dcb64c0c1", "lastInteractionBy_USER": { "Id": "6ce199d2-8a85-4e83-831c-389dcb64c0c1", "Login": "user@vtex.com", "Name": null }, "lastInteractionIn": "2025-09-24T12:32:08.6879204Z", "tags": [], "dataInstanceId": "34575ee8-80c1-458d-b75a-7492b36513e3" } ] } } } } } }, "/api/dataentities/customFieldSettings/documents": { "post": { "tags": ["Custom field settings"], "summary": "Create custom field settings", "description": "Creates and configures a custom field for a specific contract. You can define the field name, type, level, and whether it is enabled or required.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Custom fields settings configuration object.", "required": [ "contractId", "name", "enabled", "required", "level", "type" ], "properties": { "contractId": { "type": "string", "description": "The contract ID to which the custom field belongs.", "example": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1" }, "name": { "type": "string", "description": "The custom field name.", "example": "PO Number" }, "enabled": { "type": "boolean", "description": "Indicates whether the custom field is enabled (`true`) or not (`false`).", "example": true }, "required": { "type": "boolean", "description": "Indicates whether the custom field is mandatory (`true`) or optional (`false`).", "example": false }, "level": { "type": "string", "description": "The level at which the custom field applies. Possible values: `item`, `order`, `address`.", "enum": ["item", "order", "address"], "example": "item" }, "type": { "type": "string", "description": "The value type of the custom field. Possible values: `text`, `number`, `option`.", "enum": ["text", "number", "option"], "example": "option" }, "additionalData": { "type": "string", "description": "Other data associated with the custom field.", "example": "Additional validation rules" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response object containing the created custom field information.", "properties": { "Id": { "type": "string", "description": "Auto-generated GUID for the custom field, prefixed with the data entity name." }, "Href": { "type": "string", "description": "Direct URL to the created custom field document." }, "DocumentId": { "type": "string", "description": "Identifier of the custom field document (GUID without prefix)." } } }, "example": { "Id": "customFieldSettings-89f1da93-6917-4cbf-894e-1f1399682826c", "Href": "https://accountName.myvtex.com.br/api/dataentities/customFieldSettings/documents/89f1da93-6917-4cbf-894e-1f1399682826c?_schema=v1", "DocumentId": "89f1da93-6917-4cbf-894e-1f1399682826c" } } } } } } }, "/api/dataentities/customFieldSettings/documents/{documentId}": { "patch": { "tags": ["Custom field settings"], "summary": "Update custom field settings", "description": "Updates the configuration of an existing custom field. This endpoint allows you to enable or disable a custom field, mark it as required, define the level (`item`, `order`, or `address`), and set its type (`text`, `number`, or `option`). You can also provide optional `additionalData` for custom validations, allowed values, or integration rules. Each request handles a single custom field configuration. The field is identified by its auto-generated ID.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/documentId" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Custom field settings update object.", "required": [ "contractId", "name", "enabled", "required", "level", "type" ], "properties": { "contractId": { "type": "string", "description": "The contract ID to which the custom field belongs.", "example": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1" }, "name": { "type": "string", "description": "The custom field name.", "example": "PO Number" }, "enabled": { "type": "boolean", "description": "Indicates whether the custom field is enabled (`true`) or not (`false`).", "example": true }, "required": { "type": "boolean", "description": "Indicates whether the custom field is mandatory (`true`) or optional (`false`).", "example": false }, "level": { "type": "string", "description": "The level at which the custom field applies. Possible values: `item`, `order`, `address`.", "enum": ["item", "order", "address"], "example": "item" }, "type": { "type": "string", "description": "The value type of the custom field. Possible values: `text`, `number`, `option`.", "enum": ["text", "number", "option"], "example": "option" }, "additionalData": { "type": "string", "description": "Extra data associated with the custom field.", "example": "Updated validation rules" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Empty response body on successful update." }, "example": {} } } } } }, "delete": { "tags": ["Custom field settings"], "summary": "Delete custom field setting", "description": "Deletes the custom field settings document associated with the given document ID.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "name": "documentId", "in": "path", "description": "Unique identifier of the custom field settings document to delete.", "required": true, "schema": { "type": "string", "example": "89f1da93-6917-4cbf-894e-1f1399682826c" } }, { "name": "_schema", "in": "query", "description": "Schema version to use for the request.", "required": true, "schema": { "type": "string", "example": "v1" } } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/customFieldValues/documents": { "post": { "tags": ["Custom field values"], "summary": "Create custom field value", "description": "Creates a value for an existing custom field for a given contract. If you are creating a value for a custom field configured with level `address`, you must send a valid address ID in the field `auxId`.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Custom field value creation object.", "required": [ "contractId", "customFieldId", "value" ], "properties": { "contractId": { "type": "string", "description": "The ID of the contract associated with the field.", "example": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1" }, "customFieldId": { "type": "string", "description": "The ID of the custom field, which is automatically generated when creating custom field settings.", "example": "a7f2b3d4-5c6e-7f89-0123-456789abcdef" }, "auxId": { "type": "string", "description": "Optional auxiliary ID (e.g., address ID) used for fields with level `address`.", "nullable": true, "example": null }, "value": { "type": "string", "description": "The value to be stored for the custom field.", "example": "CC3" }, "description": { "type": "string", "description": "Details what the value represents.", "example": "Cost Center 3" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response object containing the created custom field value information.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the created value, prefixed with the data entity name." }, "Href": { "type": "string", "description": "Direct URL to access the value document created." }, "DocumentId": { "type": "string", "description": "The value ID without the data entity prefix." } } }, "example": { "Id": "customFieldValues-07d12677-08d8-11f0-b37f-e1ae31409099", "Href": "https://accountName.myvtex.com.br/api/dataentities/customFieldValues/documents/07d12677-08d8-11f0-b37f-e1ae31409099", "DocumentId": "07d12677-08d8-11f0-b37f-e1ae31409099" } } } } } } }, "/api/dataentities/customFieldValues/documents/{customFieldValueId}": { "get": { "tags": ["Custom field values"], "summary": "Get custom field value", "description": "Retrieves a specific custom field value document by its ID.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/customFieldValueId" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_schema" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Custom field value document object.", "properties": { "id": { "type": "string", "description": "The ID of the custom field value document." }, "dataEntityId": { "type": "string", "description": "The ID of the data entity (`customFieldValues`)." }, "accountId": { "type": "string", "description": "Unique identifier of the VTEX account." }, "accountName": { "type": "string", "description": "Name of the VTEX account." }, "followers": { "type": "array", "description": "Array of followers for this document.", "items": { "type": "string", "description": "Follower identifier." } }, "schemas": { "type": "array", "description": "Array of schemas associated with this document.", "items": { "type": "string", "description": "Schema version." } }, "customFieldId": { "type": "string", "description": "The ID of the custom field (from `customFieldSettings`)." }, "contractId": { "type": "string", "description": "The ID of the contract to which this value belongs." }, "auxId": { "type": "string", "description": "Optional auxiliary ID (e.g., address ID) used for fields with level `address`.", "nullable": true }, "value": { "type": "string", "description": "The actual value of the custom field." }, "description": { "type": "string", "description": "Optional description explaining what the value represents.", "nullable": true }, "createdBy": { "type": "string", "description": "ID of the user who created the document." }, "createdBy_USER": { "type": "object", "description": "Metadata about the creator.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the user." }, "Login": { "type": "string", "description": "Login email of the user." }, "Name": { "type": "string", "description": "Name of the user.", "nullable": true } } }, "createdIn": { "type": "string", "format": "date-time", "description": "Timestamp when the document was created." }, "lastInteractionBy": { "type": "string", "description": "ID of the last user who modified the document." }, "lastInteractionBy_USER": { "type": "object", "description": "Metadata about the last interacting user.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the user." }, "Login": { "type": "string", "description": "Login email of the user." }, "Name": { "type": "string", "description": "Name of the user.", "nullable": true } } }, "lastInteractionIn": { "type": "string", "format": "date-time", "description": "Timestamp of the last modification." }, "tags": { "type": "array", "description": "Tags associated with the document.", "items": { "type": "string", "description": "Tag value." } }, "dataInstanceId": { "type": "string", "description": "Unique identifier of the data instance." } } }, "example": { "id": "a50012d0-c01f-465d-b4bc-e33b38d7437a", "dataEntityId": "customFieldValues", "accountId": "5f1fe23b-9fd1-417d-a4aa-14df38e7746e", "accountName": "store", "followers": [], "schemas": [], "customFieldId": "a7f2b3d4-5c6e-7f89-0123-456789abcdef", "contractId": "2da4e9ab-050b-11f0-b37f-f4b136dbcce1", "auxId": null, "value": "CC3", "description": "Some details about the value", "createdBy": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "createdBy_USER": { "Id": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "Login": "user@vtex.com", "Name": null }, "createdIn": "2025-04-11T18:24:14.8763277Z", "lastInteractionBy": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "lastInteractionBy_USER": { "Id": "c83ea7ed-f875-4a10-b0a0-98d96aedab06", "Login": "user@vtex.com", "Name": null }, "lastInteractionIn": "2025-04-11T18:24:14.8763277Z", "tags": [], "dataInstanceId": "a50012d0-c01f-465d-b4bc-e33b38d7437a" } } } } } }, "patch": { "tags": ["Custom field values"], "summary": "Update custom field value", "description": "Updates the value of a specific custom field for a given contract.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/customFieldValueId" }, { "$ref": "#/components/parameters/_schema" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "Custom field value update object.", "required": [ "contractId", "customFieldId", "value" ], "properties": { "contractId": { "type": "string", "description": "The ID of the contract to which the custom field belongs.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "customFieldId": { "type": "string", "description": "The ID of the custom field (from the customFieldSettings document).", "example": "a7f2b3d4-5c6e-7f89-0123-456789abcdef" }, "auxId": { "type": "string", "description": "Optional auxiliary ID (e.g., address ID) used for fields with level `address`.", "nullable": true, "example": null }, "value": { "type": "string", "description": "The new value for the custom field (max length 22 characters).", "example": "CC3" }, "description": { "type": "string", "description": "Optional description explaining what the value represents.", "example": "Details about the value" } } } } } }, "responses": { "204": { "description": "No Content" } } }, "delete": { "tags": ["Custom field values"], "summary": "Delete custom field value", "description": "Deletes a specific custom field value document.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/customFieldValueId" }, { "$ref": "#/components/parameters/_fields" }, { "$ref": "#/components/parameters/_schema" } ], "responses": { "204": { "description": "No Content" } } } }, "/api/dataentities/customFieldValues/search": { "get": { "tags": ["Custom field values"], "summary": "Search custom field values", "description": "Retrieves custom field values filtered by contract ID, custom field ID, and optionally by specific value. Results can be sorted by value.\r\n\r\nYou can use the `_where` query parameter to filter results:\r\n- To get all values: `_where=contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\"`\r\n- To get a specific value: `_where=contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\" AND value=\"{{value}}\"`\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\r\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "name": "_schema", "in": "query", "description": "Schema version to use for the request. This query string defines which schema version to apply when retrieving data. Learn more about [Master Data schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "v1" } }, { "name": "_fields", "in": "query", "description": "Comma-separated list of field names to be returned in the response. Use `_all` to return all fields, or specify individual fields like `id,contractId,value`. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "_all" } }, { "name": "_where", "in": "query", "description": "Filter expression to search documents using Master Data v2 query syntax. You can combine multiple conditions using `AND`. Examples:\n- Get all values for a contract: `contractId={{contractId}}`\n- Filter by contract and custom field: `contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\"`\n- Filter by specific value: `contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\" AND value=\"{{value}}\"`\n\nLearn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\"" } }, { "name": "_sort", "in": "query", "description": "Defines the field and order for sorting results. Use the pattern `{fieldName} {ASC|DESC}`. For example, `value ASC` sorts results by the `value` field in ascending order. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "value ASC" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of custom field value objects matching the search criteria.", "items": { "type": "object", "description": "Custom field value search result object.", "properties": { "id": { "type": "string", "description": "The unique ID of the custom field value document." }, "contractId": { "type": "string", "description": "The ID of the contract associated with the custom field." }, "customFieldId": { "type": "string", "description": "The ID of the custom field (from `customFieldSettings`)." }, "auxId": { "type": "string", "description": "Optional auxiliary ID (e.g., address ID) used for fields with level `address`.", "nullable": true }, "value": { "type": "string", "description": "The value stored in the custom field." }, "description": { "type": "string", "description": "Optional text describing what the value represents.", "nullable": true } } } }, "examples": { "allValues": { "summary": "Search all values for a custom field", "description": "Returns all values for a specific custom field, sorted by value. Use `_where=contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\"` with `_sort=value ASC`.", "value": [ { "id": "e5130781-32ed-11f0-b37f-942217c27f9b", "contractId": "1124b2d8-32eb-11f0-b37f-e2557e6b18d5", "customFieldId": "a7f2b3d4-5c6e-7f89-0123-456789abcdef", "auxId": null, "value": "CC1", "description": "Cost Center 1" }, { "id": "f6240892-43fe-22f1-c48a-053328d28f0c", "contractId": "1124b2d8-32eb-11f0-b37f-e2557e6b18d5", "customFieldId": "a7f2b3d4-5c6e-7f89-0123-456789abcdef", "auxId": null, "value": "CC2", "description": "Cost Center 2" }, { "id": "a7351903-54ff-33f2-d59b-164439e39g1d", "contractId": "1124b2d8-32eb-11f0-b37f-e2557e6b18d5", "customFieldId": "a7f2b3d4-5c6e-7f89-0123-456789abcdef", "auxId": null, "value": "CC3", "description": "Cost Center 3" } ] }, "specificValue": { "summary": "Get a specific value", "description": "Returns a specific custom field value. Use `_where=contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\" AND value=\"{{value}}\"`.", "value": [ { "id": "e5130781-32ed-11f0-b37f-942217c27f9b", "contractId": "1124b2d8-32eb-11f0-b37f-e2557e6b18d5", "customFieldId": "a7f2b3d4-5c6e-7f89-0123-456789abcdef", "auxId": null, "value": "CC3", "description": "Cost Center 3" } ] } } } } } } } } }, "security": [ { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } }, "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "_schema": { "name": "_schema", "in": "query", "description": "Schema version to use for the request. This query string parameter defines which schema version to apply when retrieving or manipulating data. Learn more about [Master Data schemas](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle).", "required": true, "style": "form", "schema": { "type": "string", "example": "v1" } }, "_sort": { "name": "_sort", "in": "query", "description": "Defines the field and order for sorting results. This query string parameter follows the pattern `{fieldName} {ASC|DESC}`. For example, `value ASC` sorts results by the `value` field in ascending order. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": false, "style": "form", "schema": { "type": "string", "example": "value ASC" } }, "_fields": { "name": "_fields", "in": "query", "description": "Comma-separated list of field names to be returned in the response. This query string parameter allows you to specify which fields to include. Use `_all` to return all fields, or specify individual fields like `id,contractId,value`. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "schema": { "type": "string", "example": "_all" } }, "_where": { "name": "_where", "in": "query", "description": "Filter expression to search documents. This query string parameter uses Master Data v2 query syntax. You can combine multiple conditions using `AND`. For example: `contractId={{contractId}}` or `contractId={{contractId}} AND customFieldId=\"{{customFieldId}}\"`. Learn more about [searching documents in Master Data v2](https://developers.vtex.com/docs/guides/search-documents-in-master-data).", "required": true, "schema": { "type": "string", "example": "contractId={{contractId}}" } }, "documentId": { "name": "documentId", "in": "path", "description": "Unique identifier of the custom field settings document to update.", "required": true, "schema": { "type": "string", "example": "89f1da93-6917-4cbf-894e-1f1399682826c" } }, "customFieldValueId": { "name": "customFieldValueId", "in": "path", "description": "Unique identifier of the custom field value document.", "required": true, "schema": { "type": "string", "example": "a50012d0-c01f-465d-b4bc-e33b38d7437a" } } } }, "tags": [ { "name": "Custom field settings" }, { "name": "Custom field values" } ] }