Update Benefit

Update Benefit

Use this endpoint to update the description and/or effective date of an existing benefit. Only the fields you provide are updated — the benefit type cannot be changed.

Key Points

• Depends on — a benefit_id from POST /benefits or GET /benefits.
• description is required. You must always include a description even when you only want to update effective_date.
• Partial update — effective_date is optional. If omitted, the existing effective date is preserved.

PATCH benefits/{benefit_id} 

Header Parameters

Field	Type	Description
Authorization	string	Required. Bearer token obtained from the Auth endpoint. Format: Bearer <access_token>.
X-TaxBandits-Version	string	API version string. Use 1.0.0.

Query Parameters

Field	Type	Description
entity_ids	string	The organization ID. Must be exactly one UUID.

Path Parameters

Field	Type	Description
benefit_id	string	The benefit UUID from the create or list endpoints.

Request Body

Field	Type	Description
description	string	Required. New description. 1-75 characters. Must contain at least one letter. Special characters < > ; { } [ ] _ \ ! : ? = are not allowed.
effective_date	string	Optional New effective date (YYYY-MM-DD). If omitted, the existing date is preserved.

Response Body

Field	Type	Description
status	string	SUCCESS or FAILURE.
status_code	number	HTTP-style status code (e.g. 200, 400).
message	string	Human-readable status message.
response	object	The full updated benefit (same shape as GET /benefits/{benefit_id}).
benefit_id	string	Benefit UUID.
type	string	The benefit type value (unchanged).
description	string	The updated description.
frequency	string	Deduction frequency (e.g. every_paycheck).
effective_date	string	The updated effective date (YYYY-MM-DD).

Payload

Request Json

Sample	Description	Action
Sample 1	Update the description and effective date of a benefit.

Sample 1

{
  "description": "Updated 401k Plan Name",
  "effective_date": "2025-06-01"
}

Response Json

Sample	Description	Action
200	Success Response - This is a sample response for successful API requests.
400	Bad Request Response - You'll get the below response when the request body fails validation.
404	Not Found Response - You'll get the below response when no benefit matches the supplied benefit_id.

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": {
    "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
    "type": "401k",
    "description": "Updated 401k Plan Name",
    "frequency": "every_paycheck",
    "effective_date": "2025-06-01"
  }
}