Customer Payment API

Record payments received from customers and apply them to invoices using the NetSuite REST API.

---

Endpoints

Method	Endpoint	Description
GET	/record/v1/customerPayment	List all customer payments
GET	/record/v1/customerPayment/{id}	Get specific payment
POST	/record/v1/customerPayment	Create new payment
PATCH	/record/v1/customerPayment/{id}	Update payment
DELETE	/record/v1/customerPayment/{id}	Delete payment

---

Key Fields

Header Fields

Field	Type	Description	Required
id	string	Internal ID (read-only)	-
tranId	string	Payment number	Auto-generated
customer	object	Customer reference	Yes
tranDate	string	Payment date (ISO 8601)	Yes
status	object	Payment status	Read-only
subsidiary	object	Subsidiary	Yes (OneWorld)

Payment Fields

Field	Type	Description	Required
payment	number	Payment amount	Yes
currency	object	Transaction currency	Yes
exchangeRate	number	Exchange rate	Auto-calculated
paymentMethod	object	Payment method	No
creditCard	object	Credit card reference	Conditional
checkNum	string	Check number	No
account	object	Deposit to account	Yes
undepFunds	boolean	Undeposited funds	No

Application Fields

Field	Type	Description	Required
applied	number	Total amount applied (read-only)	-
unapplied	number	Unapplied amount (read-only)	-
autoApply	boolean	Auto-apply to oldest invoices	No

Other Fields

Field	Type	Description	Required
memo	string	Internal memo	No
class	object	Department/class	No
location	object	Location	No
department	object	Department	No

Sublists

Field	Type	Description	Required
apply	collection	Invoices to apply payment to	No
credit	collection	Credits to apply	No
deposit	collection	Deposits to apply	No

---

Apply Sublist Fields

The apply sublist specifies which invoices to pay.

Field	Type	Description	Required
doc	object	Invoice reference	Yes
apply	boolean	Whether to apply payment	Yes
amount	number	Amount to apply	Yes
disc	number	Discount taken	No
discDate	string	Discount date	No

---

Credit Sublist Fields

The credit sublist specifies credit memos to apply.

Field	Type	Description	Required
doc	object	Credit memo reference	Yes
apply	boolean	Whether to apply credit	Yes
amount	number	Amount to apply	Yes

---

Example: Create Customer Payment

POST /record/v1/customerPayment
Content-Type: application/json

{
  "customer": {
    "id": "456"
  },
  "tranDate": "2025-12-25",
  "payment": 1500.00,
  "subsidiary": {
    "id": "1"
  },
  "currency": {
    "id": "1"
  },
  "paymentMethod": {
    "id": "2"
  },
  "account": {
    "id": "10"
  },
  "checkNum": "1234",
  "memo": "Payment for Invoice #INV-5001 and #INV-5002",
  "apply": {
    "items": [
      {
        "doc": {
          "id": "5001"
        },
        "apply": true,
        "amount": 1000.00
      },
      {
        "doc": {
          "id": "5002"
        },
        "apply": true,
        "amount": 500.00
      }
    ]
  }
}

Response:

{
  "id": "10001",
  "tranId": "PMT-10001",
  "customer": {
    "id": "456",
    "refName": "Acme Corporation"
  },
  "tranDate": "2025-12-25",
  "payment": 1500.00,
  "applied": 1500.00,
  "unapplied": 0.00,
  "status": {
    "id": "DEPOSITED",
    "refName": "Deposited"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://{account}.suitetalk.api.netsuite.com/services/rest/record/v1/customerPayment/10001"
    }
  ]
}

---

Example: Apply Payment with Credit Memo

POST /record/v1/customerPayment
Content-Type: application/json

{
  "customer": {
    "id": "456"
  },
  "tranDate": "2025-12-25",
  "payment": 500.00,
  "subsidiary": {
    "id": "1"
  },
  "currency": {
    "id": "1"
  },
  "paymentMethod": {
    "id": "2"
  },
  "account": {
    "id": "10"
  },
  "memo": "Payment plus credit application",
  "credit": {
    "items": [
      {
        "doc": { "id": "6001" },
        "apply": true,
        "amount": 500.00
      }
    ]
  },
  "apply": {
    "items": [
      {
        "doc": { "id": "5001" },
        "apply": true,
        "amount": 1000.00
      }
    ]
  }
}

This applies $500 cash + $500 credit memo against a $1,000 invoice.

---

Example: Unapplied Payment

POST /record/v1/customerPayment
Content-Type: application/json

