# Update a payment

Update payment details or reassign invoice applications.

## What happens

- Payment fields are updated
- Invoice applications are replaced if provided
- Order statuses are recalculated

## Note

Updating applications replaces all existing applications.
Include all desired applications in the request.

Endpoint: PATCH /payments/{id}
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Request fields (application/json):

  - `paymentDate` (string)

  - `paymentMethodType` (string)
    Payment method type.
- ACH_WIRE: ACH or wire transfer
- ZELLE: Zelle payment
- VENMO: Venmo payment
- CHECK: Paper check
- EFT_DIRECT_DEPOSIT: EFT direct deposit
- E_TRANSFER: Electronic transfer
- CREDIT_CARD: Credit card payment
    Enum: "ACH_WIRE", "ZELLE", "VENMO", "CHECK", "EFT_DIRECT_DEPOSIT", "E_TRANSFER", "CREDIT_CARD"

  - `reference` (string,null)

  - `notes` (string,null)

  - `applications` (array)
    Replace all invoice applications

  - `applications.invoiceId` (string, required)
    Invoice to apply payment to

  - `applications.amount` (number, required)
    Amount to apply to this invoice

  - `creditApplications` (array)
    Replace all credit applications

  - `creditApplications.creditMemoId` (string, required)
    Credit memo to apply

  - `creditApplications.amount` (number, required)
    Credit amount to apply

## Response 200 fields (application/json):

  - `id` (string, required)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string,null)
    Human-readable payment key
    Example: "PMT-00001"

  - `customer` (object)
    Enhanced reference to a customer resource (returned in responses).
Includes full customer details in addition to id/key.

Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

  - `customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `paymentDate` (string, required)
    Date payment was received

  - `paymentMethodType` (string)
    Payment method type.
- ACH_WIRE: ACH or wire transfer
- ZELLE: Zelle payment
- VENMO: Venmo payment
- CHECK: Paper check
- EFT_DIRECT_DEPOSIT: EFT direct deposit
- E_TRANSFER: Electronic transfer
- CREDIT_CARD: Credit card payment
    Enum: "ACH_WIRE", "ZELLE", "VENMO", "CHECK", "EFT_DIRECT_DEPOSIT", "E_TRANSFER", "CREDIT_CARD"

  - `reference` (string,null)
    Check number, transaction ID, etc.

  - `notes` (string,null)
    Payment notes

  - `currency` (string,null)
    Currency code
    Example: "USD"

  - `totalAmount` (number, required)
    Total payment amount

  - `applications` (array)
    Invoices this payment is applied to

  - `applications.invoiceId` (string, required)

  - `applications.invoiceFriendlyId` (string,null)

  - `applications.invoiceAmount` (number,null)
    Total invoice amount

  - `applications.invoiceOpenBalance` (number,null)
    Invoice balance before this payment

  - `applications.amount` (number, required)
    Amount applied to this invoice

  - `creditApplications` (array)
    Credits applied in this payment

  - `creditApplications.creditMemoId` (string)

  - `creditApplications.creditMemoReference` (string,null)

  - `creditApplications.amount` (number)
    Credit amount applied in this payment

  - `overpaymentAmount` (number,null)
    Amount in excess of invoice totals

  - `overpaymentCreditMemoId` (string,null)
    Credit memo created from overpayment

  - `shipmentIds` (array)
    Related shipment IDs

  - `shipmentKeys` (array)
    Related shipment friendly IDs

  - `qboId` (string,null)
    QuickBooks Online payment ID

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message