{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Budgets API", "description": "A **Budget** is a financial management tool that enables organizations to plan and monitor expenses, ensuring resources are allocated efficiently and in compliance with strategic criteria.\r\n\r\nThe **Budgets API** is a comprehensive budget management service that allows you to create, manage, and control **Budgets**, **Allocations**, **Transactions**, and **Reservations**.\r\n\r\nMerchants and B2B organizations can manage store expenses using this API, promoting financial transparency, traceability, and control.\r\n\r\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\r\n\r\n## Budget and Allocation\r\n\r\nEach **Budget** can have one or more **Allocations**, which are subdivisions of the total balance within that **Budget**.\r\n\r\nEach **Budget** and **Allocation** has its own **amount**, **start date**, and **end date**. When funds are added to or removed from an **Allocation**, the corresponding **Budget**'s total amount is updated accordingly to reflect the change.\r\n\r\n## Transactions and Reservations\r\n\r\nTo move funds from an **Allocation**, there are two options:\r\n\r\n- **Direct Transaction** \r\n Used when you want to actually consume the balance. This creates a definitive entry that appears in the **Statements** (transaction history).\r\n \r\n- **Reservation** \r\n Used to temporarily reserve funds without consuming them immediately. Later, you can either:\r\n \r\n - **Confirm the reservation**, which automatically creates a **Transaction**.\r\n \r\n - **Delete the reservation**, which simply releases the reserved balance without generating any **Transaction** (it does not appear in the **Statements**).\r\n \r\n\r\n## Refunds\r\n\r\n**Transactions** cannot be deleted. If you need to undo a **Transaction**, you must create a **Refund**, which is a new **Transaction** with the type. Both the original **Transaction** and the **Refund** will appear in the **Statements**, with a net effect of zero.\r\n\r\n## Transaction types\r\n\r\nWhen you get a **Budget** or **Allocation** statement, each **Transaction** contains a `type` field, which can carry two values:\r\n\r\n- `DEBIT`: Regular **Transactions**, subtracting funds from the **Budget** or **Allocation**.\r\n \r\n- `CREDIT`: Associated with **Refunds**, meaning it adds funds to the **Budget** or **Allocation**.\r\n \r\n\r\n## Typical API Call Order\r\n\r\n1. Create the **Budget**.\r\n \r\n2. Create one or more **Allocations**.\r\n \r\n3. Perform a **Transaction** or a **Reservation**.\r\n \r\n4. Retrieve the transaction history using the **Statements** endpoints.\r\n \r\n\r\n> In a typical purchase flow, we do not use **Reservations**. We create direct **Transactions** and use **Refunds** when needed.\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| `{{VtexIdclientAutCookie}}` | [User token](https:\/\/developers.vtex.com\/docs\/guides\/api-authentication-using-user-tokens), valid for 24 hours. |" }, "servers": [ { "url": "https://{accountName}.{environment}.com", "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": ["myvtex"], "default": "myvtex" } } } ], "paths": { "/api/budgets/{contextType}/{contextId}/{budgetId}/statements": { "get": { "tags": ["Statements"], "summary": "Get budget statements", "description": "Retrieves the list of transactions (statement) for a specific budget within the VTEX Budgets API.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "transactions": { "type": "array", "description": "List of transaction entries.", "items": { "type": "object", "description": "Transaction entry.", "properties": { "id": { "type": "string", "description": "Identifier of the transaction." }, "budgetId": { "type": "string", "description": "Identifier of the budget." }, "allocationId": { "type": "string", "description": "Identifier of the associated allocation." }, "type": { "type": "string", "enum": [ "DEBIT", "CREDIT" ], "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund)." }, "amount": { "type": "number", "description": "Amount involved in the transaction." }, "date": { "type": "string", "format": "date-time", "description": "ISO timestamp when the transaction occurred (format: YYYY-MM-DDThh:mm:ssZ)." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "example": { "pagination": { "current": 1, "pages": 1, "results": 1 }, "transactions": [ { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "019833db-27ad-7264-b104-dfed7c0fcbac", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "type": "DEBIT", "amount": 528, "date": "2025-05-17T07:01:44.0196090Z", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Budget not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/statements": { "get": { "tags": ["Statements"], "summary": "Get allocation statements", "description": "Retrieves the list of transactions (statement) for a specific allocation within a VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "transactions": { "type": "array", "description": "List of transaction entries.", "items": { "type": "object", "description": "Transaction entry.", "properties": { "id": { "type": "string", "description": "Identifier of the transaction." }, "budgetId": { "type": "string", "description": "Identifier of the budget." }, "allocationId": { "type": "string", "description": "Identifier of the associated allocation." }, "type": { "type": "string", "enum": [ "DEBIT", "CREDIT" ], "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund)." }, "amount": { "type": "number", "description": "Amount involved in the transaction." }, "date": { "type": "string", "format": "date-time", "description": "ISO timestamp when the transaction occurred (format: YYYY-MM-DDThh:mm:ssZ)." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "example": { "pagination": { "current": 1, "pages": 1, "results": 1 }, "transactions": [ { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "019833db-27ad-7264-b104-dfed7c0fcbac", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "type": "DEBIT", "amount": 528, "date": "2025-05-17T07:01:44.0196090Z", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/transactions": { "post": { "tags": ["Transactions"], "summary": "Create transaction", "description": "Creates a new transaction which subtracts funds from the specified budget allocation.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "origin", "amount", "requestedBy", "type" ], "properties": { "origin": { "type": "string", "description": "Describes the origin or reason for the adjustment." }, "reference": { "type": "string", "description": "Reference ID or note for tracking the adjustment." }, "amount": { "type": "number", "description": "Amount to adjust. For `DEBIT` transactions, provide a negative value (the amount will be subtracted from the allocation). For `CREDIT` transactions, provide a positive value (the amount will be added to the allocation)." }, "type": { "type": "string", "description": "Condition that defines how the transaction will impact the budget (e.g., `DEBIT` or `CREDIT`). If `type` is `DEBIT`, the amount will be subtracted from the budget. If `type` is `CREDIT`, the amount will be added to the budget.", "enum": ["DEBIT", "CREDIT"] }, "requestedBy": { "type": "string", "format": "email", "description": "Email of the user requesting the change." } } }, "example": { "origin": "ecommerce", "reference": "093c891a-84a7-42cb-8a23-eb6dcf6607d4", "amount": 50.0, "requestedBy": "user1@email.com", "type": "DEBIT" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "id": "880e8400-e29b-41d4-a716-446655440000", "budgetId": "550e8400-e29b-41d4-a716-446655440000", "allocationId": "660e8400-e29b-41d4-a716-446655440000", "origin": "ecommerce", "reference": "093c891a-84a7-42cb-8a23-eb6dcf6607d4", "amount": 50.0, "requestedBy": "user1@email.com", "date": "2025-01-20T10:15:00Z", "type": "DEBIT", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/transactions/{transactionId}/refund": { "post": { "tags": ["Transactions"], "summary": "Refund transaction", "description": "Refunds a specific transaction from a budget allocation by creating a new **`CREDIT`** statement item, which adds funds back to the specified budget allocation.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/transactionId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["requestedBy"], "properties": { "requestedBy": { "type": "string", "format": "email", "description": "The email of the user initiating the refund." } } }, "example": { "requestedBy": "user1@email.com" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the newly created refund transaction." }, "originalTransactionId": { "type": "string", "description": "Identifier of the original transaction being refunded." }, "budgetId": { "type": "string", "description": "Identifier of the associated budget." }, "allocationId": { "type": "string", "description": "Identifier of the associated allocation within the budget." } } }, "example": { "id": "1bd05512-e694-4f0e-b182-bbe30ba7b613", "originalTransactionId": "b343e863-f558-4b53-b250-0ad819f06642", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/transactions/{transactionId}": { "get": { "tags": ["Transactions"], "summary": "Get transaction", "description": "Retrieves a specific transaction from a budget allocation in the VTEX Budgets API.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/transactionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "example": { "id": "1bd05512-e694-4f0e-b182-bbe30ba7b613", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "origin": "TEST", "reference": "f0e2b16b-ad4c-485d-adb2-84c78d9354e7", "amount": 480, "requestedBy": "user1@email.com" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/reservations": { "post": { "tags": ["Reservations"], "summary": "Create reservation", "description": "Creates a temporary reservation under a specific allocation in a VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "origin", "reference", "amount", "requestedBy", "reservationId", "type" ], "properties": { "origin": { "type": "string", "description": "The origin of the reservation (e.g., order system)." }, "reference": { "type": "string", "description": "Reference tied to the reservation (e.g., order ID)." }, "amount": { "type": "number", "description": "Amount to be reserved." }, "requestedBy": { "type": "string", "format": "email", "description": "Email of the user initiating the reservation." }, "reservationId": { "type": "string", "description": "Client-defined identifier for the reservation." }, "type": { "type": "string", "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund).", "enum": ["DEBIT", "CREDIT"], "example": "DEBIT" } } }, "example": { "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": -150, "requestedBy": "user1@email.com", "reservationId": "c3722334-3892-418c-a099-b13e9c562c7e", "type": "DEBIT" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationResponse" }, "example": { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": -150, "requestedBy": "user1@email.com", "date": "2025-07-22T20:43:56.8455190Z", "type": "DEBIT", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "get": { "tags": ["Reservations"], "summary": "List reservations", "description": "Retrieves a list of reservations under a specific allocation in a VTEX budget, optionally filtered by status.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/status" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "items": { "type": "array", "description": "List of reservation objects.", "items": { "type": "object", "description": "Reservation object.", "properties": { "id": { "type": "string", "description": "Identifier of the reservation." }, "budgetId": { "type": "string", "description": "Identifier of the associated budget." }, "allocationId": { "type": "string", "description": "Identifier of the associated allocation." }, "type": { "type": "string", "enum": [ "DEBIT", "CREDIT" ], "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund)." }, "amount": { "type": "number", "description": "Amount reserved." }, "date": { "type": "string", "format": "date-time", "description": "ISO timestamp when the transaction occurred (format: YYYY-MM-DDThh:mm:ssZ)." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } }, "example": { "pagination": { "current": 1, "pages": 1, "results": 1 }, "items": [ { "id": "299a291e-65bf-4c4c-9209-bdaa6f620d07", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "137793ab-efb6-4af7-a287-dd864cda336b", "type": "DEBIT", "amount": -726, "date": "2025-07-22 20:43:43", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ], "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/reservations/{reservationId}": { "get": { "tags": ["Reservations"], "summary": "Get reservation", "description": "Retrieves a reservation under a specific allocation in a VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/reservationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationResponse" }, "example": { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": -150, "requestedBy": "user1@email.com", "date": "2025-07-22T20:43:56.8455190Z", "type": "DEBIT", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "delete": { "tags": ["Reservations"], "summary": "Delete reservation", "description": "Cancels a reservation under a specific allocation in a VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/reservationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["requestedBy"], "properties": { "requestedBy": { "type": "string", "format": "email", "description": "Email of the user canceling the reservation.", "example": "user1@email.com" } } }, "example": { "requestedBy": "user1@email.com" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationResponse" }, "example": { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": -150, "requestedBy": "user1@email.com", "date": "2025-07-22T20:43:56.8455190Z", "type": "DEBIT", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Cannot delete resource due to existing dependencies." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/reservations/{reservationId}/confirmation": { "post": { "tags": ["Reservations"], "summary": "Confirm reservation", "description": "Confirms a reservation under a specific allocation in a VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" }, { "$ref": "#/components/parameters/reservationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["requestedBy"], "properties": { "requestedBy": { "type": "string", "format": "email", "description": "Email of the user confirming the reservation.", "example": "user1@email.com" } } }, "example": { "requestedBy": "user1@email.com" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationResponse" }, "example": { "id": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3", "budgetId": "137793ab-efb6-4af7-a287-dd864cda336b", "allocationId": "324b5750-c827-4a6b-a670-c9297c832f4e", "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": -150, "requestedBy": "user1@email.com", "date": "2025-07-22T20:43:56.8455190Z", "type": "DEBIT", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations": { "post": { "tags": ["Allocations"], "summary": "Create allocation", "description": "Creates a new allocation within a specific VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedEntity", "referenceId", "amount" ], "properties": { "linkedEntity": { "type": "object", "description": "Linked entity information.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field.", "example": "f07c85ed-ea1f-443e-953d-0f1b094ed012" }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration)).", "example": "User" } } }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract).", "example": "4d00d477-e4fe-4345-b5cd-ba2ef1725cc8" }, "amount": { "type": "number", "description": "Amount allocated." }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" } } }, "example": { "linkedEntity": { "id": "f07c85ed-ea1f-443e-953d-0f1b094ed012", "type": "CostCenter" }, "referenceId": "4d00d477-e4fe-4345-b5cd-ba2ef1725cc8", "amount": 658, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationResponse" }, "example": { "id": "0197c1f6-eca5-7553-bbf1-34d3cc4ccf2d", "budgetId": "0197c1eb-3f62-73e1-93a2-6fa5d37b74f1", "linkedEntity": { "id": "3bfdafe0-a111-4ce9-9205-1dd5f872b44e", "type": "CostCenter" }, "balance": { "amount": 358, "balanceAdjustment": 0, "remaining": 358 }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "referenceId": "67c9779d-b9a8-4512-a746-5f41361c7270", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "get": { "tags": ["Allocations"], "summary": "List budget allocations", "description": "Retrieves the allocations for a specific budget, with optional filtering by entity type.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/type" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/allocationStatus" }, { "$ref": "#/components/parameters/referenceId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "items": { "type": "array", "description": "List of budget allocations.", "items": { "type": "object", "description": "Allocation object.", "properties": { "id": { "type": "string", "description": "Identifier of the allocation." }, "budgetId": { "type": "string", "description": "Identifier of the budget to which the allocation belongs." }, "linkedEntity": { "type": "object", "description": "Linked entity information.", "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "balance": { "type": "object", "description": "Budget balance information.", "properties": { "amount": { "type": "number", "description": "Total amount allocated." }, "balanceAdjustment": { "type": "number", "description": "Total amount used." }, "remaining": { "type": "number", "description": "Current balance left for this allocation." } } }, "status": { "type": "string", "description": "Status of the allocation (e.g., `ACTIVE`, `INACTIVE` or `DELETE`).", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ] }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "example": { "pagination": { "current": 1, "pages": 1, "results": 3 }, "items": [ { "id": "f8dc5da1-bac5-4d5c-8907-b29f8dda4e18", "budgetId": "d5793a13-c453-483b-8fc3-d17d96282c15", "linkedEntity": { "id": "565db6d8-e125-404d-8d9d-20d96dce10c6", "type": "Cont" }, "balance": { "amount": 26, "balanceAdjustment": 0, "remaining": 26 }, "status": "DELETED", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/batch": { "post": { "tags": ["Allocations"], "summary": "Create batch of allocations", "description": "Creates one or more budget allocations in batch under a specific VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["allocations"], "properties": { "allocations": { "type": "array", "description": "List of allocation objects to be created.", "items": { "type": "object", "description": "Allocation object.", "required": [ "linkedEntity", "referenceId", "amount" ], "properties": { "linkedEntity": { "type": "object", "description": "Linked entity information.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field.", "example": "PO-number-2025-001-01" }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration)).", "example": "User" } } }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract).", "example": "21795f6f-5378-11f0-b37f-842fce820b77" }, "contractId": { "type": "string", "description": "Identifier of the contract. Alternative field to `referenceId`.", "example": "21795f6f-5378-11f0-b37f-842fce820b77" }, "amount": { "type": "number", "description": "Amount allocated." }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettings" } } } } } }, "example": { "allocations": [ { "linkedEntity": { "id": "PO-number-2025-001-01", "type": "PO Number" }, "referenceId": "21795f6f-5378-11f0-b37f-842fce820b77", "contractId": "21795f6f-5378-11f0-b37f-842fce820b77", "amount": 2040 }, { "linkedEntity": { "id": "PO-number-2025-002-02", "type": "PO Number" }, "referenceId": "21795f6f-5378-11f0-b37f-842fce820b77", "amount": 2040, "notificationSettings": [ { "type": "AMOUNT", "threshold": 121, "recipients": [ { "email": "user1@email.com" } ] } ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "budgetId": { "type": "string", "description": "Unique identifier of the budget." }, "allocations": { "type": "array", "description": "List of allocation objects to be created.", "items": { "type": "object", "description": "Created allocation object.", "properties": { "id": { "type": "string", "description": "Allocation ID." }, "budgetId": { "type": "string", "description": "Budget ID." }, "linkedEntity": { "type": "object", "description": "Linked entity information.", "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "balance": { "type": "object", "description": "Allocation balance information.", "properties": { "amount": { "type": "number", "description": "Amount allocated." }, "balanceAdjustment": { "type": "number", "description": "Allocation balance adjustments." }, "remaining": { "type": "number", "description": "Balance remaining." } } }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettings" }, "status": { "type": "string", "description": "Current status of the allocation (e.g., `ACTIVE` or `INACTIVE`).", "enum": [ "ACTIVE", "INACTIVE" ] }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract)." }, "contractId": { "type": "string", "description": "Identifier of the contract. Alternative field to `referenceId`." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "example": { "budgetId": "0197c1eb-3f62-73e1-93a2-6fa5d37b74f1", "allocations": [ { "id": "0197c1f8-082a-776a-ade2-992badbcc96a", "budgetId": "0197c1eb-3f62-73e1-93a2-6fa5d37b74f1", "linkedEntity": { "id": "PO-number-2025-001-01", "type": "PO Number" }, "balance": { "amount": 2040, "balanceAdjustment": 0, "remaining": 2040 }, "status": "ACTIVE", "referenceId": "21795f6f-5378-11f0-b37f-842fce820b77", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" }, { "id": "0197c1f8-082a-776b-9eb4-f9d4822f6c34", "budgetId": "0197c1eb-3f62-73e1-93a2-6fa5d37b74f1", "linkedEntity": { "id": "PO-number-2025-002-02", "type": "PO Number" }, "balance": { "amount": 2040, "balanceAdjustment": 0, "remaining": 2040 }, "notificationSettings": [ { "type": "AMOUNT", "threshold": 121, "recipients": [ { "email": "user1@email.com" } ] } ], "status": "ACTIVE", "referenceId": "21795f6f-5378-11f0-b37f-842fce820b77", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}": { "get": { "tags": ["Allocations"], "summary": "Get allocation", "description": "Retrieves a specific allocation within a VTEX budget by its ID.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationResponse" }, "example": { "id": "0197c65e-1012-70f3-9fef-52bd7fe66a13", "budgetId": "0197c251-5b00-707b-9023-4f3d386be220", "linkedEntity": { "id": "d5c996af-455e-4b76-a36d-43376e96d82a", "type": "CostCenter" }, "balance": { "amount": 864, "balanceAdjustment": 0, "remaining": 864 }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "referenceId": "cd1e8e85-bc9e-479e-b2a5-8d916a33618f", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "put": { "tags": ["Allocations"], "summary": "Update allocation", "description": "Updates an existing budget allocation within a specific VTEX budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedEntity", "amount", "referenceId" ], "properties": { "linkedEntity": { "type": "object", "description": "Linked entity information.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to this allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field.", "example": "5ae133af-ea31-44b4-a74e-9e14752673c4" }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration)).", "example": "User" } } }, "amount": { "type": "number", "description": "Budget amount allocated." }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract).", "example": "21795f6f-5378-11f0-b37f-842fce820b77" }, "contractId": { "type": "string", "description": "Identifier of the contract. Alternative field to `referenceId`.", "example": "50e7cb46-ec05-441c-b558-78160798ceb6" }, "allocations": { "type": "array", "description": "List of allocation objects to be created.", "items": { "type": "object", "description": "Allocation object.", "properties": { "linkedEntity": { "type": "object", "description": "Linked entity information.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract)." }, "contractId": { "type": "string", "description": "Identifier of the contract. Alternative field to `referenceId`." }, "amount": { "type": "number", "description": "Amount allocated." }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" } } } }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" } } }, "example": { "linkedEntity": { "id": "5ae133af-ea31-44b4-a74e-9e14752673c4", "type": "CostCenter" }, "amount": 40, "referenceId": "50e7cb46-ec05-441c-b558-78160798ceb6", "contractId": "50e7cb46-ec05-441c-b558-78160798ceb6", "allocations": [ { "linkedEntity": { "id": "PO-number-2025-001-01", "type": "PO Number" }, "contractId": "21795f6f-5378-11f0-b37f-842fce820b77", "amount": 2040 }, { "linkedEntity": { "id": "PO-number-2025-002-02", "type": "PO Number" }, "referenceId": "21795f6f-5378-11f0-b37f-842fce820b77", "amount": 2040, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "EMAIL", "identifier": "user1@email.com" } ] } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationResponse" }, "example": { "id": "0197c1f6-eca5-7553-bbf1-34d3cc4ccf2d", "budgetId": "0197c1eb-3f62-73e1-93a2-6fa5d37b74f1", "linkedEntity": { "id": "99805a66-143c-4409-a674-600b77e10fe9", "type": "CostCenter" }, "balance": { "amount": 51, "balanceAdjustment": 0, "remaining": 51 }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "EMAIL", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "referenceId": "2c817a12-fafd-4fc9-becb-727dd7777d5f", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "delete": { "tags": ["Allocations"], "summary": "Delete allocation", "description": "Deletes a specific allocation from a budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n> Allocations are not definitively deleted, they are maintained for the sake of record keeping. When looking at statements you will be able to see transaction history for deleted allocations.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "responses": { "200": { "description": "OK\n\nThe allocation was successfully deleted." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Cannot delete resource due to existing dependencies." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/linked-entity": { "put": { "tags": ["Allocations"], "summary": "Update allocation linked entity", "description": "Updates the linked entity of a specific allocation within a budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["linkedEntityId", "linkedEntityType"], "properties": { "linkedEntityId": { "type": "string", "description": "New identifier of the entity linked to this allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field.", "example": "f07c85ed-ea1f-443e-953d-0f1b094ed012" }, "linkedEntityType": { "type": "string", "description": "New type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration)).", "example": "User" } } }, "example": { "linkedEntityId": "f07c85ed-ea1f-443e-953d-0f1b094ed012", "linkedEntityType": "CostCenter" } } } }, "responses": { "200": { "description": "OK\n\nThis request returns an empty response." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/status": { "put": { "tags": ["Allocations"], "summary": "Change allocation status", "description": "Updates the status of a specific allocation within a budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "description": "The new status value to apply to allocation (e.g., `ACTIVE` or `INACTIVE`). The `DELETED` status is not applicable in this context.", "enum": ["ACTIVE", "INACTIVE"] } } }, "example": { "status": "ACTIVE" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The updated status of the allocation (e.g., `ACTIVE`, `INACTIVE`).", "enum": ["ACTIVE", "INACTIVE"] } } }, "example": { "status": "ACTIVE" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/allocations/{allocationId}/usage": { "put": { "tags": ["Allocations"], "summary": "Update allocation usage", "description": "Updates the usage of a specific allocation within a budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" }, { "$ref": "#/components/parameters/allocationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "origin", "amount", "requestedBy", "type" ], "properties": { "origin": { "type": "string", "description": "Describes the origin or reason for the adjustment." }, "reference": { "type": "string", "description": "Reference ID or note for tracking the adjustment." }, "amount": { "type": "number", "description": "Amount to adjust (positive or negative)." }, "requestedBy": { "type": "string", "description": "Identifier or name of the system requesting the change." }, "type": { "type": "string", "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund).", "enum": ["DEBIT", "CREDIT"] } } }, "example": { "origin": "manual-adjustment", "reference": "6a2d99e3-76e6-46ec-9764-49e0a7b71331", "amount": 150.0, "requestedBy": "user1@email.com", "type": "CREDIT" } } } }, "responses": { "200": { "description": "OK\n\nThis request returns an empty response." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/allocations/query": { "post": { "tags": ["Allocations"], "summary": "Query allocations", "description": "Queries budget allocations by context and linked entities.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "description": "List of linked entities to query allocations for.", "items": { "type": "object", "description": "Linked entity to query.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } } } } }, "example": { "items": [ { "id": "41b9ec1e-af0a-45f6-b3fb-351f700a63aa", "type": "CostCenter" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of matching allocation entries.", "items": { "type": "object", "description": "Allocation query result.", "properties": { "budgetId": { "type": "string", "description": "Identifier of the budget to which the allocation belongs." }, "allocationId": { "type": "string", "description": "Identifier of the specific allocation." }, "linkedEntity": { "type": "object", "description": "Linked entity object containing `id` and `type`.", "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "budgetBalance": { "type": "object", "description": "Budget balance information.", "properties": { "amount": { "type": "number", "description": "Total budget amount." }, "balanceAdjustment": { "type": "number", "description": "Total amount utilized from the budget." }, "remaining": { "type": "number", "description": "Remaining amount in the budget." } } }, "cycleConfiguration": { "$ref": "#/components/schemas/CycleConfiguration" }, "allocationBalance": { "type": "object", "description": "Allocation balance information.", "properties": { "amount": { "type": "number", "description": "Total allocation amount." }, "balanceAdjustment": { "type": "number", "description": "Total amount utilized from the allocation." }, "remaining": { "type": "number", "description": "Remaining amount in the allocation." } } } } } } } }, "example": { "items": [ { "budgetId": "0197c65f-a1d3-71e8-ab11-013cc2f7f023", "allocationId": "0197c65f-bfb3-7452-8ae2-edf9f83624ae", "linkedEntity": { "id": "41b9ec1e-af0a-45f6-b3fb-351f700a63aa", "type": "CostCenter" }, "budgetBalance": { "amount": 1000, "balanceAdjustment": 0, "remaining": 1000 }, "cycleConfiguration": { "startDate": "2025-04-01T00:00:00.0000000Z", "endDate": "2025-04-08T00:00:00.0000000Z", "autoResetOnPeriodEnd": true, "carryOverBalance": true }, "allocationBalance": { "amount": 13, "balanceAdjustment": 0, "remaining": 13 } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}": { "post": { "tags": ["Budgets"], "summary": "Create budget", "description": "Creates a new budget with optional allocations and cycle configuration.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["name", "description", "amount"], "properties": { "name": { "type": "string", "description": "Name of the budget." }, "description": { "type": "string", "description": "Description of the budget." }, "amount": { "type": "number", "description": "Total amount allocated to the budget." }, "cycleConfiguration": { "$ref": "#/components/schemas/CycleConfiguration" }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" }, "allocations": { "type": "array", "description": "Optional list of initial allocations to create with the budget.", "items": { "type": "object", "description": "Allocation object.", "required": [ "linkedEntity", "amount", "referenceId" ], "properties": { "linkedEntity": { "type": "object", "description": "Information about the entity to which the allocation is linked.", "required": ["id", "type"], "properties": { "id": { "type": "string", "description": "Identifier of the entity. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "amount": { "type": "number", "description": "Amount allocated." }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract)." }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" } } } } } }, "example": { "name": "Grocery Store", "description": "Bermudian Dollar (customarily known as Bermuda Dollar)", "amount": 956, "cycleConfiguration": { "startDate": "2025-04-01T00:00:00.0000000Z", "endDate": "2025-04-08T00:00:00.0000000Z", "autoResetOnPeriodEnd": true, "carryOverBalance": true }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "allocations": [ { "linkedEntity": { "id": "4de8235f-ff2d-451b-bfcf-9873aeb9feee", "type": "User" }, "amount": 639, "referenceId": "8f6b3712-4c05-4ce5-8057-63fd0d69a587", "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetResponse" }, "example": { "id": "0197c1e3-a82f-7746-8614-bf518e625a92", "name": "USER 1", "description": "USER 1", "balance": { "amount": 1000, "balanceAdjustment": 0, "remaining": 1000 }, "cycleConfiguration": { "startDate": "2025-01-01T00:00:00.0000000Z", "endDate": "2055-01-01T00:00:00.0000000Z", "autoResetOnPeriodEnd": true, "carryOverBalance": true, "nextRenewal": "2055-01-01T00:00:00.0000000Z" }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14", "allocations": [ { "id": "0197c1e3-a82f-7747-8534-2aed2ba95417", "budgetId": "0197c1e3-a82f-7746-8614-bf518e625a92", "linkedEntity": { "id": "8f6b3712-4c05-4ce5-8057-63fd0d69a587", "type": "USER" }, "balance": { "amount": 1000, "balanceAdjustment": 0, "remaining": 1000 }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "referenceId": "8f6b3712-4c05-4ce5-8057-63fd0d69a587", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "get": { "tags": ["Budgets"], "summary": "List budgets", "description": "Retrieves a paginated list of budgets filtered by context and amount range.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/minAmount" }, { "$ref": "#/components/parameters/maxAmount" }, { "$ref": "#/components/parameters/budgetStatus" }, { "$ref": "#/components/parameters/budgetName" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" }, "items": { "type": "array", "description": "Array of budget summaries.", "items": { "type": "object", "description": "Budget summary object.", "properties": { "id": { "type": "string", "description": "Identifier of the budget." }, "name": { "type": "string", "description": "Name of the budget." }, "startDate": { "type": "string", "format": "date-time", "description": "Start date of the budget in ISO 8601 format (format: YYYY-MM-DDThh:mm:ssZ)." }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the budget in ISO 8601 format (format: YYYY-MM-DDThh:mm:ssZ)." }, "balance": { "type": "object", "description": "Budget balance information.", "properties": { "amount": { "type": "number", "description": "Total budget amount." }, "balanceAdjustment": { "type": "number", "description": "Amount already used." }, "remaining": { "type": "number", "description": "Remaining budget." } } }, "status": { "type": "string", "description": "Current status of the allocation (`ACTIVE` or `INACTIVE`)." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "example": { "pagination": { "current": 1, "pages": 1, "results": 2 }, "items": [ { "id": "ffc4575e-5e5c-420e-bcb7-bf4a271f5d60", "name": "Grocery Store", "startDate": "2025-03-27T00:00:00.0000000Z", "endDate": "2025-04-18T00:00:00.0000000Z", "balance": { "amount": 657, "balanceAdjustment": 0, "remaining": 657 }, "status": "ACTIVE", "contextType": "UNIT", "contextId": "unit123" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}": { "get": { "tags": ["Budgets"], "summary": "Get budget", "description": "Retrieves the details of a specific budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ViewBudget` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ViewBudget` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetResponse" }, "example": { "id": "0197c1e3-a82f-7746-8614-bf518e625a92", "name": "USER 1", "description": "USER 1", "balance": { "amount": 1000, "balanceAdjustment": 0, "remaining": 1000 }, "cycleConfiguration": { "startDate": "2025-01-01T00:00:00.0000000Z", "endDate": "2055-01-01T00:00:00.0000000Z", "autoResetOnPeriodEnd": true, "carryOverBalance": true, "nextRenewal": "2055-01-01T00:00:00.0000000Z" }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14", "allocations": [ { "id": "0197c1e3-a82f-7747-8534-2aed2ba95417", "budgetId": "0197c1e3-a82f-7746-8614-bf518e625a92", "linkedEntity": { "id": "8f6b3712-4c05-4ce5-8057-63fd0d69a587", "type": "USER" }, "balance": { "amount": 1000, "balanceAdjustment": 0, "remaining": 1000 }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "referenceId": "8f6b3712-4c05-4ce5-8057-63fd0d69a587", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "put": { "tags": ["Budgets"], "summary": "Update budget", "description": "Updates an existing budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n> ⚠️ Note that you can't update the fields `contextType` and `contextId`. You must send the original values, as they are used to validate the request.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["name", "description", "amount"], "properties": { "name": { "type": "string", "description": "Name of the budget." }, "description": { "type": "string", "description": "Description of the budget." }, "amount": { "type": "number", "description": "Updated budget amount." }, "cycleConfiguration": { "$ref": "#/components/schemas/CycleConfiguration" }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" } } }, "example": { "name": "Grocery Store", "description": "Syrian Pound", "amount": 355, "cycleConfiguration": { "startDate": "2025-03-27T00:00:00.0000000Z", "endDate": "2025-04-18T00:00:00.0000000Z", "autoResetOnPeriodEnd": false, "carryOverBalance": true }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetResponse" }, "example": { "id": "0197c1e3-a82f-7746-8614-bf518e625a92", "name": "Grocery Store", "description": "Codes specifically reserved for testing purposes", "balance": { "amount": 381, "balanceAdjustment": 0, "remaining": 381 }, "cycleConfiguration": { "startDate": "2025-01-01T00:00:00.0000000Z", "endDate": "2055-01-01T00:00:00.0000000Z", "autoResetOnPeriodEnd": false, "carryOverBalance": true }, "notificationSettings": { "enable": false, "thresholds": [ { "type": "PERCENT", "Value": 99 } ], "recipients": [ { "type": "Email", "identifier": "user1@email.com" } ] }, "status": "ACTIVE", "contextType": "UNIT", "contextId": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14", "allocations": [] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } }, "delete": { "tags": ["Budgets"], "summary": "Delete budget", "description": "Deletes a specific budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Accept" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "responses": { "200": { "description": "OK\n\nThere is no response body." }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Invalid request parameters." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Cannot delete resource due to existing dependencies." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } }, "/api/budgets/{contextType}/{contextId}/{budgetId}/status": { "put": { "tags": ["Budgets"], "summary": "Update budget status", "description": "Updates the status of a specific budget.\n\n>⚠️ This feature is only available for stores using [B2B Buyer Portal](https://help.vtex.com/docs/tutorials/b2b-buyer-portal), which is currently available to select accounts.\n\n## Permissions\n\nAny user must have the **[Storefront Roles](https://developers.vtex.com/docs/guides/storefront-roles)** resource `ManageBudgets` to be able to successfully run this request.\n\nThe predefined storefront roles that include `ManageBudgets` are **Organizational Unit Admin** and **Budget Manager**. **Budget Manager** is API only.\n\n**[API keys](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)** can call this endpoint and don't require **[License Manager resources](https://help.vtex.com/docs/tutorials/license-manager-resources)**.", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/contextType" }, { "$ref": "#/components/parameters/contextId" }, { "$ref": "#/components/parameters/budgetId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "description": "New status value for the budget (e.g., `ACTIVE` or `INACTIVE`).", "enum": ["ACTIVE", "INACTIVE"] } } }, "example": { "status": "ACTIVE" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The updated budget status (e.g., `ACTIVE` or `INACTIVE`).", "enum": ["ACTIVE", "INACTIVE"] } } }, "example": { "status": "ACTIVE" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Validation error in request body." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Authentication required." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource not found." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "Resource conflict." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseError" }, "example": { "error": "An internal server error occurred." } } } } } } } }, "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": { "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" } }, "contextType": { "name": "contextType", "in": "path", "description": "Type of context for the budget (e.g., `UNIT`). This field can't be updated, it is used for validation. You must send the original value.", "required": true, "schema": { "type": "string", "example": "UNIT" } }, "contextId": { "name": "contextId", "in": "path", "description": "Identifier of the corresponding Unit. This field can't be updated, it is used for validation. You must send the original value.", "required": true, "schema": { "type": "string", "example": "093f29ac-7a1b-4d6b-a79a-48f89cf73d14" } }, "budgetId": { "name": "budgetId", "in": "path", "description": "Identifier of the budget.", "required": true, "schema": { "type": "string", "example": "019833db-27ad-7264-b104-dfed7c0fcbac" } }, "allocationId": { "name": "allocationId", "in": "path", "description": "Identifier of the allocation.", "required": true, "schema": { "type": "string", "example": "324b5750-c827-4a6b-a670-c9297c832f4e" } }, "page": { "name": "page", "in": "query", "description": "Page number of the results.", "required": false, "style": "form", "schema": { "type": "integer", "example": 1 } }, "pageSize": { "name": "pageSize", "in": "query", "description": "Number of items per page.", "required": false, "style": "form", "schema": { "type": "integer", "example": 20 } }, "transactionId": { "name": "transactionId", "in": "path", "description": "Identifier of the transaction.", "required": true, "schema": { "type": "string", "example": "880e8400-e29b-41d4-a716-446655440000" } }, "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "example": "application/json" } }, "reservationId": { "name": "reservationId", "in": "path", "description": "Identifier of the reservation.", "required": true, "schema": { "type": "string", "example": "b0e55425-a981-4d00-b6a2-9c7294d3d2b3" } }, "status": { "name": "status", "in": "query", "description": "Filter by reservation status (e.g., `RESERVED`, `CONFIRMED`, or `CANCELED`).", "required": false, "style": "form", "schema": { "type": "string", "enum": ["RESERVED", "CONFIRMED", "CANCELED"], "example": "RESERVED" } }, "type": { "name": "type", "in": "query", "description": "Filters the allocations by linked entity type. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration)).", "required": false, "style": "form", "schema": { "type": "string", "example": "Location" } }, "allocationStatus": { "name": "status", "in": "query", "description": "Filter allocations by their status. Use `ACTIVE` for current allocations, `INACTIVE` for temporary disabled ones, or `DELETED` for removed allocations.", "required": false, "style": "form", "schema": { "type": "string", "enum": ["ACTIVE", "INACTIVE", "DELETED"], "example": "ACTIVE" } }, "referenceId": { "name": "referenceId", "in": "query", "description": "Filters the allocations by contract ID.", "required": false, "style": "form", "schema": { "type": "string", "example": "4d00d477-e4fe-4345-b5cd-ba2ef1725cc8" } }, "minAmount": { "name": "minAmount", "in": "query", "description": "Minimum budget amount for filtering.", "required": false, "style": "form", "schema": { "type": "number", "format": "float", "example": 100.0 } }, "maxAmount": { "name": "maxAmount", "in": "query", "description": "Maximum budget amount for filtering.", "required": false, "style": "form", "schema": { "type": "number", "format": "float" } }, "budgetStatus": { "name": "status", "in": "query", "description": "Filter budgets by their status. Use `ACTIVE` for enabled budgets or `INACTIVE` for disabled budgets. The status `DELETED` is not applicable for budget filtering: deleted budgets are purged from the system and cannot be retrieved or filtered through the API.", "required": false, "style": "form", "schema": { "type": "string", "enum": ["ACTIVE", "INACTIVE"], "example": "ACTIVE" } }, "budgetName": { "name": "name", "in": "query", "description": "Budget name.", "required": false, "style": "form", "schema": { "type": "string", "example": "North America Q2 Budget" } } }, "schemas": { "responseError": { "type": "object", "description": "Object containing the error message.", "properties": { "error": { "type": "string", "description": "Error message." } } }, "Pagination": { "type": "object", "description": "Pagination information.", "properties": { "current": { "type": "integer", "description": "Current page number." }, "pages": { "type": "integer", "description": "Total number of pages available." }, "results": { "type": "integer", "description": "Total number of results across all pages." } } }, "TransactionResponse": { "type": "object", "description": "Response containing transaction details.", "properties": { "id": { "type": "string", "description": "Identifier of the created transaction." }, "budgetId": { "type": "string", "description": "Identifier of the associated budget." }, "allocationId": { "type": "string", "description": "Identifier of the allocation within the budget." }, "origin": { "type": "string", "description": "Source system or origin of the transaction." }, "reference": { "type": "string", "description": "Reference identifier tied to the transaction." }, "amount": { "type": "number", "description": "Amount committed in the transaction." }, "requestedBy": { "type": "string", "format": "email", "description": "Email of the user who created the transaction." }, "date": { "type": "string", "format": "date-time", "description": "Date and time of the transaction (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "type": { "type": "string", "description": "Condition that defines how the transaction will impact the budget (e.g., `DEBIT` or `CREDIT`). If `type` is `DEBIT`, the amount will be subtracted from the budget. If `type` is `CREDIT`, the amount will be added to the budget.", "enum": ["DEBIT", "CREDIT"] }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier for the context type." } } }, "ReservationResponse": { "type": "object", "description": "Response containing reservation details.", "properties": { "id": { "type": "string", "description": "Identifier of the reservation." }, "budgetId": { "type": "string", "description": "Identifier of the associated budget." }, "allocationId": { "type": "string", "description": "Identifier of the associated allocation." }, "origin": { "type": "string", "description": "The origin of the reservation (e.g., order system)." }, "reference": { "type": "string", "description": "Reference tied to the reservation (e.g., order ID)." }, "amount": { "type": "number", "description": "Amount reserved." }, "requestedBy": { "type": "string", "format": "email", "description": "Email of the user who requested the reservation." }, "date": { "type": "string", "format": "date-time", "description": "Reservation date (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "type": { "type": "string", "description": "Type of transaction (`DEBIT`, meaning a regular transaction or `CREDIT` indicating a refund).", "enum": ["DEBIT", "CREDIT"] }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the corresponding Unit." } } }, "AllocationResponse": { "type": "object", "description": "Response containing allocation details.", "properties": { "id": { "type": "string", "description": "Identifier of the allocation." }, "budgetId": { "type": "string", "description": "Identifier of the budget." }, "linkedEntity": { "type": "object", "description": "Linked entity information.", "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "balance": { "type": "object", "description": "Budget balance information.", "properties": { "amount": { "type": "number", "description": "Total amount in the budget." }, "balanceAdjustment": { "type": "number", "description": "Amount already utilized." }, "remaining": { "type": "number", "description": "Remaining budget." } } }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" }, "status": { "type": "string", "description": "Current status of the allocation (e.g., `ACTIVE` or `INACTIVE`).", "enum": ["ACTIVE", "INACTIVE", "DELETED"] }, "referenceId": { "type": "string", "description": "Identifier of the related entity (e.g., Identifier of a contract)." }, "contractId": { "type": "string", "description": "Identifier of the contract. Alternative field to `referenceId`." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the corresponding Unit." } } }, "NotificationSettings": { "type": "array", "description": "List of thresholds that trigger a notification based on usage. Applies to both Budgets and Allocations.", "items": { "type": "object", "description": "Notification setting.", "properties": { "type": { "type": "string", "description": "Defines whether the threshold is based on percentage of usage or a fixed amount.", "enum": ["PERCENT", "AMOUNT"] }, "threshold": { "type": "number", "description": "The value of the threshold. For `\"PERCENT\"`, 100 means fully used (0 available); values above 100 indicate overuse.", "example": 121 }, "recipients": { "type": "array", "description": "List of recipients to notify.", "items": { "type": "object", "description": "Recipient information.", "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the recipient." } } } } } } }, "NotificationSettingsObject": { "type": "object", "description": "Thresholds that trigger a notification based on usage. Applies to both Budgets and Allocations.", "properties": { "enable": { "type": "boolean", "description": "Enables notifications." }, "thresholds": { "type": "array", "description": "Array of threshold configurations.", "items": { "type": "object", "description": "Threshold configuration.", "properties": { "type": { "type": "string", "description": "Defines whether the threshold is based on percentage of usage or a fixed amount.", "enum": ["PERCENT", "AMOUNT"] }, "Value": { "type": "number", "description": "The value of the threshold. For `\"PERCENT\"`, 100 means fully used (0 available); values above 100 indicate overuse." } } } }, "recipients": { "type": "array", "description": "List of recipients to notify.", "items": { "type": "object", "description": "Recipient information.", "properties": { "type": { "type": "string", "description": "Type of notification." }, "identifier": { "type": "string", "format": "email", "description": "Email identifier to send notifications." } } } } } }, "BudgetResponse": { "type": "object", "description": "Response containing budget details.", "properties": { "id": { "type": "string", "description": "Identifier of the budget." }, "name": { "type": "string", "description": "Name of the budget." }, "description": { "type": "string", "description": "Description of the budget." }, "balance": { "type": "object", "description": "Budget balance information.", "properties": { "amount": { "type": "number", "description": "Total amount in the budget." }, "balanceAdjustment": { "type": "number", "description": "Amount already utilized." }, "remaining": { "type": "number", "description": "Remaining budget." } } }, "cycleConfiguration": { "$ref": "#/components/schemas/CycleConfigurationResponse" }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" }, "status": { "type": "string", "description": "Current status of the budget (e.g., `ACTIVE`, `INACTIVE`).", "enum": ["ACTIVE", "INACTIVE"] }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." }, "allocations": { "type": "array", "description": "Optional list of initial allocations to create with the budget.", "items": { "type": "object", "description": "Allocation object.", "properties": { "id": { "type": "string", "description": "Unique identifier of the allocation." }, "budgetId": { "type": "string", "description": "Identifier of the associated budget." }, "linkedEntity": { "type": "object", "description": "Entity to which the allocation is linked.", "properties": { "id": { "type": "string", "description": "Identifier of the entity linked to the allocation. If `type` is `User` or `Address`, this should be the identifier of the user or address, respectively. If `type` is an Accounting Field ([Custom Field](https://developers.vtex.com/docs/guides/custom-fields-integration)), this should be the **value** of that Accounting Field." }, "type": { "type": "string", "description": "Type of the linked entity. Currently, the accepted entity types are: `User`, `Address`, and Accounting Fields ([Custom Fields](https://developers.vtex.com/docs/guides/custom-fields-integration))." } } }, "balance": { "type": "object", "description": "Financial details of the allocation.", "properties": { "amount": { "type": "number", "description": "Total amount allocated." }, "balanceAdjustment": { "type": "number", "description": "Amount already used from the allocation." }, "remaining": { "type": "number", "description": "Remaining balance." } } }, "notificationSettings": { "$ref": "#/components/schemas/NotificationSettingsObject" }, "status": { "type": "string", "description": "Current status of the allocation (e.g., `ACTIVE`)." }, "referenceId": { "type": "string", "description": "Identifier of the related contract." }, "contextType": { "type": "string", "description": "Defines the context type associated with the budget which must be `UNIT` in B2B context." }, "contextId": { "type": "string", "description": "Identifier of the context type." } } } } } }, "CycleConfiguration": { "type": "object", "description": "Configuration for budget cycle.", "required": [ "startDate", "autoResetOnPeriodEnd", "carryOverBalance" ], "properties": { "startDate": { "type": "string", "format": "date-time", "description": "Start date of the budget cycle (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the budget cycle (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "autoResetOnPeriodEnd": { "type": "boolean", "description": "Enable (`true`) or disable (`false`) the autoreset period." }, "carryOverBalance": { "type": "boolean", "description": "Defines wether to carry over balance (`true`) or not (`false`)." } } }, "CycleConfigurationResponse": { "type": "object", "description": "Configuration for budget cycle in response.", "properties": { "startDate": { "type": "string", "format": "date-time", "description": "Start date of the budget cycle (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the budget cycle (ISO format: YYYY-MM-DDThh:mm:ssZ)." }, "autoResetOnPeriodEnd": { "type": "boolean", "description": "Condition if the period will auto reset when ended." }, "carryOverBalance": { "type": "boolean", "description": "Condition if the remain balance will be transferred to the next cycle." }, "nextRenewal": { "type": "string", "format": "date-time", "description": "Next cycle renewal date (format: YYYY-MM-DDThh:mm:ssZ)." } } } } }, "tags": [ { "name": "Statements" }, { "name": "Transactions" }, { "name": "Reservations" }, { "name": "Allocations" }, { "name": "Budgets" } ] }