{ "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" } ] }