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

# Create a payment

`POST /payments`

Record a customer payment applied to invoices.

## What happens

- Payment record is created
- Specified amounts are applied to invoices
- Invoice/order status updated to `PAID` when fully paid
- Overpayment creates a credit memo automatically

## Validations

- Payment date must be >= invoice date for all applied invoices
- Application amounts must not exceed invoice open balances
- Customer must match invoice customer

## Request body

- PaymentInput
  - `customerId` string, uuid, required — Customer making the payment
  - `paymentDate` string, date, required — Date payment was received
  - `paymentMethodType` 'ACH_WIRE' | 'ZELLE' | 'VENMO' | 'CHECK' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'CREDIT_CARD' — 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
  - `reference` string — Check number, transaction ID, etc.
  - `notes` string — Payment notes
  - `applications` PaymentApplicationInput[], required — Invoices to apply payment to
    - `invoiceId` string, uuid, required — Invoice to apply payment to
    - `amount` number, required — Amount to apply to this invoice
  - `creditApplications` PaymentCreditApplicationInput[] — Credits to apply in this payment
    - `creditMemoId` string, uuid, required — Credit memo to apply
    - `amount` number, required — Credit amount to apply

## Response `201`

Payment created successfully

- Payment
  - `id` string, uuid, required
  - `key` string, nullable — Human-readable payment key
  - `customer` CustomerReference — 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.
    - `id` string, uuid, required — Customer UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Customer company name
    - `friendlyId` string, required — Human-readable customer identifier
    - `status` 'PROSPECT' | 'ACTIVE' | 'INACTIVE' | 'CHURNED', required — Customer status
    - `phoneNumber` string, nullable — Primary phone number
    - `website` string, nullable — Customer website URL
    - `createdAt` string, date-time, required — When the customer was created
    - `updatedAt` string, date-time, required — When the customer was last updated
    - `deletedAt` string, date-time, nullable — When the customer was soft deleted (null if active)
  - `paymentDate` string, date, required — Date payment was received
  - `paymentMethodType` 'ACH_WIRE' | 'ZELLE' | 'VENMO' | 'CHECK' | 'EFT_DIRECT_DEPOSIT' | 'E_TRANSFER' | 'CREDIT_CARD' — 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
  - `reference` string, nullable — Check number, transaction ID, etc.
  - `notes` string, nullable — Payment notes
  - `currency` string, nullable — Currency code
  - `totalAmount` number, required — Total payment amount
  - `applications` PaymentApplication[] — Invoices this payment is applied to
    - `id` string, uuid, required
    - `invoiceId` string, uuid, required
    - `invoiceFriendlyId` string, nullable
    - `invoiceAmount` number, nullable — Total invoice amount
    - `invoiceOpenBalance` number, nullable — Invoice balance before this payment
    - `amount` number, required — Amount applied to this invoice
  - `creditApplications` PaymentCreditApplication[] — Credits applied in this payment
    - `id` string, uuid
    - `creditMemoId` string, uuid
    - `creditMemoReference` string, nullable
    - `amount` number — Credit amount applied in this payment
  - `overpaymentAmount` number, nullable — Amount in excess of invoice totals
  - `overpaymentCreditMemoId` string, uuid, nullable — Credit memo created from overpayment
  - `shipmentIds` string[] — Related shipment IDs
  - `shipmentKeys` string[] — Related shipment friendly IDs
  - `qboId` string, nullable — QuickBooks Online payment ID
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `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)