> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Garnishment

> Transitions a garnishment lifecycle status: modify (supersede), cancel, or vacate.

Garnishment details are append-only. Every `PATCH` is a lifecycle transition keyed on `status`. Only `active` garnishments can be updated.

### Modify (`status: "modified"`)

Supersedes the existing record with a new linked garnishment. This is the only way to change withholding terms or display fields. Send a partial `modification` object — omitted fields are inherited from the superseded record. Optional fields accept `null` to clear them on the replacement. Simple caps (`cap_amount` / `cap_percentage`) and `withholding_schedule` are mutually exclusive: sending a non-null value on one mode clears the omitted opposite mode, so a mode switch does not need to null the other side. Sending both modes together is rejected. When you send a `withholding_schedule`, the garnishment must be for an employee (contractors have no pay frequency; use simple caps instead). The schedule must tile `$0.00` to infinity per pay frequency with no gaps or overlaps, and at least one bracket must withhold. It does not need to cover every pay frequency — include only the frequencies the order specifies; a payment whose pay frequency is not listed withholds nothing. The resulting record must still have at least one withholding rule. The response is the **new** active garnishment with `previous_garnishmentID` set to the superseded record's ID; amount already withheld is carried forward.

### Cancel (`status: "canceled"`)

Closes the garnishment in place. Requires `canceled_reason` (for mistakes, duplicates, bad worker match, or other non-legal cancellation).

### Vacate (`status: "vacated"`)

Closes the garnishment in place when the court/order was withdrawn or overturned.


## OpenAPI

````yaml openapi/zeal-api.json patch /garnishments/{garnishmentID}
openapi: 3.1.0
info:
  title: zeal-api
  version: '1.0'
servers:
  - url: https://api.zeal.com
security:
  - sec0: []
