The Budgets feature is only available for B2B Buyer Portal. Authorization from the Commerce Engineer of the account is required for usage.

The Budgets API allows buyers to track spending across different parts of your organization by creating budgets and subdividing them into allocations that are attached to specific entities, such as users, addresses, or business accounting fields like cost center or purchase order number.

This integration guide explains how to provision budgets for a given business context, distribute those budgets into allocations, and query allocations at checkout time so your ecommerce and back-office systems can consistently track spending rules. It focuses on the Budget and Allocations endpoints of the Budgets API.

The budget functionality is intended for buyers using the Organization Account interface. Integration is only required when the merchant needs to create budgets on behalf of the buyer, support budget consumption, or implement a headless checkout.

Before integrating with the Budgets API, make sure the following requirements are met.

To use the Budgets API, the integration must have the required License Manager permissions. Without these permissions, all API requests will fail with a 403 Forbidden response.

• ManageBudgets: Required to create, update, delete, and query budgets and allocations.
• ViewBudget: Required for read-only access to budgets.

Assign these permissions to dedicated integration roles rather than shared roles to ensure secure, auditable access.

To use the Budgets API, follow this lifecycle:

1. Create a budget for a B2B unit.
2. Create allocations under that budget, each linked to a specific entity, such as a user, address, cost center, and so on.

   During order processing, Checkout and OMS consume allocations through Transactions or Reservations + Transactions, decreasing available balances.

3. Retrieve statements for audits and reporting, not covered in this guide.

Each budget and allocation has:

• A total amount and remaining balance.
• A validity window defined by start and end dates.
• A status, for example, ACTIVE or INACTIVE, that controls whether it can be used.

Budgets and allocations are always scoped by contextType and contextId, which represent the B2B business context that owns the budget. For B2B scenarios, contextType must be UNIT. Use a stable, unique identifier from your master data as contextId to correlate budgets with your external systems.

A typical end-to-end integration looks as follows:

1. Your Integration Layer or back-office creates or updates budgets and allocations via the Budgets API, on behalf of the buyer.
2. Checkout receives an order, identifies the relevant entities such as cost center, buyer, address, and so on, and calls the Query allocations endpoint to retrieve applicable allocations.
3. Checkout determines how much to deduct from each allocation based on your buyer’s business rules.
4. Checkout sends the selected budgets and allocation IDs to OMS.
5. OMS creates Transactions and Refunds when needed against those allocations.

If you deactivate or delete a budget or allocation that is still referenced by your ERP or checkout integration, queries may stop returning it, and purchases may be blocked unexpectedly.

The budget provisioning flow creates and maintains the main spending envelope for a given business context, such as a B2B unit. A budget defines the total amount available over a period and can include optional initial allocations created in a single call.

Use this flow in the following scenarios:

• Create or synchronize budgets from an external application.
• Change the budget amount, description, or period.
• Activate or deactivate a budget without removing its historical data.

• POST - Create budget
• GET - List budgets
• GET - Get budget
• PUT - Update budget
• PUT - Update budget status
• DELETE - Delete budget

Follow the steps below to create and manage a budget for a given business context (for example, a B2B unit) using the Budgets API.

1. Choose the budget context:

   • Decide which context type and ID will own the budget, for example, contextType = UNIT, contextId = "unit-123". For B2B scenarios, contextType must be UNIT.
   • Ensure the same values are used consistently by all systems that will interact with this budget.

2. Create the budget by calling the POST Create budget endpoint with the required fields:

   • name, description, and amount required.
     • cycleConfiguration start and end dates, auto-reset, carry-over.
     • Optional allocations array if you want to create initial allocations in the same request.

3. Store the budget identifier by saving the returned id and keep it associated with your External Service budget identifier.

4. List and retrieve budgets

   • Use GET List budgets to list budgets for a context with pagination.
   • Use GET Get budget to retrieve full details, including balance and allocations.

5. Update the budget by using the PUT Update budget endpoint to update fields such as name, description, amount, or cycleConfiguration.

6. Control budget availability

   • Use PUT Update budget status to activate or inactivate a budget.
   • Use DELETE Delete budget only when you are sure the budget is no longer required.

The allocation management flow subdivides a budget into one or more allocations, each tied to a specific entity such as a cost center, a user, or a shipping address. Each allocation has its own amount, optional notification settings, and status.

Allocations allow you to define fine-grained spending rules while still tracking the total budget for the broader context.

• To distribute a budget across multiple entities, such as cost centers or projects.
• To adjust the amount, status, or notification rules for existing allocations.

• POST Create allocations batch
• GET List budget allocations
• GET Get allocation
• PUT Update allocation
• DELETE Delete allocation

1. Create allocations for a budget

   • Use POST Create allocations batch.
   • The body contains an allocations array. Each allocation includes:
     • linkedEntity: Linked entity information such as id = "cost-center-001", type = "CostCenter".
     • amount: allocation amount.
     • referenceId: ID of the related resource, such as a contract.
     • Optional notificationSettings.

2. Call the GET List budget allocations endpoint to retrieve allocations with pagination.

3. Call the GET Get allocation endpoint to retrieve full allocation details.

4. Call the PUT Update allocation endpoint to update fields such as amount, referenceId, or notificationSettings.

5. Call the DELETE Delete allocation endpoint to delete an allocation while preserving its history.

The checkout allocation lookup flow allows Checkout or any other consuming system to discover which allocations apply to a given purchase. It uses the Query allocations endpoint to match a combination of entities, such as cost centers, users, or addresses, against existing allocations.

Checkout identifies and groups applicable allocations, while OMS processes transactions and refunds. If configured, Order Authorization can enforce budget rules.

• Determine which budgets and allocations should fund a given order.
• Centralize budget logic in the Budgets API instead of hardcoding it in Checkout or OMS.
• Support complex scenarios where multiple entities determine the applicable budget.

• POST Query allocations

1. Identify the context for the order by determining the contextType and contextId that represent its business context.

2. Identify the relevant entities that influence budget selection, such as user ID, shipping address, and accounting fields like purchase order number or project code, and define for each entity its id and semantic type (for example, User, Address, CostCenter, or PO Number).

3. Call the Query allocations endpoint

   • Use POST Query allocations.

   • The request body contains an items array with all entities to match.

4. Interpret the response by reading the items array returned by the API, which includes budgetId, allocationId, the linkedEntity, and budget and allocation balance information, and decide how much to deduct from each allocation based on its applicability to the order, item, or address.

5. Pass the result to OMS by including the selected budgetId and allocationId values in the order so that OMS can create transactions.