# Update a business policy

> 🔒 **Private label — [contact sales](mailto:sales@boyahq.com).** Requires a private-label entitlement on your API client.

Updates rules, workflow, status, or other fields of an existing business policy. Pass status: "DISABLED" to disable the policy.

Endpoint: PUT /business-policies/{businessPolicyId}
Version: 2.0.0
Security: oauth2ClientCredentials

## Path parameters:

  - `businessPolicyId` (string, required)
    Business policy document ID

## Header parameters:

  - `business_id` (string, required)
    Business identifier for the request

## Request fields (application/json):

  - `_id` (string)
    Business policy MongoDB ObjectId
    Example: 6a3ebb7893bb2649e19cb8a6

  - `status` (string)
    Policy status
    Enum: "ACTIVE", "DISABLED", "INACTIVE", "DELETED"

  - `policy` (string)
    Parent policy group ID or object
    Example: 66788b3e2805e9ffbda6dcf7

  - `business` (string)
    Business MongoDB ObjectId
    Example: 631b067a46830ae81217f860

  - `policy_type` (string)
    Policy scope type (e.g. business, budget)
    Example: business

  - `employees` (array)
    Employee IDs this policy is scoped to

  - `teams` (array)
    Team IDs this policy is scoped to

  - `budgets` (array)
    Budget IDs this policy is scoped to

  - `priority` (number)
    Priority order among policies of the same type
    Example: 1

  - `workflow` (object)
    Approval workflow ID or null when no approval is required
    Example: 6a3e6c5387ee44d7d52a3092

  - `rules` (array)
    Rules defining the conditions and actions of this policy

  - `rules.conditions` (array)
    Conditions that must be met for this rule to apply

  - `rules.conditions.field` (string)
    Field the condition applies to (e.g. amount, channel, subcategory)

  - `rules.conditions.operator` (string)
    Comparison operator (e.g. greater_than, equal, less_than)

  - `rules.conditions.value` (object)
    Value to compare against

  - `rules.conditions.value_id` (string)
    MongoDB ObjectId of the referenced value (e.g. subcategory ID)

  - `rules.action` (string)
    Action to take when conditions are met (e.g. allow, block, request_approval, require_receipt)

  - `rules.period_unit` (string)
    Time unit for the spending period. TRANSACTION = per-payment limit; HOUR/DAY/WEEK/MONTH/YEAR = cumulative window
    Enum: "TRANSACTION", "HOUR", "DAY", "WEEK", "MONTH", "YEAR"

  - `rules.period` (number)
    Number of period units for the spending limit window. Use 0 when period_unit is TRANSACTION
    Example: 0

  - `rules.kick_off_date` (string)
    ISO 8601 date when the rule becomes active

  - `rules.target` (string)
    Who this rule targets (e.g. everyone)

  - `rules.target_employees` (array)
    Specific employee IDs this rule targets

  - `rules.exempt_employees` (array)
    Employee IDs exempt from this rule

  - `rules.target_teams` (array)
    Team IDs this rule targets

  - `rules.exempt_teams` (array)
    Team IDs exempt from this rule

  - `rules.target_sub_categories` (array)
    Subcategories this rule targets

  - `rules.exempt_sub_categories` (array)
    Subcategories exempt from this rule

  - `rules.target_channels` (array)
    Payment channels this rule targets (e.g. mpesa, bills, tills)

  - `rules.target_roles` (array)
    Employee roles this rule targets

  - `rules.require_tax_compliant_receipt` (boolean)
    Whether a tax-compliant receipt is required

  - `rules.funding_source_strategy` (string)
    Funding source strategy (e.g. business_wallet, initiator_wallet)

  - `rules.exempt_wallet_types` (array)
    Wallet types exempt from this rule

  - `name` (string)
    Human-readable name for the policy
    Example: Test

  - `description` (string)
    Optional description for the policy
    Example: test

  - `require_tax_compliant_receipt` (boolean)
    Whether tax-compliant receipts are required (legacy top-level field)

## Response 200 fields (application/json):

  - `_id` (string)
    Business policy MongoDB ObjectId

  - `status` (string)
    Policy status
    Enum: "ACTIVE", "DISABLED", "DELETED"

  - `policy` (object)
    Parent policy group — either a MongoDB ObjectId string or an expanded PolicyRefV1Dto object

  - `policy._id` (string)
    Policy group MongoDB ObjectId

  - `policy.status` (string)
    Policy status
    Enum: "ACTIVE", "DISABLED", "DELETED"

  - `policy.description` (string)
    Human-readable description of the policy type

  - `policy.policy_code` (string)
    Policy code identifier (e.g. SUBCATEGORY, CHANNELS, VENDORS)

  - `business` (string)
    Business MongoDB ObjectId this policy belongs to

  - `policy_type` (string)
    Policy scope (e.g. business, budget)

  - `policy_code` (string)
    Policy code inherited from the parent policy group

  - `employees` (array)
    Employee IDs this policy is scoped to

  - `teams` (array)
    Team IDs this policy is scoped to

  - `budgets` (array)
    Budget IDs this policy is scoped to

  - `priority` (number)
    Priority order among policies of the same type (lower = higher priority)

  - `workflow` (object)
    Approval workflow attached to this policy — null when no approval is required

  - `rules` (array)
    Rules defining the conditions and actions of this policy

  - `rules.conditions` (array)
    Conditions that must be met for this rule to apply

  - `rules.conditions.field` (string)
    Field the condition applies to (e.g. amount, channel, subcategory)

  - `rules.conditions.operator` (string)
    Comparison operator (e.g. greater_than, equal, less_than)

  - `rules.conditions.value` (object)
    Value to compare against

  - `rules.conditions.value_id` (string)
    MongoDB ObjectId of the referenced value (e.g. subcategory ID)

  - `rules.action` (string)
    Action to take when conditions are met (e.g. allow, block, request_approval, require_receipt)

  - `rules.period_unit` (string)
    Time unit for the spending period. TRANSACTION = per-payment limit; HOUR/DAY/WEEK/MONTH/YEAR = cumulative window
    Enum: "TRANSACTION", "HOUR", "DAY", "WEEK", "MONTH", "YEAR"

  - `rules.period` (number)
    Number of period units for the spending limit window. Use 0 when period_unit is TRANSACTION
    Example: 0

  - `rules.kick_off_date` (string)
    ISO 8601 date when the rule becomes active

  - `rules.target` (string)
    Who this rule targets (e.g. everyone)

  - `rules.target_employees` (array)
    Specific employee IDs this rule targets

  - `rules.exempt_employees` (array)
    Employee IDs exempt from this rule

  - `rules.target_teams` (array)
    Team IDs this rule targets

  - `rules.exempt_teams` (array)
    Team IDs exempt from this rule

  - `rules.target_sub_categories` (array)
    Subcategories this rule targets

  - `rules.exempt_sub_categories` (array)
    Subcategories exempt from this rule

  - `rules.target_channels` (array)
    Payment channels this rule targets (e.g. mpesa, bills, tills)

  - `rules.target_roles` (array)
    Employee roles this rule targets

  - `rules.require_tax_compliant_receipt` (boolean)
    Whether a tax-compliant receipt is required

  - `rules.funding_source_strategy` (string)
    Funding source strategy (e.g. business_wallet, initiator_wallet)

  - `rules.exempt_wallet_types` (array)
    Wallet types exempt from this rule

  - `name` (string)
    Human-readable name for this business policy

  - `description` (string)
    Optional description for this business policy

  - `createdAt` (string)
    ISO 8601 creation timestamp

  - `updatedAt` (string)
    ISO 8601 last-updated timestamp