The VTEX Buyer Organization API enables B2B commerce capabilities by allowing businesses to manage buyer organizations, their members, roles, and cost centers. It supports bulk import of buyer organizations and manages permissions for B2B purchasing workflows.
openapi: 3.0.0
info:
title: VTex Buyer Organizations
description: "The Buyer Organizations API facilitates the bulk import of [Buyer Organizations](https://developers.vtex.com/docs/apps/vtex.b2b-organizations), [Cost Centers](https://developers.vtex.com/docs/guides/vtex-b2b-organizations#cost-centers), and [Members](https://developers.vtex.com/docs/guides/vtex-b2b-organizations#users). By allowing spreadsheet import, this API simplifies the management of buyer organizations and allows easy updating and maintenance of information in B2B stores.\r\n\r\n>ℹ ️Only `.xlsx` files under 50MB in size can be imported. You can [download the template file](https://io.vtex.com.br/b2b-bulk-import/b2b-bulk-import-template.xlsx) as an example. For more information on the file structure and how to fill it out, access the [Bulk Import Buyer Organizations Spreadsheet](https://developers.vtex.com/docs/guides/bulk-import-buyer-organizations-spreadsheet) guide.\r\n\r\n## Index\r\n\r\n- `POST` [Upload file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs)\r\n- `GET` [Check progress](https://developers.vtex.com/docs/api-reference/buyer-organizations#get-/api/b2b/import/buyer-orgs/-importId-)\r\n- `POST` [Start import](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/-importId-)\r\n- `POST` [Validate file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/validate/-importId-)\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. Used as part of the URL. |\r\n| `{{X-VTEX-API-AppKey}}` | Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). |\r\n| `{{X-VTEX-API-AppToken}}` | Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys). |"
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/b2b/import/buyer-orgs:
post:
tags:
- Bulk Import
summary: VTex Upload file
description: "Uploads a file for bulk import of Buyer Organizations, Cost Centers and Members. The uploaded file should be in `XLSX` format and have less than 50MB. For more information on the file structure and how to fill it out, access the [Bulk Import Spreadsheet](https://developers.vtex.com/docs/guides/bulk-import-buyer-organizations-spreadsheet) guide.\r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| B2B | B2B General | **B2BBulkImport** |\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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: UploadFile
parameters:
- $ref: '#/components/parameters/Content-Type-Multipart'
- $ref: '#/components/parameters/an'
requestBody:
content:
multipart/form-data:
encoding: {}
schema:
required:
- file
type: object
properties:
file:
type: string
format: binary
description: File to be uploaded.
example: file.xlsx
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/file-data'
example:
accountName: accountName
importId: 3c3cba0a-8355-4812-ad4d-f4c0b32e2613
importState: Uploaded
percentage: '0'
lastUpdateDate: '2023-10-05T16:40:11+00:00'
fileName: file.xlsx
/api/b2b/import/buyer-orgs/{importId}:
get:
tags:
- Bulk Import
summary: VTex Check progress
description: "Checks the progress of a started file validation or import process. After initiating validation using [Validate file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/validate/-importId-) or import using [Start import](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/-importId-), you can track progress by sending a request to this endpoint. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| B2B | B2B General | **B2BBulkImport** |\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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
operationId: CheckProgress
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/an'
- $ref: '#/components/parameters/importId'
responses:
'200':
description: Response containing the details of the file validation or import.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/file-data'
- $ref: '#/components/schemas/importResult'
- $ref: '#/components/schemas/validationResult'
examples:
ValidationDetails:
value:
accountName: accountName
importId: 3c3cba0a-8355-4812-ad4d-f4c0b32e2613
importState: InValidation
percentage: '0'
lastUpdateDate: '2023-10-05T16:40:11+00:00'
fileName: file.xlsx
ImportDetails:
value:
accountName: accountName
importId: 3c3cba0a-8355-4812-ad4d-f4c0b32e2613
importState: Completed
percentage: '100'
lastUpdateDate: '2023-10-05T16:41:11+00:00'
fileName: file.xlsx
ValidationErrorsDetails:
value:
accountName: accountName
importId: 71411025-c7d9-4c9d-92b5-9bc70a1acdb7
importState: ValidationFailed
percentage: '0'
lastUpdateDate: '2024-02-21T17:56:57+00:00'
fileName: file.xlsx
validationResult:
isValid: false
validationResult:
- name: Organizations
validRows: 0
invalidRows: 1
- name: Cost Centers
validRows: 0
invalidRows: 0
- name: Members
validRows: 0
invalidRows: 0
ImportErrorsDetails:
value:
accountName: accountName
importId: d51b1b09-b4f3-44a3-ad70-53b9c8fe35f4
importState: CompletedWithError
percentage: '100'
lastUpdateDate: '2024-02-26T14:47:10+00:00'
fileName: test-26-fev-bulk-import-error.xlsx
importResult:
imports:
- name: Organizations
importedRows: 2
rowsWithError: 1
reportDownloadLink: https://host.com/files/accountName/d51b1b09-b4f3-44a3-ad70-53b9c8fe35f4/file-error_Report.xlsx
importedAt: '2024-02-26T14:47:05+00:00'
importedUserEmail: [email protected]
importedUserName: user
post:
tags:
- Bulk Import
summary: VTex Start import
description: "Once the file is successfully uploaded and validated, you can call this endpoint to start the import. Provide the `importId` returned by the [Validate file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs/validate/-importId-) or [Upload file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs) endpoints. \r\n\r\n## Permissions\r\n\r\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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| B2B | B2B General | **B2BBulkImport** |\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 app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations."
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/an'
- $ref: '#/components/parameters/importId'
responses:
'204':
description: No Content
/api/b2b/import/buyer-orgs/validate/{importId}:
post:
tags:
- Bulk Import
summary: VTex Validate file
description: |-
Starts the bulk import file content validation. Once the the file is successfully uploaded, you can start the validation using the `importId` returned by the [Upload file](https://developers.vtex.com/docs/api-reference/buyer-organizations#post-/api/b2b/import/buyer-orgs) endpoint.
## Permissions
Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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:
| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| B2B | B2B General | **B2BBulkImport** |
There 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).
>❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.
operationId: ValidateFile
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/an'
- $ref: '#/components/parameters/importId'
responses:
'204':
description: No Content
components:
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
Content-Type-Multipart:
name: Content-Type
in: header
description: Type of the content being sent.
required: true
style: simple
schema:
type: string
example: multipart/form-data
an:
name: an
in: query
description: Name of your VTEX account.
required: false
style: form
schema:
type: string
example: exampleAccount
accountName:
name: accountName
in: path
required: true
description: Name of your VTEX account.
schema:
type: string
example: apiexamples
environment:
name: environment
in: path
required: true
description: Environment to be used in the request.
schema:
type: string
default: vtexcommercestable
importId:
name: importId
in: path
required: true
description: Unique identifier of the import.
schema:
type: string
example: 3c3cba0a-8355-4812-ad4d-f4c0b32e2613
schemas:
file-data:
type: object
description: Object containing information about bulk import state.
required:
- accountName
- importId
- importState
- percentage
- lastUpdateDate
- fileName
properties:
accountName:
type: string
description: Name of your VTEX account.
importId:
type: string
description: Unique identifier of the import.
importState:
type: string
description: |-
Current state of the import. The possible values are:
- `Uploaded`: The file was successfully uploaded.
- `InValidation`: File validation is in progress.
- `ReadyToImport`: File validation completed, ready for import.
- `Completed`: File successfully imported.
- `ValidationFailed`: File validation failed.
- `CompletedWithError`: File import failed.
percentage:
type: string
description: Completion percentage of the import.
lastUpdateDate:
type: string
description: Date and time of the last update of the import, in `yyyy-mm-ddTHH:MM:SS+00:00` format.
fileName:
type: string
description: Name of the file being imported.
importResult:
type: object
description: Object containing information about bulk import state.
required:
- accountName
- importId
- importState
- percentage
- lastUpdateDate
- fileName
- importResult
- importedAt
- importedUserEmail
- importedUserName
properties:
accountName:
type: string
description: Name of your VTEX account.
importId:
type: string
description: Unique identifier of the import.
importState:
type: string
description: |-
Current state of the import. The possible values are:
- `Uploaded`: The file was successfully uploaded.
- `InValidation`: File validation is in progress.
- `ReadyToImport`: File validation completed, ready for import.
- `Completed`: File successfully imported.
- `ValidationFailed`: File validation failed.
- `CompletedWithError`: File import failed.
percentage:
type: string
description: Completion percentage of the import.
lastUpdateDate:
type: string
description: Date and time of the last update of the import, in `yyyy-mm-ddTHH:MM:SS+00:00` format.
fileName:
type: string
description: Name of the file being imported.
importedAt:
type: string
description: Date and time when the import was completed, in `yyyy-mm-ddTHH:MM:SS+00:00` format.
importedUserEmail:
type: string
description: Email address of the user who performed the import.
importedUserName:
type: string
description: Name of the user who performed the import.
importResult:
type: object
description: Information about the outcome of the bulk import operation.
properties:
reportDownloadLink:
type: string
description: A link to download a detailed report on the outcome of the bulk import.
imports:
type: array
description: Detailed information about the imported items.
items:
type: object
description: Object with detailed information.
properties:
name:
type: string
description: Unique identifier associated with the imported item.
importedRows:
type: integer
description: Total number of lines successfully imported.
rowsWithError:
type: integer
description: Total number of lines that encountered errors during import.
validationResult:
type: object
description: Object containing information about bulk import state.
required:
- accountName
- importId
- importState
- percentage
- lastUpdateDate
- fileName
- validationResult
properties:
accountName:
type: string
description: Name of your VTEX account.
importId:
type: string
description: Unique identifier of the import.
importState:
type: string
description: |-
Current state of the import. The possible values are:
- `Uploaded`: The file was successfully uploaded.
- `InValidation`: File validation is in progress.
- `ReadyToImport`: File validation completed, ready for import.
- `Completed`: File successfully imported.
- `ValidationFailed`: File validation failed.
- `CompletedWithError`: File import failed.
percentage:
type: string
description: Completion percentage of the import.
lastUpdateDate:
type: string
description: Date and time of the last update of the import, in `yyyy-mm-ddTHH:MM:SS+00:00` format.
fileName:
type: string
description: Name of the file being imported.
validationResult:
type: object
description: Information about the result of bulk imported data validation.
properties:
isValid:
type: boolean
description: Indicates whether the bulk import operation was successful.
validationResult:
type: array
description: Detailed information about the validation results.
items:
type: object
description: Object with detailed information.
properties:
name:
type: string
description: Unique identifier associated with the imported item.
validRows:
type: integer
description: Total number of lines successfully validated.
invalidRows:
type: integer
description: Number of imported lines that failed validation.
securitySchemes:
appKey:
type: apiKey
in: header
name: X-VTEX-API-AppKey
description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
appToken:
type: apiKey
in: header
name: X-VTEX-API-AppToken
description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-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.'
tags:
- name: Bulk Import
security:
- appKey: []
appToken: []
- VtexIdclientAutCookie: []