Budgets API

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.

The Budgets API is a comprehensive budget management service that allows you to create, manage, and control Budgets, Allocations, Transactions, and Reservations.

Merchants and B2B organizations can manage store expenses using this API, promoting financial transparency, traceability, and control.

This feature is only available for stores using B2B Buyer Portal, which is currently available to select accounts.

Budget and Allocation

Each Budget can have one or more Allocations, which are subdivisions of the total balance within that Budget.

Each 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.

Transactions and Reservations

To move funds from an Allocation, there are two options:

• Direct Transaction
  Used when you want to actually consume the balance. This creates a definitive entry that appears in the Statements (transaction history).

• Reservation
  Used to temporarily reserve funds without consuming them immediately. Later, you can either:

  • Confirm the reservation, which automatically creates a Transaction.

  • Delete the reservation, which simply releases the reserved balance without generating any Transaction (it does not appear in the Statements).

Refunds

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.

Transaction types

When you get a Budget or Allocation statement, each Transaction contains a type field, which can carry two values:

• DEBIT: Regular Transactions, subtracting funds from the Budget or Allocation.

• CREDIT: Associated with Refunds, meaning it adds funds to the Budget or Allocation.

Typical API Call Order

1. Create the Budget.

2. Create one or more Allocations.

3. Perform a Transaction or a Reservation.

4. Retrieve the transaction history using the Statements endpoints.

In a typical purchase flow, we do not use Reservations. We create direct Transactions and use Refunds when needed.

Common parameters in the documentation

Parameter name	Description
{{accountName}}	Name of the VTEX account. Used as part of the URL.
{{environment}}	Environment to use. Used as part of the URL.
{{VtexIdclientAutCookie}}	User token, valid for 24 hours.