paths:
  /garnishments/{garnishmentID}:
    patch:
      summary: Update Garnishment
      description: >-
        Transitions a garnishment lifecycle status. Details are append-only: use
        status modified with a modification payload to supersede terms; use
        canceled or vacated to close an active garnishment in place. Simple caps
        and withholding_schedule are mutually exclusive: sending a non-null
        value on one mode clears the omitted opposite mode. Sending both modes
        together is rejected. When modification.withholding_schedule is set, the
        garnishment must be for an employee (contractors have no pay frequency;
        use simple caps instead). It must tile $0.00 to infinity per pay
        frequency with no gaps or overlaps, and at least one bracket must
        withhold. It does not need to cover every pay frequency; a payment whose
        pay frequency is not listed withholds nothing.
      operationId: update-garnishment
      parameters:
        - name: garnishmentID
          in: path
          required: true
          schema:
            type: string
          description: Garnishment ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: Modify
                  type: object
                  required:
                    - companyID
                    - status
                    - modification
                  properties:
                    companyID:
                      type: string
                      description: Company ID of employer
                    status:
                      type: string
                      enum:
                        - modified
                      description: Must be modified
                    modification:
                      type: object
                      description: >-
                        Partial overrides for the replacement garnishment.
                        Omitted fields are inherited from the superseded record.
                        Simple caps (cap_amount / cap_percentage) and
                        withholding_schedule are mutually exclusive: sending a
                        non-null value on one mode clears the omitted opposite
                        mode, so a mode switch does not need to null the other
                        side. Sending both modes together is rejected. When
                        withholding_schedule is set, the garnishment must be for
                        an employee (contractors have no pay frequency; use
                        simple caps instead). Every frequency branch must tile
                        $0.00 to infinity with no gaps or overlaps, and at least
                        one bracket must withhold. The schedule does not need to
                        cover every pay frequency; a payment whose pay frequency
                        is not listed withholds nothing.
                      properties:
                        garnishment_type:
                          type: string
                          enum:
                            - child_support
                            - federal_tax_levy
                            - state_tax_levy
                            - creditor
                            - student_loan
                            - other
                          description: >-
                            Override garnishment type. Omit to inherit from the
                            superseded record.
                        effective_start_date:
                          type: string
                          description: Override effective start date. Omit to inherit.
                        effective_end_date:
                          type: string
                          nullable: true
                          description: >-
                            Override effective end date. Pass null to clear.
                            Omit to inherit.
                        priority:
                          type: integer
                          nullable: true
                          minimum: 0
                          description: >-
                            Override priority. Pass null to clear. Omit to
                            inherit.
                        total_amount_owed:
                          type: number
                          nullable: true
                          minimum: 0
                          description: >-
                            Override total amount owed. Pass null to clear. Omit
                            to inherit. Must be >= amount already withheld.
                        cap_amount:
                          type: number
                          nullable: true
                          minimum: 0
                          description: >-
                            Override per-paycheck cap amount in dollars. Pass
                            null to clear. Omit to inherit, unless a non-null
                            withholding_schedule is sent (that mode switch
                            clears omitted simple caps). Mutually exclusive with
                            withholding_schedule; do not send both. Resulting
                            record must still have cap_amount, cap_percentage,
                            or withholding_schedule.
                        cap_percentage:
                          type: number
                          nullable: true
                          minimum: 0
                          maximum: 100
                          description: >-
                            Override per-paycheck cap percentage (0-100). Pass
                            null to clear. Omit to inherit, unless a non-null
                            withholding_schedule is sent (that mode switch
                            clears omitted simple caps). Mutually exclusive with
                            withholding_schedule; do not send both.
                        garnishment_state:
                          type: string
                          nullable: true
                          description: >-
                            Override state code. Pass null to clear. Omit to
                            inherit.
                        agency_name:
                          type: string
                          description: Override agency name. Omit to inherit.
                        agency_address:
                          type: string
                          description: Override agency address. Omit to inherit.
                        case_id:
                          type: string
                          description: Override case ID. Omit to inherit.
                        order_number:
                          type: string
                          description: Override order number. Omit to inherit.
                        custom_name:
                          type: string
                          nullable: true
                          description: >-
                            Override custom name. Pass null to clear. Omit to
                            inherit.
                        external_id:
                          type: string
                          nullable: true
                          description: >-
                            Override external ID. Pass null to clear. Omit to
                            inherit.
                        withholding_schedule:
                          allOf:
                            - $ref: '#/components/schemas/WithholdingSchedule'
                          nullable: true
                          description: >-
                            Override withholding schedule. Employee-only:
                            contractors have no pay frequency, so a schedule on
                            a contractor is rejected — use cap_amount /
                            cap_percentage instead. Pass null to clear. Omit to
                            inherit, unless a non-null simple cap is sent (that
                            mode switch clears an omitted schedule). Mutually
                            exclusive with cap_amount / cap_percentage; do not
                            send both. When set, every frequency branch must
                            tile $0.00 to infinity with no gaps or overlaps, and
                            at least one bracket must withhold. Money fields are
                            in dollars.
                - title: Cancel
                  type: object
                  required:
                    - companyID
                    - status
                    - canceled_reason
                  properties:
                    companyID:
                      type: string
                      description: Company ID of employer
                    status:
                      type: string
                      enum:
                        - canceled
                      description: Must be canceled
                    canceled_reason:
                      type: string
                      description: Reason for cancellation (required)
                - title: Vacate
                  type: object
                  required:
                    - companyID
                    - status
                  properties:
                    companyID:
                      type: string
                      description: Company ID of employer
                    status:
                      type: string
                      enum:
                        - vacated
                      description: Must be vacated
            examples:
              Modify:
                value:
                  companyID: 1eeec343485723ee58afef12
                  status: modified
                  modification:
                    cap_percentage: 30
                    total_amount_owed: 450
              Modify to withholding schedule:
                summary: Switch to an advanced withholding schedule
                value:
                  companyID: 1eeec343485723ee58afef12
                  status: modified
                  modification:
                    withholding_schedule:
                      - frequency: weekly
                        brackets:
                          - min: 0
                            max: null
                            action:
                              kind: amount
                              amount: 50
              Cancel:
                value:
                  companyID: 1eeec343485723ee58afef12
                  status: canceled
                  canceled_reason: duplicate entry
              Vacate:
                value:
                  companyID: 1eeec343485723ee58afef12
                  status: vacated
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Canceled:
                  value:
                    success: true
                    data:
                      garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa
                      companyID: 1eeec343485723ee58afef12
                      workerID: 674759a85785745748e3847a
                      workerType: contractor
                      garnishment_type: creditor
                      priority: 50
                      total_amount_owed: 500
                      total_amount_withheld: 0
                      status: canceled
                      effective_start_date: '2025-01-01'
                      agency_name: Acme Agency
                      agency_address: 123 Court St
                      cap_percentage: 25
                      case_id: CASE-1
                      order_number: ORD-1
                      created_at: '2025-01-01T00:00:00.000Z'
                      updated_at: '2025-01-01T00:00:00.000Z'
                      canceled_reason: duplicate entry
                Modified:
                  value:
                    success: true
                    data:
                      garnishmentID: 4dab1c18d38a45e7a688aceeb4fcfcbb
                      companyID: 1eeec343485723ee58afef12
                      workerID: 674759a85785745748e3847a
                      workerType: contractor
                      garnishment_type: creditor
                      priority: 50
                      total_amount_owed: 450
                      total_amount_withheld: 0
                      status: active
                      effective_start_date: '2025-01-01'
                      agency_name: Acme Agency
                      agency_address: 123 Court St
                      cap_percentage: 30
                      case_id: CASE-1
                      order_number: ORD-1
                      previous_garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa
                      created_at: '2025-01-01T00:00:00.000Z'
                      updated_at: '2025-01-01T00:00:00.000Z'
                Modify to withholding schedule:
                  summary: Switch to an advanced withholding schedule
                  value:
                    success: true
                    data:
                      garnishmentID: 4dab1c18d38a45e7a688aceeb4fcfcbb
                      companyID: 1eeec343485723ee58afef12
                      workerID: 674759a85785745748e3847a
                      workerType: employee
                      garnishment_type: creditor
                      priority: 50
                      total_amount_owed: 500
                      total_amount_withheld: 0
                      status: active
                      effective_start_date: '2025-01-01'
                      agency_name: Acme Agency
                      agency_address: 123 Court St
                      withholding_schedule:
                        - frequency: weekly
                          brackets:
                            - min: 0
                              max: null
                              action:
                                kind: amount
                                amount: 50
                      case_id: CASE-1
                      order_number: ORD-1
                      previous_garnishmentID: 3cab1c18d38a45e7a688aceeb4fcfcaa
                      created_at: '2025-01-01T00:00:00.000Z'
                      updated_at: '2025-01-01T00:00:00.000Z'
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                    default: true
                  data:
                    type: object
                    properties:
                      garnishmentID:
                        type: string
                        description: Unique identifier for this garnishment
                        example: 3cab1c18d38a45e7a688aceeb4fcfcaa
                      companyID:
                        type: string
                        description: Company ID of employer
                        example: 1eeec343485723ee58afef12
                      workerID:
                        type: string
                        description: Employee or contractor ID this garnishment applies to
                        example: 674759a85785745748e3847a
                      workerType:
                        type: string
                        enum:
                          - employee
                          - contractor
                        description: Whether the worker is an employee or contractor
                        example: contractor
                      garnishment_type:
                        type: string
                        enum:
                          - child_support
                          - federal_tax_levy
                          - state_tax_levy
                          - creditor
                          - student_loan
                          - other
                        description: Type of garnishment order
                        example: creditor
                      priority:
                        type: integer
                        description: >-
                          Withholding priority. Lower numbers are withheld
                          first. When omitted on create, Zeal applies a
                          type-based default.
                        example: 50
                      total_amount_owed:
                        type: number
                        description: >-
                          Total balance owed in dollars. Omit for open-ended /
                          forever orders.
                        example: 500
                      total_amount_withheld:
                        type: number
                        description: Total amount withheld to date in dollars
                        example: 0
                      status:
                        type: string
                        enum:
                          - active
                          - satisfied
                          - modified
                          - vacated
                          - canceled
                        description: Lifecycle status of the garnishment
                        example: active
                      effective_start_date:
                        type: string
                        description: ISO date (YYYY-MM-DD) when withholding begins
                        example: '2025-01-01'
                      effective_end_date:
                        type: string
                        description: >-
                          ISO date (YYYY-MM-DD) when withholding ends. Omit for
                          open-ended orders.
                        example: '2025-12-31'
                      agency_name:
                        type: string
                        description: Name of the collecting agency
                        example: Acme Agency
                      agency_address:
                        type: string
                        description: Address of the collecting agency
                        example: 123 Court St
                      cap_amount:
                        type: number
                        description: >-
                          Per-paycheck maximum withhold amount in dollars. At
                          least one of cap_amount or cap_percentage is required
                          on create.
                        example: 150
                      cap_percentage:
                        type: number
                        description: >-
                          Per-paycheck maximum withhold percentage of disposable
                          earnings (0-100). At least one of cap_amount or
                          cap_percentage is required on create.
                        example: 25
                      garnishment_state:
                        type: string
                        description: US state code (2-letter) associated with the order
                        example: CA
                      case_id:
                        type: string
                        description: Court/agency case identifier
                        example: CASE-1
                      order_number:
                        type: string
                        description: Court/agency order number
                        example: ORD-1
                      custom_name:
                        type: string
                        description: Optional display name for this garnishment
                        example: Acme creditor
                      external_id:
                        type: string
                        description: Optional external identifier for your own systems
                        example: ext-create-1
                      previous_garnishmentID:
                        type: string
                        description: >-
                          ID of the garnishment this record supersedes. Present
                          when this garnishment was created via a modify
                          (status: modified) transition; omitted otherwise.
                        example: 2bab1c18d38a45e7a688aceeb4fcfcbb
                      canceled_reason:
                        type: string
                        description: Reason provided when status is canceled
                      satisfied_at:
                        type: string
                        description: ISO timestamp when the garnishment was fully satisfied
                      created_at:
                        type: string
                        description: ISO timestamp when the garnishment was created
                        example: '2025-01-01T00:00:00.000Z'
                      updated_at:
                        type: string
                        description: ISO timestamp when the garnishment was last updated
                        example: '2025-01-01T00:00:00.000Z'
                      withholding_schedule:
                        $ref: '#/components/schemas/WithholdingSchedule'
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    success: false
                    errors:
                      - message: >-
                          status is required and must be 'modified', 'canceled',
                          or 'vacated'
                        code: 0
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        code:
                          type: integer
                          example: 0
      deprecated: false
