{ "openapi": "3.0.0", "info": { "title": "B2B Buyer Data API", "description": "The B2B Buyer Data API allows you to create, retrieve, update, delete, and search buyer documents stored in the `shopper` data entity.\r\n\r\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "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": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/dataentities/shopper/schemas/v1": { "get": { "summary": "Get buyer schema", "description": "This endpoint retrieves a buyer entity [schema](https://developers.vtex.com/docs/guides/master-data-schema-lifecycle) with buyer personal data.\r\n\r\n> ℹ️ The buyer schema supports `additionalProperties: true`, allowing clients to send and persist additional properties beyond the defined schema properties (e.g., `phone2`, `marketingOptIn`, or any business-specific fields).\n\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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerSchemaResponse" } }, "example": [ { "name": "v1", "schema": { "title": "buyer", "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "document": { "type": "string" }, "documentType": { "type": "string" }, "phone": { "type": "string" }, "cards": { "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string" }, "paymentSystem": { "type": "string" }, "paymentSystemName": { "type": "string" }, "cardNumber": { "type": "string", "pattern": "^[\\*]{12}[0-9]{4}$" }, "bin": { "type": "string" }, "expirationDate": { "type": "string" }, "useCvvForAuthorization": { "type": "boolean" }, "cardLabel": { "type": "string" }, "isCardToken": { "type": "boolean" }, "availableAddresses": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } }, "additionalProperties": true, "required": [ "userId", "firstName", "lastName" ], "v-indexed": [ "userId", "firstName", "lastName", "document", "phone" ] } } ] } } } }, "security": [ { "VtexIdclientAutCookie": [] } ] } }, "/api/dataentities/shopper/documents": { "post": { "summary": "Create buyer", "description": "This endpoint creates a buyer entity document.\r\n\r\n> ℹ️ The buyer schema supports additional properties. Clients can include extra properties (e.g., `phone2`, `marketingOptIn`) in the request body, and they will be persisted alongside the standard fields.\n\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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "name": "_schema", "in": "query", "required": true, "schema": { "type": "string", "example": "v1" }, "description": "Schema name. The value must be `v1`." }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerDocumentRequest" }, "example": { "userId": "8abea412-4702-46fb-b835-3edb29d8a261", "email": "john@vtex.com", "firstName": "John", "lastName": "Doe", "document": "514.427.690-33", "documentType": "cpf", "phone": "11917118990", "phone2": "11987654321", "marketingOptIn": true } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBuyerDocumentResponse" }, "example": { "Id": "buyer-a26301e6-1a1e-11f0-b37f-e46d3d0578c6", "Href": "", "DocumentId": "a26301e6-1a1e-11f0-b37f-e46d3d0578c6" } } } } }, "security": [ { "VtexIdclientAutCookie": [] } ] } }, "/api/dataentities/shopper/documents/{buyerId}": { "get": { "summary": "Get buyer by ID", "description": "This endpoint retrieves a buyer entity document by User ID.\r\n\r\n> ℹ️ The response may include additional properties beyond the standard schema if they were previously stored (e.g., `phone2`, `marketingOptIn`).\n\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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "name": "buyerId", "in": "path", "required": true, "schema": { "type": "string", "example": "buyer-8abea412-4702-46fb-b835-3edb29d8a261" }, "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users)." }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerDocument" }, "example": { "userId": "8abea412-4702-46fb-b835-3edb29d8a261", "email": "john@vtex.com", "firstName": "John", "lastName": "Doe", "document": "514.427.690-33", "documentType": "cpf", "phone": "11917118990", "phone2": "11987654321", "marketingOptIn": true, "cards": [ { "cardId": "D05881AD4F424A6C93D8536C9F7F992E", "paymentSystem": "2", "paymentSystemName": "Visa", "cardNumber": "************3232", "bin": "22343333", "availableAddresses": [ "12345" ], "expirationDate": "02/2029", "useCvvForAuthorization": true, "isCardToken": false } ] } } } } }, "security": [ { "VtexIdclientAutCookie": [] } ] }, "patch": { "summary": "Update buyer", "description": "This request allows you to partially update a buyer 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>ℹ️ You can use this request to update documents for any given data entity. Because of this, you are not restricted to using the fields exemplified below in your requests. But you should be aware of the fields allowed or required for each document you wish to update.\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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "name": "buyerId", "in": "path", "required": true, "schema": { "type": "string", "example": "buyer-8abea412-4702-46fb-b835-3edb29d8a261" }, "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyerDocumentRequest" }, "example": { "userId": "8abea412-4702-46fb-b835-3edb29d8a261", "email": "john@vtex.com", "firstName": "John", "lastName": "Doe", "document": "514.427.690-33", "documentType": "cpf", "phone": "11917118990", "phone2": "11987654321", "marketingOptIn": true } } }, "required": true }, "responses": { "204": { "description": "No Content" } }, "security": [ { "VtexIdclientAutCookie": [] } ] }, "delete": { "summary": "Delete buyer", "description": "Deletes a buyer 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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "buyerId", "in": "path", "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users).", "required": true, "style": "simple", "schema": { "type": "string", "example": "buyer-8abea412-4702-46fb-b835-3edb29d8a261" } } ], "responses": { "202": { "description": "Accepted" }, "204": { "description": "No Content" } }, "security": [ { "VtexIdclientAutCookie": [] } ] } }, "/api/dataentities/shopper/search": { "get": { "summary": "Search buyers", "description": "This endpoint searches a buyer entity document by User ID.\r\n\r\n> ℹ️ The response may include additional properties beyond the standard schema if they were previously stored (e.g., `phone2`, `marketingOptIn`).\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 | **Master Data administrator** |\r\n| Master Data | Application | **List Applications** |\r\n| Master Data | Application | **View logs** |\r\n| Master Data | Form | **List Forms** |\r\n| Master Data | Comment | **List Comments** |\r\n| Master Data | Customized Search | **List Custom Search** |\r\n| Master Data | Generic resources | **Read-only form access** |\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>\u2757 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.", "tags": [ "Buyer data" ], "parameters": [ { "name": "_where", "in": "query", "required": false, "schema": { "type": "string", "example": "userId=8abea412-4702-46fb-b835-3edb29d8a261" }, "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users). Use the `userId={{userId}}` value." }, { "name": "_schema", "in": "query", "required": true, "schema": { "type": "string", "default": "v1", "enum": [ "v1" ] }, "description": "Schema name. The value must be `v1`." }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.vtex.create-budget+json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BuyerDocument" } }, "example": [ { "userId": "8abea412-4702-46fb-b835-3edb29d8a261", "email": "john@vtex.com", "firstName": "John", "lastName": "Doe", "document": "514.427.690-33", "documentType": "cpf", "phone": "11917118990", "phone2": "11987654321", "marketingOptIn": true, "cards": [ { "cardId": "D05881AD4F424A6C93D8536C9F7F992E", "paymentSystem": "2", "paymentSystemName": "Visa", "cardNumber": "************3232", "bin": "22343333", "availableAddresses": [ "12345" ], "expirationDate": "02/2029", "useCvvForAuthorization": true, "isCardToken": false } ] } ] } } } }, "security": [ { "VtexIdclientAutCookie": [] } ] } } }, "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." } }, "schemas": { "BuyerSchemaResponse": { "type": "object", "description": "Schema response containing the buyer entity schema definition with properties, required fields, and indexed fields configuration.", "properties": { "name": { "type": "string", "description": "Schema name." }, "schema": { "type": "object", "description": "Buyer schema definition containing properties, required fields, and indexed fields.", "properties": { "title": { "type": "string", "description": "Schema title." }, "type": { "type": "string", "description": "Schema type." }, "properties": { "type": "object", "description": "Schema properties definition.", "properties": { "userId": { "required": [ "type", "format" ], "type": "object", "description": "Buyer identifier definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the buyer ID field." }, "format": { "type": "string", "description": "Indicates the expected format for the buyer ID field." } } }, "email": { "type": "object", "description": "Email field definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the email field." } } }, "firstName": { "type": "object", "description": "Buyer's first name definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the first name field." } } }, "lastName": { "type": "object", "description": "Buyer's last name definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the last name field." } } }, "document": { "type": "object", "description": "Buyer's document number (e.g., CPF) definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the document number field." } } }, "documentType": { "type": "object", "description": "Type of document (e.g., `cpf`) definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the document type field." } } }, "phone": { "type": "object", "description": "Buyer's phone number definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the phone number field." } } }, "cards": { "type": "object", "description": "Saved credit cards information. This field is used by the checkout module.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the cards field." }, "items": { "type": "object", "description": "Credit card information.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the card ID field." }, "properties": { "type": "object", "description": "Credit card information.", "properties": { "cardId": { "type": "object", "description": "Unique identifier of the saved card definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the card ID field." } } }, "paymentSystem": { "type": "object", "description": "Payment system definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the payment system field." } } }, "paymentSystemName": { "type": "object", "description": "Payment system name definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the payment system name field." } } }, "cardNumber": { "type": "object", "description": "Card number definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the card number field." }, "pattern": { "type": "string", "description": "Indicates the expected pattern for the card number field.", "pattern": "^[\\*]{12}[0-9]{4}$" } } }, "bin": { "type": "object", "description": "Bin definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the bin field." } } }, "expirationDate": { "type": "object", "description": "Expiration date definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the expiration date field." } } }, "useCvvForAuthorization": { "type": "object", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the use CVV for authorization field." } }, "description": "Indicates the expected data type for the use CVV for authorization field." }, "cardLabel": { "type": "object", "description": "Card label definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the card label field." } } }, "isCardToken": { "type": "object", "description": "`isCardToken` definition.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the `isCardToken` field." } } }, "availableAddresses": { "type": "object", "description": "Indicates the expected data type for the available addresses field.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the available addresses field." }, "items": { "type": "object", "description": "Address identifier.", "properties": { "type": { "type": "string", "description": "Indicates the expected data type for the address identifier field." } } } } } } }, "additionalProperties": { "type": "boolean", "description": "When `true`, allows clients to send and persist custom fields beyond the defined schema. This enables storing extra fields like `phone2`, `marketingOptIn`, or any buyer-specific data." } } } } } } }, "additionalProperties": { "type": "boolean", "description": "When `true`, allows clients to send and persist custom fields beyond the defined schema. This enables storing extra fields like `phone2`, `marketingOptIn`, or any buyer-specific data." }, "requiredField": { "title": "required", "type": "array", "description": "List of required properties.", "items": { "type": "string", "description": "Name of a required property field." } }, "v-indexed": { "type": "array", "description": "List of indexed properties.", "items": { "type": "string", "description": "Name of an indexed property field." } } } } }, "required": [ "name", "schema" ] }, "BuyerDocumentRequest": { "type": "object", "description": "Buyer document creation request. Supports additional properties beyond the defined schema.", "required": [ "userId", "firstName", "lastName", "document", "documentType" ], "properties": { "userId": { "type": "string", "format": "uuid", "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users)." }, "email": { "type": "string", "description": "Buyer's email." }, "firstName": { "type": "string", "description": "Buyer's first name." }, "lastName": { "type": "string", "description": "Buyer's last name." }, "document": { "type": "string", "description": "Buyer's document number (e.g., CPF number)." }, "documentType": { "type": "string", "description": "Type of the document provided (e.g., `cpf`)." }, "phone": { "type": "string", "description": "Buyer's phone number." } } }, "BuyerDocument": { "type": "object", "description": "Buyer document. May include additional properties beyond the standard schema if they were previously stored.", "properties": { "userId": { "type": "string", "format": "uuid", "description": "Unique identifier for the buyer created by [VTEX ID API](https://developers.vtex.com/docs/api-reference/vtex-id-api#post-/api/authenticator/v1/storefront/users)." }, "email": { "type": "string", "description": "Buyer's email." }, "firstName": { "type": "string", "description": "Buyer's first name." }, "lastName": { "type": "string", "description": "Buyer's last name." }, "document": { "type": "string", "description": "Buyer's document number (e.g., CPF number)." }, "documentType": { "type": "string", "description": "Type of the document provided (e.g., `cpf`)." }, "phone": { "type": "string", "description": "Buyer's phone number." }, "cards": { "type": "array", "description": "List of cards associated with the buyer. This field is used by the checkout module.", "items": { "type": "object", "description": "Credit card information.", "properties": { "cardId": { "type": "string", "description": "Unique identifier of the saved card." }, "paymentSystem": { "type": "string", "description": "Code representing the payment system (e.g., `2` for Visa)." }, "paymentSystemName": { "type": "string", "description": "Name of the payment system (e.g., `Visa`)." }, "cardNumber": { "type": "string", "description": "Masked credit card number." }, "bin": { "type": "string", "description": "Bank Identification Number - the first digits of the card." }, "expirationDate": { "type": "string", "description": "Expiry date of the card in `MM/YYYY` format." }, "useCvvForAuthorization": { "type": "boolean", "description": "Indicates if CVV is required for authorization." }, "cardLabel": { "type": "string", "description": "Label or nickname for the card." }, "isCardToken": { "type": "boolean", "description": "Indicates whether the card data is tokenized." }, "availableAddresses": { "type": "array", "description": "Array of address IDs the card is associated with.", "items": { "type": "string", "description": "Address identifier." } } } } } } }, "CreateBuyerDocumentResponse": { "type": "object", "description": "Response object returned when a document is successfully created.", "properties": { "Id": { "type": "string", "description": "Unique identifier of the document, prefixed with the entity name (`buyer`)." }, "Href": { "type": "string", "description": "URL to access the document. May be empty if not applicable." }, "DocumentId": { "type": "string", "description": "Same as `Id`, used internally to identify the document." } }, "required": [ "Id", "DocumentId" ] }, "BuyerDocumentResponse": { "required": [ "Id", "Href" ], "type": "object", "description": "Response body object.", "properties": { "Id": { "type": "string", "description": "ID of the document that was created or updated." }, "Href": { "type": "string", "description": "Document reference URL." } } } }, "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" } } } }, "tags": [ { "name": "Buyer data" } ] }