Skip to main content

How to create and manage budgets via the OpenAPI

  • Updated

Create, update, and delete budgets through the Weel OpenAPI so they stay in sync with events in your ERP, HR system, or budget cycle.

Before you start

You will need:

  • A Weel Enterprise plan, with Owner or Admin access, or the API permission enabled for your role.
  • An API key. See How to generate and manage API keys.
  • Your Client ID, shown on the Settings > API page in the Weel web app.

Include your API key as a bearer token in the Authorization header of every request. The full endpoint reference is at developer.letsweel.com.

Steps

1. Create a budget

Send POST /v1/businesses/{client_id}/budgets. Every configuration field is required; there are no silent defaults:

  • name: the budget's name.
  • reset_amount and reset_period: the amount the budget resets to each period.
  • has_member_limits: when true, each member gets their own cap and the member caps must add up to the budget's reset_amount (the API validates this and rejects a mismatch). When false, members share the budget's pot and no member can carry an individual reset_amount.
  • rollover_funds: whether unspent balance rolls over to the next period.
  • members and owners: at least one of each. You can't create a budget with zero members or zero owners.

Optional fields:

  • limit_categories plus categories: restrict which categories are visible on the budget. Each entry in categories is an object referencing a category by id, not a bare ID string.
  • custom_fields: attach custom fields to the budget.
  • payment_types: restrict which payment types (for example, cards) are enabled on the budget from creation, the same setting covered in How to limit payment types on a budget. If omitted, all payment types are available on the new budget.

2. Update or delete a budget

  • Update configuration with PATCH /v1/businesses/{client_id}/budgets/{budget_id}. This endpoint doesn't accept members or owners; manage those through the nested endpoints in step 3. It also can't be used on an archived budget, or on a subscription or default-charge-card budget (these return an error).
  • Delete with DELETE /v1/businesses/{client_id}/budgets/{budget_id}. This also removes the budget's members and owners.

3. Manage members and owners

  • Add, update, or remove members with POST /budgets/{budget_id}/members, PATCH .../members/{budget_member_id}, and DELETE .../members/{budget_member_id}. A budget must always keep at least one member; removing the last one is rejected.
  • Add or remove Budget Owners with POST /budgets/{budget_id}/owners and DELETE .../owners/{budget_owner_id} (there's no PATCH for owners; to change an owner, remove and re-add). A budget must always keep at least one owner; removing the last one is rejected the same way.

4. Top up a budget

  • Top up the budget's shared pot with POST /budgets/{budget_id}/topups.
  • Top up an individual member with POST /budgets/{budget_id}/members/{budget_member_id}/topups.
  • Both accept an optional auto_approve flag that immediately approves and actions the top-up instead of leaving it pending. Top-ups made through the OpenAPI are always one-off increases to the current period. There's no option to permanently raise a budget's reset_amount through this endpoint; use the update-budget call in step 2 instead.

What happens next

The budget appears on the Budgets page in Weel immediately; there's no separate activation step. A member who already has an active Weel card can spend from the budget with that card straight away. If you add a member who doesn't have a card yet (for example, someone still going through onboarding), they'll need their card issued through the normal onboarding flow first; adding them to a budget via the API doesn't itself trigger card issuance.

Wire the calls to your source system to keep budgets in step with your business.

Related Articles