API reference

Budget control

Whether orders and requests are checked against cost center budgets, and where each budget stands.

More about this resource

A buyer workspace can check each purchase order and purchase request against its cost center's budget for the current month, quarter or year. In warn mode an order over budget goes ahead with a warning; in block mode it is refused with 409 over_budget. Committed spend is approved orders that aren't invoiced yet, and actual spend is approved invoices. The budgets themselves are set per cost center in Pleaxy.

Get budget control

Gets whether budgets are checked, and over what period.

GET/v1/workspaces/{regionId}/budget-control

Returns

200 OK with the object shown in the response.

More details

Returns the workspace's budget control setting: off, warn or block, and the period budgets cover.

Any member of the buyer workspace, whatever their procurement role.

Response fields

  • mode"off" | "warn" | "block"

    off: budgets aren't checked. warn: an order or request over its cost center's budget goes ahead with a warning. block: it is refused with 409 over_budget.

  • period"month" | "quarter" | "year"

    The period a budget covers and spend is counted over.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/budget-control
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Update budget control

Changes whether budgets are checked, and over what period.

PATCH/v1/workspaces/{regionId}/budget-control

Body

  • mode"off" | "warn" | "block"

    Optional. Whether budgets are checked, and whether going over warns or blocks.

  • period"month" | "quarter" | "year"

    Optional. The period a budget covers.

Returns

200 OK with the object shown in the response.

More details

Changes the budget control setting. It applies to orders and requests submitted or approved from then on.

Signed-in session only, with 'edit' access to approval settings or to invoices. An API key gets 403 HUMAN_SESSION_REQUIRED.

Response fields

  • mode"off" | "warn" | "block"

    off: budgets aren't checked. warn: an order or request over its cost center's budget goes ahead with a warning. block: it is refused with 409 over_budget.

  • period"month" | "quarter" | "year"

    The period a budget covers and spend is counted over.

Errors

  • 400 Bad Request - mode or period isn't one of the listed values.
  • 403 Forbidden - Code HUMAN_SESSION_REQUIRED. The caller isn't a signed-in person (for example, an API key). Nothing is saved.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
PATCH /v1/workspaces/{regionId}/budget-control
Request
curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year"
}
Response · 200 OK
{
   "mode": "off" | "warn" | "block",
   "period": "month" | "quarter" | "year",
   "updatedAt": "string",
   "updatedBy": "string"
}

Get budget status

Gets budget, committed, actual and remaining spend per cost center.

GET/v1/workspaces/{regionId}/budget-control/status

Parameters

  • costCenterstring

    Only this cost center. Every budgeted cost center when absent.

  • datestring

    A day (YYYY-MM-DD) in the period to report. Today when absent.

Returns

200 OK with the object shown in the response.

More details

Returns, for the current period, each budgeted cost center's budget, committed spend (approved orders not yet invoiced), actual spend (approved invoices) and what remains. Spend with no cost center is reported apart, as unassigned.

Needs 'view' access to purchase orders.

Response fields

  • costCenters[].committednumber

    Approved purchase orders, less what has already been invoiced against them.

  • costCenters[].actualnumber

    Approved invoices in the period.

  • costCenters[].remainingnumber

    The budget less committed and actual spend.

  • costCenters[].pendingnumber

    Spend still waiting for approval. It doesn't reduce remaining.

  • costCenters[].unconvertednumber

    Always 0, kept for older clients.

  • unassignedobject

    The period's spend that names no cost center, in the workspace's currency; unassignedByCurrency has one entry per currency.

Errors

  • 400 Bad Request - date isn't a day written as YYYY-MM-DD.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/budget-control/status
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/budget-control/status" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "settings": {
      "mode": "off" | "warn" | "block",
      "period": "month" | "quarter" | "year",
      "updatedAt": "string",
      "updatedBy": "string"
   },
   "period": { "kind": "month" | "quarter" | "year", "start": "string", "end": "string", "fiscalYear": number },
   "currency": "string",
   "costCenters": [
      {
         "costCenter": "string",
         "costCenterName": "string",
         "period": { "kind": "month" | "quarter" | "year", "start": "string", "end": "string" },
         "currency": "string",
         "budget": number,
         "committed": number,
         "actual": number,
         "remaining": number,
         "pending": number,
         "unconverted": number
      }
   ],
   "unassigned": { "committed": number, "actual": number, "pending": number, "unconverted": number },
   "unassignedByCurrency": [ { "currency": "string", "committed": number, "actual": number, "pending": number, "unconverted": number } ]
}

Check budget

Previews the budget check for an amount on a cost center.

POST/v1/workspaces/{regionId}/budget-control/check

Body

  • amountnumberRequired

    The amount to check.

  • currencystringRequired

    The amount's currency code.

  • costCenterstring

    The cost center the amount would be booked to.

  • excludeOrderIdstring

    A purchase order to leave out of committed spend, when checking a change to that order.

  • blanketboolean

    true: check as a blanket order, which reserves expectedMonthly for each month of the period up to validUntil.

  • expectedMonthlynumber

    With blanket: what the order is expected to spend each month.

  • validUntilstring

    With blanket: the order's last day (YYYY-MM-DD).

Returns

200 OK with the object shown in the response.

More details

Says what the budget check would answer for an amount on a cost center, against that cost center's budget in the amount's currency. It writes nothing and never refuses: an amount over budget comes back as outcome over, with 200.

Any member of the buyer workspace, whatever their procurement role.

Response fields

  • outcomestring

    within: the amount fits the budget. over: it exceeds what remains, by overBy. no_budget: the cost center has no budget in this currency. no_rate: there's no exchange rate to check it. off: budgets aren't checked.

Errors

  • 400 Bad Request - amount or currency is missing or invalid.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/budget-control/check
Request
POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/budget-control/check
{
   "costCenter": "CC-1000",
   "amount": 12000,
   "currency": "USD"
}
Response · 200 OK
{
   "outcome": "over",
   "mode": "warn",
   "period": { "kind": "quarter", "start": "2026-10-01", "end": "2026-12-31" },
   "costCenter": "CC-1000",
   "currency": "USD",
   "budget": 50000,
   "committed": 31000,
   "actual": 10500,
   "remaining": 8500,
   "amount": 12000,
   "overBy": 3500,
   "checkedAt": "2026-11-11T15:04:05.000Z"
}
Talk to us