components:
  schemas:
    WithholdingSchedule:
      type: array
      minItems: 1
      description: >-
        Advanced withholding schedule (mutually exclusive with cap_amount /
        cap_percentage). Employee-only: contractors have no pay frequency, so a
        schedule on a contractor is rejected — use cap_amount / cap_percentage
        instead. Use for fixed amounts per pay frequency or disposable-earnings
        brackets. At least one of cap_amount, cap_percentage, or
        withholding_schedule is required. Money fields are in dollars. When
        present, every frequency branch must tile disposable earnings from $0.00
        to infinity with no gaps or overlaps: the first bracket min must be 0,
        each next min must be exactly $0.01 after the previous max, and the last
        bracket max must be null. At least one bracket in the schedule must
        withhold (not all exempt).
      items:
        type: object
        required:
          - frequency
          - brackets
        properties:
          frequency:
            type: string
            enum:
              - daily
              - weekly
              - biweekly
              - semimonthly
              - monthly
              - quarterly
            description: Pay frequency this branch applies to
          brackets:
            type: array
            minItems: 1
            description: >-
              Disposable-earnings brackets for this frequency. Must tile $0.00
              to infinity with no gaps or overlaps (first min is 0; each next
              min is previous max + 0.01; last max is null).
            items:
              type: object
              required:
                - min
                - max
                - action
              properties:
                min:
                  type: number
                  minimum: 0
                  description: >-
                    Inclusive lower bound of disposable earnings in dollars. The
                    first bracket in a branch must start at 0.
                max:
                  type: number
                  minimum: 0
                  nullable: true
                  description: >-
                    Inclusive upper bound of disposable earnings in dollars.
                    Only the last bracket may be null (open-ended); earlier
                    brackets require a max.
                action:
                  oneOf:
                    - type: object
                      required:
                        - kind
                      properties:
                        kind:
                          type: string
                          enum:
                            - exempt
                          description: Do not withhold in this band
                    - type: object
                      required:
                        - kind
                        - amount
                      properties:
                        kind:
                          type: string
                          enum:
                            - amount
                        amount:
                          type: number
                          minimum: 0
                          description: Fixed dollar amount to withhold
                    - type: object
                      required:
                        - kind
                        - floor
                      properties:
                        kind:
                          type: string
                          enum:
                            - excess_over_floor
                        floor:
                          type: number
                          minimum: 0
                          description: >-
                            Withhold disposable earnings above this floor
                            (dollars)
                    - type: object
                      required:
                        - kind
                        - percentage
                      properties:
                        kind:
                          type: string
                          enum:
                            - percentage
                        percentage:
                          type: number
                          minimum: 0
                          maximum: 100
                          description: >-
                            Percentage of disposable earnings to withhold
                            (0-100)
                  description: How to compute the withhold amount for this bracket
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: Authorization
      x-bearer-format: bearer

````