Getting StartedAPI Reference
Changelog
Back to All
Improved

Breaking Change: AP Pay Batch Entries Add

24 days ago by Ben Lash

Target release date: July 29, 2026

Affected endpoint: POST /vista/ap/2/data/pay_batch_entries/actions/add

This release updates the Pay Batch Entries Add action with a breaking request schema change and an enhancement that groups multiple vendor invoices onto a single payment header, matching Vista AP Payment Posting behavior.
Action required before July 29: Integrations calling Pay Batch Entries Add must update request payloads to use the new PayBatchEntry wrapper (see Migration below). No other endpoint URLs change.

Breaking Change — Request Schema

The Add action input must now be sent as a wrapped object. The previous flat JSON shape at the root level will no longer validate.

Before

{
  "Co": 50,
  "Mth": "2025-05-01",
  "BatchId": 4,
  "Vendor": 911,
  "PaidDate": "2026-03-02",
  "PayMethod": "C",
  "CMAcct": 1,
  "ExpMth": "2025-01-01",
  "APTrans": 12345
}

After (required)

{
  "PayBatchEntry": {
    "Co": 50,
    "Mth": "2025-05-01",
    "BatchId": 4,
    "Vendor": 911,
    "PaidDate": "2026-03-02",
    "PayMethod": "C",
    "CMAcct": 1,
    "ExpMth": "2025-01-01",
    "APTrans": 12345
  }
}

All existing fields (ExpMth, APTrans, Vendor, PaidDate, PayMethod, CMAcct, CMRef, AddressOverride, etc.) remain valid — they move inside PayBatchEntry. Requirements from the prior Pay Batch Entries Add update (including required ExpMth and APTrans on single-invoice requests) are unchanged.

API Improvements

Request body must be wrapped in PayBatchEntry. Flat root-level payloads are no longer accepted.
Repeated Add calls for the same vendor in the same payment batch now group onto one payment header when SeparatePayYN is N and vendor, pay method, CM account, and address sequence match. This produces one check or ACH per vendor instead of one per invoice.
Added optional grouped input via LineItems[] to add multiple open AP transactions for one vendor in a single API call. Each line requires ExpMth and APTrans.
Success response now documents BatchSeq (required) and LineCount (number of invoice lines on the payment header). Use LineCount to confirm grouping on repeated Adds.

Grouping Behavior

When adding invoices to a payment batch, the API now follows Vista AP Payment Initialization defaults:
Checks (PayMethod = C)

  • One payment header per vendor per batch
  • Unique check reference (CMRef) per vendor payment
    EFT (PayMethod = E)
  • One payment header per vendor per batch
  • All EFT payments in the batch share the same CMRef (one EFT file)
  • Each vendor receives a sequential EFTSeq within that file
    Separate pay (SeparatePayYN = Y)
  • Forces a distinct payment header even when other grouping criteria match
  • Use this when a vendor must receive separate checks or ACH disbursements
    Address sequence
  • Different AddressSeq values create separate payment headers, consistent with Vista behavior
    Vendor validation
  • The Vendor in the request must match the vendor on each APTrans. Mismatches return an error.

Optional — Grouped LineItems[] Request

Instead of multiple single-invoice Add calls, you may send multiple invoices in one request:

{
  "PayBatchEntry": {
    "Co": 50,
    "Mth": "2025-05-01",
    "BatchId": 4,
    "Vendor": 911,
    "PaidDate": "2026-03-02",
    "PayMethod": "C",
    "CMAcct": 1,
    "SeparatePayYN": "N",
    "LineItems": [
      { "ExpMth": "2025-01-01", "APTrans": 100 },
      { "ExpMth": "2025-02-01", "APTrans": 101 }
    ]
  }
}

LineItems requires at least two entries. Optional per-line fields: Gross, Balance, DiscTaken.

Success Response

{
  "Co": 50,
  "Mth": "2025-05-01",
  "BatchId": 4,
  "BatchSeq": 1,
  "KeyID": 987654,
  "LineCount": 2
}

On grouped Adds, repeated calls for the same vendor return the same KeyID and an increasing LineCount. Integrations that assumed every Add created a new KeyID for the same vendor should use KeyID and LineCount to track the grouped header.

Migration Checklist

  1. Wrap all Pay Batch Entries Add request bodies in { "PayBatchEntry": { ... } } before July 29.
  2. Retest your payment batch workflow — create a batch via pay_batches/actions/add, then add invoices. Confirm one payment header per vendor in the pay_batch_entries cache and in Vista after posting.
  3. Optional: Adopt LineItems[] to reduce round-trips when paying multiple invoices for the same vendor.
  4. Optional: Update response parsing to use LineCount for grouping confirmation.
  5. Use SeparatePayYN: Y when you intentionally need separate payments for the same vendor.

What Does Not Change

  • Endpoint path: POST /vista/ap/2/data/pay_batch_entries/actions/add
  • Parent workflow: create the payment batch first via pay_batches/actions/add
  • pay_batch_entries cache read shape (one header with nested LineItems[])
  • Required fields on single-invoice Adds (ExpMth, APTrans, Vendor, PaidDate, and other existing requirements)

Reference