{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "Organization Units API", "description": "The Organization Units API enables you to manage B2B functionalities in your VTEX store, focusing on users and organization units. This API provides endpoints for managing users, organization units, and their associated scopes.\n\n>⚠️ This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.\n\n## Common parameters\n\n| Parameter name | Description | Type |\n| - | - | - |\n| `accountName` | Name of the VTEX account. Used as part of the URL. | Server variable. |\n| `environment` | Environment to use. Used as part of the URL. | Server variable. |\n| `VtexIdclientAutCookie` | [User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header. |" }, "servers": [ { "url": "https://{accountName}.{environment}.com", "description": "VTEX server URL.", "variables": { "accountName": { "default": "apiexamples", "description": "Name of the VTEX account. Used as part of the URL." }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "myvtex" ], "default": "myvtex" } } } ], "paths": { "/api/organization-units/v1/users/{userId}/scopes": { "get": { "tags": [ "Users" ], "summary": "Get user scopes", "description": "Retrieves all scopes associated with a user's 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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "userId", "in": "path", "description": "Unique identifier (GUID) of the user.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "4a7b24a8-45b8-3b5c-73a9-9a3b8a4a5a7a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of scopes with their types and associated values.", "items": { "$ref": "#/components/schemas/ScopeResponse" } }, "example": [ { "scope": "contractIds", "ids": [ "contract-123", "contract-456" ] }, { "scope": "collectionIds", "ids": [ "collection-789" ] } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "User not found." } } } } } } }, "/api/organization-units/v1/{userId}/unit": { "get": { "tags": [ "Users" ], "summary": "Get user's organization unit", "description": "Retrieves the organization unit associated with a specific user.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "userId", "in": "path", "description": "Unique identifier (GUID) of the user.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "4a7b24a8-45b8-3b5c-73a9-9a3b8a4a5a7a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T10:30:00.000Z" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "User or organization unit not found." } } } } } } }, "/api/organization-units/v1": { "post": { "tags": [ "Units" ], "summary": "Create organization unit", "description": "Creates a new organization unit at the root level of the organizational hierarchy. After creation, you can move the organization unit to a desired parent using the `PUT` [Move organization unit](https://developers.vtex.com/docs/api-reference/organization-units-api#put-/api/organization-units/v1/-organizationUnitId-/path) endpoint.\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| Organization Units | units | **Edit_Organization_Unit** |\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": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the new organization unit.", "example": "Marketing Department" }, "type": { "type": "string", "description": "Type of the organization unit. If not provided, defaults to `Buyer Org`. Set to `Sales Team` when creating units through the [Sales Team Management integration guide](https://developers.vtex.com/docs/guides/sales-team-management-integration-guide).", "enum": [ "Buyer Org", "Sales Team" ], "default": "Buyer Org", "example": "Sales Team" } } }, "example": { "name": "Marketing Department" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the organization unit was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update." }, "name": { "type": "string", "description": "Name of the organization unit." }, "type": { "type": "string", "description": "Type of the organization unit.", "enum": [ "Buyer Org", "Sales Team" ], "default": "Buyer Org" }, "path": { "type": "object", "description": "Hierarchical path of the organization unit.", "properties": { "ids": { "type": "string", "description": "Full ID path of the organization unit." } } }, "id": { "type": "string", "description": "ID of the organization unit." }, "customerGroup": { "type": "object", "description": "Group of customers associated with the organization unit.", "properties": { "customerIds": { "type": "array", "description": "List of associated customer IDs (can be empty).", "items": { "type": "string", "description": "ID of the customer." } } } } } }, "example": { "createdAt": "2025-03-19T21:28:13.103978Z", "updatedAt": "2025-03-19T21:28:13.103978Z", "name": "new-unit", "type": "Buyer Org", "path": { "ids": "qastore/b13531bb-8242-43fd-80f5-3263dd4e9cdd/92264b68-74da-4fc4-b51a-9ddcb8baf29a" }, "id": "92264b68-74da-4fc4-b51a-9ddcb8baf29a", "customerGroup": { "customerIds": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid organization unit name." } } } } } }, "get": { "tags": [ "Units" ], "summary": "Search organization units", "description": "Searches for organization units based on query parameters, with pagination support. If no name or type filter is provided, returns all organization units for the account.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "name", "in": "query", "description": "Name or partial name of the organization unit to search for. If not provided, all units are returned.", "required": false, "schema": { "type": "string", "example": "Marketing" } }, { "name": "type", "in": "query", "description": "Filters organization units by type. If not provided, units of all types are returned. See the [Sales Team Management integration guide](https://developers.vtex.com/docs/guides/sales-team-management-integration-guide) for more on the `Sales Team` type.", "required": false, "schema": { "type": "string", "enum": [ "Buyer Org", "Sales Team" ], "example": "Sales Team" } }, { "name": "page", "in": "query", "description": "Page number for pagination. Must be greater than 0.", "required": false, "style": "form", "schema": { "type": "integer", "format": "int32", "minimum": 1, "default": 1, "example": 1 } }, { "name": "pageSize", "in": "query", "description": "Number of items per page. Must be between 1 and 1000.", "required": false, "style": "form", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 1000, "default": 20, "example": 20 } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of organization units matching the search criteria.", "items": { "$ref": "#/components/schemas/OrganizationUnit" } }, "example": [ { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T10:30:00.000Z" }, { "id": "7c9a57d1-78e0-4c8e-a6b2-2a6e1b7d8c0b", "name": "Marketing Operations", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a/7c9a57d1-78e0-4c8e-a6b2-2a6e1b7d8c0b" }, "createdAt": "2025-10-21T11:00:00.000Z", "updatedAt": "2025-10-21T11:00:00.000Z" } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid pagination parameters." } } } } } } }, "/api/organization-units/v1/{organizationUnitId}": { "get": { "tags": [ "Units" ], "summary": "Get organization unit", "description": "Retrieves details of a specific organization unit by its unique identifier.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T10:30:00.000Z" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } }, "delete": { "tags": [ "Units" ], "summary": "Delete organization unit", "description": "Deletes an organization unit. If the unit has children and the `cascade` parameter is `true`, all children will also be deleted. If `cascade` is `false` and the unit has children, the request will fail.\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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit to delete.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "cascade", "in": "query", "description": "If `true`, deletes all child organization units of the specified organization unit. If `false` and the organization unit has children, the request will fail.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Cannot delete organization unit with children. Set cascade to true to delete all children." } } } } } }, "patch": { "tags": [ "Units" ], "summary": "Rename organization unit", "description": "Updates the name of an existing 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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit to update.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "New name for the organization unit.", "example": "Marketing and Communications Department" } } }, "example": { "name": "Marketing and Communications Department" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing and Communications Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T14:45:00.000Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid organization unit name." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } } }, "/api/organization-units/v1/{organizationUnitId}/children": { "get": { "tags": [ "Units" ], "summary": "Get all children organization units", "description": "Lists all children of a specific organization unit. The `shallowSearch` parameter controls whether to retrieve only direct children or all descendants.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the parent organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "shallowSearch", "in": "query", "description": "Indicates whether to retrieve only direct children (`true`) or all descendants (`false`).", "required": false, "style": "form", "schema": { "type": "boolean", "default": true, "example": true } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "List of child organization units.", "items": { "$ref": "#/components/schemas/OrganizationUnit" } }, "example": [ { "id": "7c9a57d1-78e0-4c8e-a6b2-2a6e1b7d8c0b", "name": "Marketing Operations", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a/7c9a57d1-78e0-4c8e-a6b2-2a6e1b7d8c0b" }, "createdAt": "2025-10-21T11:00:00.000Z", "updatedAt": "2025-10-21T11:00:00.000Z" }, { "id": "5a8b35b9-56c9-3a6c-84a0-0a4c9a5b6a8a", "name": "Marketing Communications", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a/5a8b35b9-56c9-3a6c-84a0-0a4c9a5b6a8a" }, "createdAt": "2025-10-21T11:15:00.000Z", "updatedAt": "2025-10-21T11:15:00.000Z" } ] } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } } }, "/api/organization-units/v1/roots": { "get": { "tags": [ "Units" ], "summary": "Get root organization units", "description": "Retrieves all root-level organization units for the account. Root units are top-level units with no parent.\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| Organization Units | units | **View_Organization_Unit** |\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" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of root organization units.", "items": { "$ref": "#/components/schemas/OrganizationUnit" } }, "example": [ { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T10:30:00.000Z" }, { "id": "6b7a46c0-67d9-4b7d-95a1-1a5d0a6c7b9c", "name": "Sales Department", "path": { "ids": "apiexamples/6b7a46c0-67d9-4b7d-95a1-1a5d0a6c7b9c" }, "createdAt": "2025-10-21T09:15:00.000Z", "updatedAt": "2025-10-21T09:15:00.000Z" } ] } } } } } }, "/api/organization-units/v1/{organizationUnitId}/path": { "put": { "tags": [ "Units" ], "summary": "Move organization unit", "description": "Moves an organization unit to a different parent in the hierarchy. If no `parentId` is provided in the request body, the organization unit becomes a root 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| Organization Units | units | **Move_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit to move.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "7c9a57d1-78e0-4c8e-a6b2-2a6e1b7d8c0b" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parentId" ], "description": "Request body for moving an organization unit to a new parent.", "properties": { "parentId": { "type": "string", "format": "uuid", "description": "Unique identifier of the new parent organization unit. If not provided, the organization unit becomes a root organization unit.", "nullable": true, "example": "6b7a46c0-67d9-4b7d-95a1-1a5d0a6c7b9c" } } }, "example": { "parentId": "b13531bb-8242-43fd-80f5-3263dd4e9cdd" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing and Communications Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T14:45:00.000Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid organization unit name." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } } }, "/api/vtexid/organization-units/{organizationUnitId}/users": { "post": { "tags": [ "Units" ], "summary": "Add user to organization unit", "description": "Adds a user to 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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "force", "in": "query", "description": "Indicates whether user should be forcefully moved to the organization unit in case they are already assigned to another organization unit. If set to `true`, users already assigned to the organization unit will be returned in `addedUserIds`. If set to `false`, those users will appear in `failedUserIds` instead.", "required": true, "schema": { "type": "boolean", "example": false } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for adding users to an organization unit.", "required": [ "userIds" ], "properties": { "userIds": { "type": "array", "description": "List of user IDs to add to the organization unit.", "items": { "type": "string", "description": "ID of the user to add to the organization unit.", "example": "92264b68-74da-4fc4-b51a-9ddcb8baf29a" } } } }, "example": { "userIds": [ "92264b68-74da-4fc4-b51a-9ddcb8baf29a" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationUnitId": { "type": "string", "description": "ID of the organization unit." }, "addedUserIds": { "type": "array", "description": "List of user IDs that were successfully added to the organization unit.", "items": { "type": "string", "description": "ID of the user that was added to the organization unit." } }, "failedUserIds": { "type": "array", "description": "List of user IDs that were not added to the organization unit (can be empty).", "items": { "type": "string", "description": "ID of the user that was not added to the organization unit." } } } }, "example": { "organizationUnitId": "b13531bb-8242-43fd-80f5-3263dd4e9cdd", "addedUserIds": [ "468cc9c0-e8bd-4826-b7a6-13dce147dc26" ], "failedUserIds": [] } } } } } }, "delete": { "tags": [ "Units" ], "summary": "Remove users from organization unit", "description": "Removes one or more users from 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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "userIds" ], "properties": { "userIds": { "type": "array", "description": "List of user IDs to remove from the organization unit.", "items": { "type": "string", "description": "ID of the user to remove from the organization unit.", "example": "92264b68-74da-4fc4-b51a-9ddcb8baf29a" } } } }, "example": { "userIds": [ "92264b68-74da-4fc4-b51a-9ddcb8baf29a" ] } } } }, "responses": { "200": { "description": "OK" } } }, "get": { "tags": [ "Units" ], "summary": "List users from organization unit", "description": "Retrieves all users associated with 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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response object containing the list of users in the organization unit.", "properties": { "users": { "type": "array", "description": "List of users in the organization unit.", "items": { "type": "object", "description": "User object.", "properties": { "userId": { "type": "string", "description": "User's unique identifier." }, "login": { "type": "string", "description": "User's email address." } } } } } }, "example": { "users": [ { "userId": "860cf3ed-1c50-4054-b367-99c8f6138fcc", "login": "daniel.white@email.com" }, { "userId": "37eba317-9154-4844-8ecd-afc5ffb0bf23", "login": "john.thomas@email.com" }, { "userId": "468cc9c0-e8bd-4826-b7a6-13dce147dc26", "login": "emma.harris@email.com" } ] } } } } } } }, "/api/organization-units/v1/{organizationUnitId}/scopes": { "get": { "tags": [ "Scopes" ], "summary": "Get organization unit scopes", "description": "Retrieves all scopes defined for a specific organization unit. Scopes represent domain-specific attributes such as contract IDs, collection IDs, or addresses.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Response object containing the scopes of the organization unit.", "properties": { "organizationUnitId": { "type": "string", "description": "ID of the organization unit." }, "scopes": { "type": "array", "description": "List of scope objects assigned to the unit.", "items": { "type": "object", "description": "Scope object.", "properties": { "scope": { "type": "string", "description": "Type of the scope.", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ] }, "ids": { "type": "array", "description": "List of IDs associated with the scope.", "items": { "type": "string", "description": "ID of the scope value." } } } } } } }, "example": { "organizationUnitId": "92264b68-74da-4fc4-b51a-9ddcb8baf29a", "scopes": [ { "scope": "creditCards", "ids": [ "21770434-1061-4ac5-bb4c-fce528aefbd1" ] } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } }, "delete": { "tags": [ "Scopes" ], "summary": "Delete all scopes from organization unit", "description": "Deletes all scopes from an 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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T16:00:00.000Z" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Organization unit not found." } } } } } } }, "/api/organization-units/v1/{organizationUnitId}/scopes/{scope}": { "post": { "tags": [ "Scopes" ], "summary": "Create organization unit scope", "description": "Creates a new scope with specified values for an organization unit. If the scope already exists, this operation will fail.\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| Organization Units | units | **Edit_Organization_Unit** |\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": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "scope", "in": "path", "description": "Name of the scope category for which data should be retrieved. Supported values are: `contractIds`, `creditCards`, `installmentOptions`, `collectionIds`, `priceTables`, `paymentSystemIds`, `addresses`, `customFields`.", "required": true, "schema": { "type": "string", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ], "example": "contractIds" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeValuesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeOperationResponse" }, "example": { "organizationUnitId": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "scope": "contractIds", "ids": [ "contract-123", "contract-456" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Scope already exists for this organization unit." } } } } } }, "put": { "tags": [ "Scopes" ], "summary": "Update organization unit scope", "description": "Updates an existing scope by replacing all its values with the provided set.\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| Organization Units | units | **Edit_Organization_Unit** |\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": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "scope", "in": "path", "description": "Name of the scope category for which data should be retrieved. Supported values are: `contractIds`, `creditCards`, `installmentOptions`, `collectionIds`, `priceTables`, `paymentSystemIds`, `addresses`, `customFields`.", "required": true, "schema": { "type": "string", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ], "example": "contractIds" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeValuesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeOperationResponse" }, "example": { "organizationUnitId": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "scope": "contractIds", "ids": [ "contract-789", "contract-101" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid scope values provided." } } } } } }, "delete": { "tags": [ "Scopes" ], "summary": "Delete organization unit scope", "description": "Deletes a specific scope from an organization unit, removing all associated values.\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| Organization Units | units | **Edit_Organization_Unit** |\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": [ { "name": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "scope", "in": "path", "description": "Name of the scope category for which data should be retrieved. Supported values are: `contractIds`, `creditCards`, `installmentOptions`, `collectionIds`, `priceTables`, `paymentSystemIds`, `addresses`, `customFields`.", "required": true, "schema": { "type": "string", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ], "example": "contractIds" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUnit" }, "example": { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department", "path": { "ids": "apiexamples/8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" }, "createdAt": "2025-10-21T10:30:00.000Z", "updatedAt": "2025-10-21T16:30:00.000Z" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Scope not found." } } } } } } }, "/api/organization-units/v1/{organizationUnitId}/scopes/{scope}/remove": { "delete": { "tags": [ "Scopes" ], "summary": "Remove values from organization unit scope", "description": "Removes specific values from an organization unit scope without deleting the entire scope. If all values are removed, the scope remains but with an empty set of values.\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| Organization Units | units | **Edit_Organization_Unit** |\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": "organizationUnitId", "in": "path", "description": "Unique identifier (GUID) of the organization unit.", "required": true, "style": "simple", "schema": { "type": "string", "format": "uuid", "example": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a" } }, { "name": "scope", "in": "path", "description": "Name of the scope category for which data should be retrieved. Supported values are: `contractIds`, `creditCards`, `installmentOptions`, `collectionIds`, `priceTables`, `paymentSystemIds`, `addresses`, `customFields`.", "required": true, "schema": { "type": "string", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ], "example": "contractIds" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeValuesRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeOperationResponse" }, "example": { "organizationUnitId": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "scope": "contractIds", "ids": [ "contract-456" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid scope values provided." } } } } } } }, "/api/organization-units/v1/scope/{scope}/value/{scopeValue}": { "get": { "tags": [ "Units" ], "summary": "Find all organization units with scope value", "description": "Retrieves all organization units that have a specific scope value. This is useful for reverse lookups, such as finding which organization units are associated with a particular contract ID. Optionally, results can be filtered by organization unit type using the `type` query parameter.\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| Organization Units | units | **View_Organization_Unit** |\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": [ { "name": "scope", "in": "path", "description": "Name of the scope category for which data should be retrieved. Supported values are: `contractIds`, `creditCards`, `installmentOptions`, `collectionIds`, `priceTables`, `paymentSystemIds`, `addresses`, `customFields`.", "required": true, "schema": { "type": "string", "enum": [ "contractIds", "creditCards", "installmentOptions", "collectionIds", "priceTables", "paymentSystemIds", "addresses", "customFields" ], "example": "contractIds" } }, { "name": "scopeValue", "in": "path", "description": "Unique identifier within the given scope. Example: For contractIds, use the contract ID.", "required": true, "schema": { "type": "string", "example": "9025fbdd-6271-11f0-b37f-f5b4d28a6ca2" } }, { "name": "type", "in": "query", "description": "Filters the returned organization units by type. If not provided, units of all types are returned. If no organization unit matches both the scope value and the given type, the response status is `204`. See the [Sales Team Management integration guide](https://developers.vtex.com/docs/guides/sales-team-management-integration-guide) for more on the `Sales Team` type.", "required": false, "schema": { "type": "string", "enum": [ "Buyer Org", "Sales Team" ], "example": "Sales Team" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "description": "Array of organization units that contain the specified scope value.", "items": { "$ref": "#/components/schemas/UnitDto" } }, "example": [ { "id": "8d8b68e2-89e1-4d9f-b7c3-3a7f2c8e9d1a", "name": "Marketing Department" }, { "id": "6b7a46c0-67d9-4b7d-95a1-1a5d0a6c7b9c", "name": "Sales Department" } ] } } }, "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "No organization units found with the specified scope value." } } } } } } } }, "security": [ { "VtexIdclientAutCookie": [] } ], "components": { "securitySchemes": { "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": { "ErrorResponse": { "type": "object", "description": "Error response object.", "properties": { "message": { "type": "string", "description": "Error message describing what went wrong." } } }, "OrganizationUnit": { "type": "object", "description": "Organization unit object.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organization unit." }, "name": { "type": "string", "description": "Name of the organization unit." }, "type": { "type": "string", "description": "Type of the organization unit. `Buyer Org` represents a regular organization unit within a buyer organization. `Sales Team` represents a sales team unit created through the [Sales Team Management integration guide](https://developers.vtex.com/docs/guides/sales-team-management-integration-guide).", "enum": [ "Buyer Org", "Sales Team" ], "default": "Buyer Org", "example": "Buyer Org" }, "path": { "type": "object", "description": "Hierarchical path of the organization unit.", "properties": { "ids": { "type": "string", "description": "Forward-slash separated path of IDs from tenant root to this unit." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the organization unit was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the organization unit was last updated." } } }, "ScopeResponse": { "type": "object", "description": "Scope with associated values.", "properties": { "scope": { "type": "string", "description": "Scope type identifier." }, "ids": { "type": "array", "description": "List of values associated with this scope.", "items": { "type": "string", "description": "Scope value." } } } }, "ScopeValuesRequest": { "type": "object", "description": "Request body containing scope values.", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "Set of unique values for the scope.", "items": { "type": "string", "description": "Scope value identifier.", "example": "contract-123" }, "example": [ "contract-123", "contract-456" ] } } }, "ScopeOperationResponse": { "type": "object", "description": "Response for scope creation, update, or removal operations.", "properties": { "organizationUnitId": { "type": "string", "format": "uuid", "description": "Unique identifier of the organization unit." }, "scope": { "type": "string", "description": "Scope type identifier." }, "ids": { "type": "array", "description": "Current list of values for this scope after the operation.", "items": { "type": "string", "description": "Scope value." } } } }, "UnitDto": { "type": "object", "description": "Simplified organization unit object.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the organization unit." }, "name": { "type": "string", "description": "Name of the organization unit." } } } } }, "tags": [ { "name": "Users" }, { "name": "Units" }, { "name": "Scopes" } ] }