Skip to content
XOS Developers

Create a budget line

Finance module

POST/budget-linesbudgetLines.create

A budget line. A blank unit price is unpriced; zero is a claim. Fee and Contingency are line types. Creates a budget line. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

  • Requires the capability finance.budget.write.
  • OAuth scopes: finance.
  • Send an Idempotency-Key header. A replay with the same key returns the original response.
  • Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: BudgetLineCreate

budgetLines.create: BudgetLineCreate
FieldTypeRequiredDescription
budget_idstring (uuid)YesIdentifier of the budget.
cost_center_idstring (uuid) | nullNoIdentifier of the cost center.
uridUridAtAnyGrainYesURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzYesXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Constraints: pattern ^[XYZ]$
xyz_basisstringYesBasis for the XYZ tag.Constraints: length 1 to 300
line_typeLineTypeNoBudget line type from the budget template specification (Bible tab 34). Fee and Contingency are line types, not accounts.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
grade_codestring | nullNoPrice band grade of the catalog element.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
element_idItemIdNoCatalog item identifier `{URID}-{ORG}-{SEQ}` (Section 3.6).Constraints: pattern ^[0-9]000\.[0-9]{2}\.[0-9]{2}-[A-Z0-9]+-[0-9]+$
descriptionstringYesLine description.Constraints: length 1 to 300
quantitynumberNoQuantity; defaults to 1.
unit_basisUnitCodeNoUnit basis from the controlled unit list in `xpms.dim_unit_alias`.Constraints: pattern ^[a-z][a-z0-9_-]*$
unit_price_minorinteger (int64) | nullNoUnit price. Integer minor units of the resource currency; null means unpriced, never zero.
line_numberintegerYesLine number within the budget.Constraints: range 1 to any
phase_codePhaseCode | nullNo
tier_codeTierCode | nullNo
{
  "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "urid": "4000.01",
  "xyz": "X",
  "xyz_basis": "Rented inventory",
  "grade_code": "base",
  "description": "Stage deck rental",
  "quantity": 24,
  "unit_price_minor": 4500,
  "line_number": 1
}

Response 201: BudgetLine

budgetLines.create: BudgetLine
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the budget line.
org_idstring (uuid)YesIdentifier of the owning organization, derived from the parent row and never accepted from the caller.
created_atstring (date-time)YesWhen the row was created.
created_bystring (uuid) | nullYesIdentifier of the person who created the row; null when a seed, platform or system process created it.
updated_atstring (date-time)YesWhen the row was last updated.
updated_bystring (uuid) | nullYesIdentifier of the person who last updated the row; null when a seed, platform or system process updated it.
budget_idstring (uuid)YesIdentifier of the budget.
cost_center_idstring (uuid) | nullYesIdentifier of the cost center.
uridUridAtAnyGrainYesURID at discipline grain (`DDDD.DD`) or category grain (`DDDD.DD.DD`), as GL dimension 2 allows.Constraints: pattern ^[0-9]000(\.[0-9]{2}){1,2}$
xyzXyzYesXYZ schema-family tag (Section 3.6): X Resource, Y Process, Z Timeline.Constraints: pattern ^[XYZ]$
xyz_basisstringYesBasis for the XYZ tag.Constraints: length 1 to 300
line_typeLineTypeYesBudget line type from the budget template specification (Bible tab 34). Fee and Contingency are line types, not accounts.Constraints: pattern ^[A-Z0-9][A-Za-z0-9&'/.()-]*( [A-Za-z0-9&'/.()-]+)*$
grade_codestring | nullYesPrice band grade of the catalog element.Constraints: pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
element_idItemIdYesCatalog item identifier `{URID}-{ORG}-{SEQ}` (Section 3.6).Constraints: pattern ^[0-9]000\.[0-9]{2}\.[0-9]{2}-[A-Z0-9]+-[0-9]+$
descriptionstringYesLine description.Constraints: length 1 to 300
quantitynumberYesQuantity; defaults to 1.
unit_basisUnitCodeYesUnit basis from the controlled unit list in `xpms.dim_unit_alias`.Constraints: pattern ^[a-z][a-z0-9_-]*$
unit_price_minorinteger (int64) | nullYesUnit price. Integer minor units of the resource currency; null means unpriced, never zero.
line_total_minorinteger (int64) | nullYesLine total, generated from quantity and unit price. Integer minor units of the resource currency; null means unpriced, never zero.
line_numberintegerYesLine number within the budget.Constraints: range 1 to any
phase_codePhaseCode | nullYes
tier_codeTierCode | nullYes
actual_minorinteger (int64) | nullYesApproved and paid expenses posted to the line (app.budget_line_facts); null when unpriced. Integer minor units of the resource currency; null means unpriced, never zero.
account_codeGlAccountCode | nullYes
{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "urid": "4000.01",
  "xyz": "X",
  "xyz_basis": "Rented inventory",
  "line_type": "Contingency",
  "grade_code": "base",
  "element_id": "4000.01.01-XPMS-001",
  "description": "Stage deck rental",
  "quantity": 24,
  "unit_basis": "each",
  "unit_price_minor": 4500,
  "line_total_minor": 108000,
  "line_number": 1,
  "phase_code": "SCP",
  "tier_code": "04",
  "actual_minor": 480000,
  "account_code": "5400"
}

Code samples

curl -X POST "$XOS_BASE_URL/budget-lines" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"budget_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","cost_center_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","urid":"4000.01","xyz":"X","xyz_basis":"Rented inventory","grade_code":"base","description":"Stage deck rental","quantity":24,"unit_price_minor":4500,"line_number":1}'
const { data } = await xos.budgetLines.create({
    "budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "urid": "4000.01",
    "xyz": "X",
    "xyz_basis": "Rented inventory",
    "grade_code": "base",
    "description": "Stage deck rental",
    "quantity": 24,
    "unit_price_minor": 4500,
    "line_number": 1
  });
response = xos.budget_lines.create({"budget_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "cost_center_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "urid": "4000.01", "xyz": "X", "xyz_basis": "Rented inventory", "grade_code": "base", "description": "Stage deck rental", "quantity": 24, "unit_price_minor": 4500, "line_number": 1})
xos budget-lines create --data '{"budget_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","cost_center_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","urid":"4000.01","xyz":"X","xyz_basis":"Rented inventory","grade_code":"base","description":"Stage deck rental","quantity":24,"unit_price_minor":4500,"line_number":1}'