---
title: "Update a bill payment"
method: PATCH
path: "/bill-payments/{id}"
tags: ["Bill Payments"]
---

# Update a bill payment

`PATCH /bill-payments/{id}`

Update bill payment fields.

## Constraints

- Cannot change carrier factor after creation
- Can add/remove/update payment applications

## Updating applications

In the `applications` array:
- Include `id` to update an existing application
- Omit `id` and include `billId` to add a new application
- Set `delete: true` with `id` to remove an application

## Path parameters

- `id` string, required

## Query parameters

- `by` 'id' | 'key'

## Request body

- BillPaymentPatch
  - `paymentDate` string, date
  - `paymentMethodType` 'ACH_WIRE' | 'CHECK' | 'CREDIT_CARD' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'VENMO' — Payment method used for the bill payment. - `ACH_WIRE`: ACH wire transfer - `CHECK`: Paper check - `CREDIT_CARD`: Credit card payment - `EFT_DIRECT_DEPOSIT`: EFT direct deposit - `E_TRANSFER`: Electronic transfer - `VENMO`: Venmo payment
  - `reference` string, nullable
  - `notes` string, nullable
  - `applications` BillPaymentApplicationPatch[] — Update payment applications
    - `id` string, uuid — Existing application ID (for update)
    - `billId` string, uuid — Bill ID (for new applications)
    - `amount` number
    - `delete` boolean — Set to true to remove this application

## Response `200`

Bill payment updated successfully

- BillPayment
  - `id` string, uuid, required
  - `key` string, nullable — Client-defined key
  - `recipientType` 'CARRIER' | 'VENDOR', required — Type of recipient for the payment. - `CARRIER`: Payment to a carrier - `VENDOR`: Payment to a vendor
  - `carrier` CarrierReference — Enhanced reference to a carrier resource (returned in responses). Includes full carrier details in addition to id/key. Note: Does NOT include nested references (contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — Carrier UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Carrier company name
    - `phoneNumber` string, nullable — Primary phone number
    - `email` string, email, nullable — Primary email address
    - `createdAt` string, date-time, required — When the carrier was created
    - `updatedAt` string, date-time, required — When the carrier was last updated
    - `deletedAt` string, date-time, nullable — When the carrier was soft deleted (null if active)
  - `vendor` VendorReference — Enhanced reference to a vendor profile. Includes full vendor details in addition to id/key.
    - `id` string, uuid, required — Vendor UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `friendlyId` string, required — Human-readable vendor identifier
    - `name` string, required — Vendor legal name
    - `email` string, email, nullable — Primary email address
    - `phone` string, nullable — Primary phone number
    - `status` string, nullable — Vendor status
    - `currency` string, nullable — Preferred currency code (ISO 4217)
    - `createdAt` string, date-time, required — When the vendor was created
    - `updatedAt` string, date-time, required — When the vendor was last updated
  - `carrierFactor` BillPaymentsCarrierFactorReference
    - `id` string, uuid
    - `companyName` string
    - `bankName` string, nullable
  - `paymentDate` string, date, required — Date the payment was made
  - `paymentMethodType` 'ACH_WIRE' | 'CHECK' | 'CREDIT_CARD' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'VENMO' — Payment method used for the bill payment. - `ACH_WIRE`: ACH wire transfer - `CHECK`: Paper check - `CREDIT_CARD`: Credit card payment - `EFT_DIRECT_DEPOSIT`: EFT direct deposit - `E_TRANSFER`: Electronic transfer - `VENMO`: Venmo payment
  - `reference` string, nullable — Check number, transaction ID, etc.
  - `notes` string, nullable — Additional notes
  - `totalAmount` number, required — Total payment amount (sum of all applications)
  - `overpayment` number, nullable — Amount paid in excess of invoice totals
  - `overpaymentCreditMemoId` string, uuid, nullable — Credit memo created for overpayment
  - `applications` BillPaymentApplication[], required — Individual bill payments in this group
    - `id` string, uuid, required
    - `billId` string, uuid, required — Bill (invoice) this payment applies to
    - `billFriendlyId` string, nullable — Human-readable bill ID
    - `amount` number, required — Amount applied to this bill
    - `loadCarrierId` string, uuid, nullable — Associated load carrier (for carrier bills)
    - `vendedServiceId` string, uuid, nullable — Associated vended service (for vendor bills)
    - `shipmentId` string, uuid, nullable
    - `shipmentFriendlyId` string, nullable
  - `qboId` string, nullable — QuickBooks Online bill payment ID
  - `syncStatus` 'pending' | 'synced' | 'error', nullable — QuickBooks sync status
  - `syncError` string, nullable — QuickBooks sync error message
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `404` — Resource not found
- `409` — Conflict - invalid state for update
- `422` — Validation error - invalid field values

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/versions/c44e5e7a4256/schema)