---
title: "Create a bill payment"
method: POST
path: "/bill-payments"
tags: ["Bill Payments"]
---

# Create a bill payment

`POST /bill-payments`

Record a payment for one or more carrier/vendor bills.

## What happens

- PaymentGroup record is created
- Payment applications are created for each bill
- Bill open balances are reduced
- Load/service status updates to PAID when fully paid

## Carrier factor payments

To pay a carrier's factor instead of the carrier directly,
specify `carrierFactorId` in the request.

## Overpayments

If `allowOverpayment` is true and payment exceeds bill totals,
a credit memo is automatically created for the difference.

## Request body

- BillPaymentInput
  - `paymentDate` string, date, required — Date of payment
  - `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
  - `carrierFactorId` string, uuid — Carrier factor to pay (for factored payments)
  - `reference` string — Check number, transaction ID, etc.
  - `notes` string — Additional notes
  - `applications` BillPaymentApplicationInput[], required — Bills to pay
    - `billId` string, uuid, required — Bill (invoice) to apply payment to
    - `amount` number, required — Amount to apply to this bill
  - `allowOverpayment` boolean — Allow payment amount to exceed bill totals

## Response `201`

Bill payment created 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
- `409` — Conflict - bill already paid or invalid state
- `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/revisions/c44e5e7a4256/schema)