{
  "customer": {
    "id": "456"
  },
  "tranDate": "2025-12-25",
  "payment": 2000.00,
  "subsidiary": {
    "id": "1"
  },
  "currency": {
    "id": "1"
  },
  "paymentMethod": {
    "id": "3"
  },
  "account": {
    "id": "10"
  },
  "memo": "Advance payment - to be applied later"
}

Unapplied Payments

Omit the apply sublist to record payment without applying to specific invoices. Creates a credit balance on customer account.

---

Example: Update Customer Payment

PATCH /record/v1/customerPayment/10001
Content-Type: application/json

{
  "memo": "Payment cleared - confirmed by bank",
  "checkNum": "1234-CLEARED"
}

---

Apply Payment to Multiple Invoices

The apply sublist allows paying multiple invoices:

"apply": {
  "items": [
    {
      "doc": { "id": "5001" },
      "apply": true,
      "amount": 1000.00
    },
    {
      "doc": { "id": "5002" },
      "apply": true,
      "amount": 500.00
    },
    {
      "doc": { "id": "5003" },
      "apply": true,
      "amount": 250.00
    }
  ]
}

---

Apply Payment with Early Payment Discount

{
  "apply": {
    "items": [
      {
        "doc": { "id": "5001" },
        "apply": true,
        "amount": 980.00,
        "disc": 20.00,
        "discDate": "2025-12-25"
      }
    ]
  }
}

Payment of $980 with $20 discount on $1,000 invoice.

---

Query Filters

Find Payments by Date

GET /record/v1/customerPayment?q=tranDate='2025-12-25'

Find by Customer

GET /record/v1/customerPayment?q=customer='456'

Find Unapplied Payments

GET /record/v1/customerPayment?q=unapplied > 0

Find by Payment Method

GET /record/v1/customerPayment?q=paymentMethod='2'

Find by Date Range

GET /record/v1/customerPayment?q=tranDate BETWEEN '2025-12-01' AND '2025-12-31'

Find High-Value Payments

GET /record/v1/customerPayment?q=payment > 5000

Find Undeposited Funds

GET /record/v1/customerPayment?q=undepFunds=true

---

Important Notes

Accounting Impact

Creating a customer payment:

• Debit: Cash/Bank Account (or Undeposited Funds)
• Credit: Accounts Receivable

Reduces customer's A/R balance and increases cash.

When to Use Customer Payments

• Payments received after invoicing
• Check payments
• Wire transfers
• ACH/EFT payments
• Any post-invoice payment

Payment Application

Payments can be applied to:

• One or multiple invoices
• Partial invoice amounts
• Combined with credit memos
• Left unapplied (creates customer credit)

Auto-Apply Feature

Set autoApply: true to automatically apply payment to oldest invoices:

{
  "payment": 1000.00,
  "autoApply": true
}

Unapplied Payments

When payment > applied amount:

• Creates credit balance on customer
• Can apply to future invoices
• Available for refund via Customer Refund
• Shows as unapplied in customer record

Overpayment Handling

If customer pays more than owed:

1. Apply to all outstanding invoices
2. Remaining amount stays unapplied
3. Use for future invoices or refund

Payment Methods

Common payment methods:

• Check
• ACH/EFT
• Wire Transfer
• Credit Card
• PayPal/Stripe
• Cash

Undeposited Funds

Set undepFunds: true to hold payment for later deposit:

{
  "undepFunds": true,
  "paymentMethod": { "id": "1" }
}

Later include in bank Deposit transaction.

Credit Card Processing

• Requires payment processor integration
• Real-time authorization
• Tokenization for PCI compliance
• Automatic reconciliation

Early Payment Discounts

Apply discounts for early payment:

• Set discount terms on invoice
• Calculate discount amount
• Apply via disc field
• Track discount date

Partial Payments

Apply less than invoice total:

{
  "doc": { "id": "5001" },
  "apply": true,
  "amount": 500.00  // Invoice is $1,000
}

Invoice remains open for $500 balance.

Multi-Currency Payments

• Must match customer/invoice currency
• Exchange rate locked at payment date
• Gain/loss calculated on application
• Important for international payments

Payment Reversals

To reverse a payment:

1. Delete the payment (if period open)
2. Or create offsetting journal entry
3. Re-apply credits if needed

Bank Reconciliation

• Payments appear on bank reconciliation
• Match with bank statement
• Clear in NetSuite when reconciled
• Important for cash management

Integration Considerations

• Payment gateways update in real-time
• Bank feeds can auto-create payments
• Match payments to bank deposits
• Automate reconciliation

---

See Also

• Invoice - Invoices to pay
• Credit Memo - Credits to apply
• Customer Refund - Refund overpayments
• Deposit - Bank deposits
• Customer Deposit - Prepayments