{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Default Values API",
"description": "Default values are purchase details, such as addresses and credit cards, that you can configure for an organizational unit to be automatically pre-filled at checkout.\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## Authentication\r\n\r\nYou can authenticate requests to these APIs by sending a VTEX user token in a header named `VtexIdclientAutCookie`. Learn more in [API authentication using user tokens](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-user-tokens).\r\n\r\n## Common parameters in the documentation\r\n\r\n| Parameter name | Description |\r\n| - | - |\r\n| `{{accountName}}`| Name of the VTEX account. Used as part of the URL. |\r\n| `{{environment}}`| Environment to use. The default value is `vtexcommercestable`. Used in the URL. |\r\n| `{{X-VTEX-API-AppKey}}` | Unique identifier of the [API key](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-api-keys). |\r\n| `{{X-VTEX-API-AppToken}}` | Secret token of the [API key](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-api-keys). |"
},
"servers": [
{
"url": "https://{accountName}.{environment}.com.br",
"description": "VTEX server URL.",
"variables": {
"accountName": {
"default": "apiexamples",
"description": "Name of the VTEX account. Used as part of the URL."
},
"environment": {
"enum": [
"vtexcommercestable"
],
"default": "vtexcommercestable",
"description": "Environment to use. Used as part of the URL."
}
}
}
],
"paths": {
"/api/dataentities/defaultValues/documents": {
"post": {
"tags": [
"Default values"
],
"summary": "Create default values",
"description": "Creates a document with a set of default values for a specific organization unit.\n\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\n\n## Permissions\n\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\n\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.\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\n\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"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultValuesRequest"
},
"example": {
"id": "a6d958c2-25ba-4f4d-9a0a-6b56e458426c",
"defaultValues": [
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "4498bd3d-7eaf-11f0-b37f-cc2298c87c12"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "7852aef0-7eb3-11f0-b37f-bfdc92dec2f6"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "9952aef0-7eb3-11f0-b37f-bfdc92dec2e6"
},
{
"entity": "creditCard",
"entityValueId": "EDE0B17747B24EFC9650B6C6B3E06C5F"
},
{
"entity": "address/billing",
"entityValueId": "747b9bed-d6f4-4cf5-b9d1-4944f9825470"
},
{
"entity": "address/shipping",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da72d"
},
{
"entity": "customFieldValues/{{customFieldId}}/{{auxId}}",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da723"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response object containing document information.",
"properties": {
"Id": {
"type": "string",
"description": "Unique identifier of the created document."
},
"Href": {
"type": "string",
"description": "Direct link to the created document."
},
"DocumentId": {
"type": "string",
"description": "The document ID."
}
}
},
"example": {
"Id": "c90354e8-08d6-11f0-b37f-daebda928cfa",
"Href": "http://store.myvtex.com/api/dataentities/defaultValues/documents/c90354e8-08d6-11f0-b37f-daebda928cfa",
"DocumentId": "c90354e8-08d6-11f0-b37f-daebda928cfa"
}
}
}
}
}
}
},
"/api/dataentities/defaultValues/documents/{unitId}": {
"get": {
"tags": [
"Default values"
],
"summary": "Get default values",
"description": "Retrieves the default values for a specific organization unit in the VTEX Data Entity by making a GET request.\n\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\n\n## Permissions\n\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Dynamic Storage | Dynamic storage generic resources | **Read only documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\n\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.\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\n\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": "unitId",
"in": "path",
"description": "Unique identifier of the organizational unit.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "_schema",
"in": "query",
"description": "Schema version.",
"required": true,
"schema": {
"type": "string",
"example": "v1"
}
},
{
"name": "_fields",
"in": "query",
"description": "Comma-separated list of fields to return.",
"required": true,
"schema": {
"type": "string",
"example": "id,defaultValues"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Default values for the organizational unit.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the organizational unit."
},
"defaultValues": {
"type": "array",
"description": "An array of default value objects configured for this organizational unit.",
"items": {
"type": "object",
"description": "Default value object defining entity-specific defaults.",
"properties": {
"entity": {
"type": "string",
"description": "The name of the entity. Possible values:
•`address/shipping`
•`address/billing`
•`creditCard`
•`customFieldValues/{{customFieldId}}` for regular custom fields (e.g., PO Number, Cost Center, Release) where `{{customFieldId}}` is the `DocumentId` from Create Custom Field Settings
•`customFieldValues/{{customFieldId}}/{{auxId}}` for Location custom fields where `{{customFieldId}}` is the `DocumentId` returned by the Create Custom Field Settings endpoint (e.g., `89f1da93-6917-4cbf-894e-1f1399682826c`) and `{{auxId}}` is the address ID (only for Location custom fields)."
},
"entityValueId": {
"type": "string",
"description": "The ID of the entity value associated with the entity."
}
}
}
}
}
},
"example": {
"id": "a6d958c2-25ba-4f4d-9a0a-6b56e458426c",
"defaultValues": [
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "4498bd3d-7eaf-11f0-b37f-cc2298c87c12"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "7852aef0-7eb3-11f0-b37f-bfdc92dec2f6"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "9952aef0-7eb3-11f0-b37f-bfdc92dec2e6"
},
{
"entity": "creditCard",
"entityValueId": "EDE0B17747B24EFC9650B6C6B3E06C5F"
},
{
"entity": "address/billing",
"entityValueId": "747b9bed-d6f4-4cf5-b9d1-4944f9825470"
},
{
"entity": "address/shipping",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da72d"
},
{
"entity": "customFieldValues/{{customFieldId}}/{{auxId}}",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da723"
}
]
}
}
}
}
}
},
"patch": {
"tags": [
"Default values"
],
"summary": "Update default values",
"description": "Updates the default values for a specific organization unit.\n\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\n\n## Permissions\n\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Dynamic Storage | Dynamic storage generic resources | **Insert or update document (not remove)** |\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\n\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.\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\n\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"
},
{
"name": "unitId",
"in": "path",
"description": "Unique identifier of the organizational unit.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DefaultValuesRequest"
},
"example": {
"id": "a6d958c2-25ba-4f4d-9a0a-6b56e458426c",
"defaultValues": [
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "4498bd3d-7eaf-11f0-b37f-cc2298c87c12"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "7852aef0-7eb3-11f0-b37f-bfdc92dec2f6"
},
{
"entity": "customFieldValues/{{customFieldId}}",
"entityValueId": "9952aef0-7eb3-11f0-b37f-bfdc92dec2e6"
},
{
"entity": "creditCard",
"entityValueId": "EDE0B17747B24EFC9650B6C6B3E06C5F"
},
{
"entity": "address/billing",
"entityValueId": "747b9bed-d6f4-4cf5-b9d1-4944f9825470"
},
{
"entity": "address/shipping",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da72d"
},
{
"entity": "customFieldValues/{{customFieldId}}/{{auxId}}",
"entityValueId": "45c50497-b67f-40ee-85ec-eddaa23da723"
}
]
}
}
}
},
"responses": {
"204": {
"description": "No Content"
}
}
},
"delete": {
"tags": [
"Default values"
],
"summary": "Delete default values",
"description": "Deletes all default values for a specific organization unit.\n\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\n\n## Permissions\n\nAny user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Dynamic Storage | Dynamic storage generic resources | **Full access to all documents** |\n| Dynamic Storage | Dynamic storage generic resources | **Master Data administrator** |\n\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.\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).\n\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": "unitId",
"in": "path",
"description": "Unique identifier of the organizational unit.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Created"
},
"404": {
"description": "Not Found"
}
}
}
}
},
"security": [
{
"appKey": [],
"appToken": []
},
{
"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"
}
}
},
"schemas": {
"DefaultValuesRequest": {
"type": "object",
"description": "Request body containing default values configuration for an organizational unit.",
"required": [
"id",
"defaultValues"
],
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the organizational unit. This value is used as the default values document ID."
},
"defaultValues": {
"type": "array",
"description": "An array of default value objects.",
"items": {
"type": "object",
"description": "Default value object defining entity-specific defaults.",
"required": [
"entity",
"entityValueId"
],
"properties": {
"entity": {
"type": "string",
"description": "The name of the entity. Possible values:
•`address/shipping`
•`address/billing`
•`creditCard`
•`customFieldValues/{{customFieldId}}` for regular custom fields (e.g., PO Number, Cost Center, Release) where `{{customFieldId}}` is the `DocumentId` from Create Custom Field Settings
•`customFieldValues/{{customFieldId}}/{{auxId}}` for Location custom fields where `{{customFieldId}}` is the `DocumentId` returned by the Create Custom Field Settings endpoint (e.g., `89f1da93-6917-4cbf-894e-1f1399682826c`) and `{{auxId}}` is the address ID (only for Location custom fields)."
},
"entityValueId": {
"type": "string",
"description": "The ID of the entity value associated with the entity."
}
}
}
}
}
}
}
},
"tags": [
{
"name": "Default values"
}
]
}