Payment Allocation Schema
Payment distribution records linking transactions to invoice payments
The Payment Allocation schema defines the structure and properties of payment allocation objects in the Payload API. Payment allocations track how payment amounts are distributed across invoices, linking transactions to specific invoices and reducing their balances. This enables partial payments, multi-invoice payments, and tracking of both platform-processed payments and external payments made via cash, check, or wire transfer.
Payment Allocation Object Properties
Complete reference for all properties available in the Payment Allocation schema
amountnumber (double)Required
The payment amount being allocated to the invoice. This is how much of the payment is being applied toward this specific invoice. Cannot exceed the invoice's remaining balance_due. Required for all payment allocations.
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
external_paymentboolean
Flag indicating whether this payment was made outside the Payload platform. Set to true for payments made via cash, check, wire transfer, or other external methods that are being manually recorded. Set to false (or omit) for payments processed through Payload. When true, transaction_id must be null. When false, transaction_id is typically required.
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: item)
Pattern:
^item_[A-Za-z0-9]+$invoice_id ID of InvoicestringRequired
The unique identifier of the invoice that this payment is being allocated to. The payment amount will be applied toward this invoice's balance, reducing the amount_due. Required for all payment allocations. (ID prefix: inv)
Pattern:
^inv_[A-Za-z0-9]+$modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
payment_allocationtransaction_id ID of Transactionstring
The unique identifier of the transaction that processed this payment. Links the payment allocation to the actual payment transaction. Required when external_payment is false. Must be null when external_payment is true (for payments made outside the platform). (ID prefix: txn)
Pattern:
^txn_[A-Za-z0-9]+$