Create or update a category / subcategory policy

Reference

Create or update a category / subcategory policy

Request

🔒 Private label — contact sales. Requires a private-label entitlement on your API client.

Upserts a business policy under the SUBCATEGORY or CATEGORY policy group.

Without _id: initializes a new policy then applies the full payload in one call.
With _id: updates the existing policy directly.

The policy group is resolved automatically from the type query param.

Security

oauth2ClientCredentials(Required scopes: business-policies:write)

Query

typestringrequired

Policy group to operate under. Case-insensitive.

Enum:"subcategory""category"

business_idstringrequired

Business identifier for the request

Bodyapplication/jsonrequired

_idstring

Business policy MongoDB ObjectId. When present the policy is updated; omit to create.

Example:"6a3ebb7893bb2649e19cb8a6"

namestringrequired

Human-readable name for the policy

Example:"Company Travel spend limits"

typestringrequired

Target scope of the policy: business | team | employee

Example:"business"

statusstring

Policy status. INACTIVE is accepted as an alias for DISABLED.

Enum:"ACTIVE""DISABLED""INACTIVE""DELETED"

Example:"ACTIVE"

descriptionstring

Optional description

prioritynumber

Priority order (lower = higher priority)

Example:1

workflowobject or null

Approval workflow ID or null

employeesArray of strings

Employee IDs scoped to this policy

teamsArray of strings

Team IDs scoped to this policy

budgetsArray of strings

Budget IDs scoped to this policy

rulesArray of objects(PolicyRuleV1Dto)

Rules defining conditions and actions of this policy

require_tax_compliant_receiptboolean

Whether tax-compliant receipts are required

curl -i -X PUT \
  'https://developer.boyahq.com/_mock/v2/openapi/business-policies/category-policies?type=subcategory' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'business_id: string' \
  -d '{
    "_id": "6a3ebb7893bb2649e19cb8a6",
    "name": "Company Travel spend limits",
    "type": "business",
    "status": "ACTIVE",
    "description": "string",
    "priority": 1,
    "workflow": {},
    "employees": [
      "string"
    ],
    "teams": [
      "string"
    ],
    "budgets": [
      "string"
    ],
    "rules": [
      {
        "conditions": [
          {
            "field": "string",
            "operator": "string",
            "value": {},
            "value_id": "string"
          }
        ],
        "action": "string",
        "period_unit": "TRANSACTION",
        "period": 0,
        "kick_off_date": "string",
        "target": "string",
        "target_employees": [
          "string"
        ],
        "exempt_employees": [
          "string"
        ],
        "target_teams": [
          "string"
        ],
        "exempt_teams": [
          "string"
        ],
        "target_sub_categories": [
          "string"
        ],
        "exempt_sub_categories": [
          "string"
        ],
        "target_channels": [
          "string"
        ],
        "target_roles": [
          "string"
        ],
        "require_tax_compliant_receipt": true,
        "funding_source_strategy": "string",
        "exempt_wallet_types": [
          "string"
        ]
      }
    ],
    "require_tax_compliant_receipt": true
  }'

Responses

Business policy created or updated successfully

Bodyapplication/json

_idstring

Business policy MongoDB ObjectId

statusstring

Policy status

Enum:"ACTIVE""DISABLED""DELETED"

policyobject(PolicyRefV1Dto)

Parent policy group — either a MongoDB ObjectId string or an expanded PolicyRefV1Dto object

businessstring

Business MongoDB ObjectId this policy belongs to

policy_typestring

Policy scope (e.g. business, budget)

policy_codestring

Policy code inherited from the parent policy group

employeesArray of strings

Employee IDs this policy is scoped to

teamsArray of strings

Team IDs this policy is scoped to

budgetsArray of strings

Budget IDs this policy is scoped to

prioritynumber

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

workflowobject or null

Approval workflow attached to this policy — null when no approval is required

rulesArray of objects(PolicyRuleV1Dto)

Rules defining the conditions and actions of this policy

namestring

Human-readable name for this business policy

descriptionstring

Optional description for this business policy

createdAtstring

ISO 8601 creation timestamp

updatedAtstring

ISO 8601 last-updated timestamp

Response

{
  "_id": "string",
  "status": "ACTIVE",
  "policy": {
    "_id": "string",
    "status": "ACTIVE",
    "description": "string",
    "policy_code": "string"
  },
  "business": "string",
  "policy_type": "string",
  "policy_code": "string",
  "employees": [
    "string"
  ],
  "teams": [
    "string"
  ],
  "budgets": [
    "string"
  ],
  "priority": 0,
  "workflow": {},
  "rules": [
    { … }
  ],
  "name": "string",
  "description": "string",
  "createdAt": "string",
  "updatedAt": "string"
}