Adding Installment Payments in Batch

This guide walks you through creating a batch of installment payments for existing pledges, either by entering them manually or importing from a spreadsheet.

Creating a New Batch

1. Go to Data > Batch Import
2. Click Create and confirm — the batch is named with the date and time; rename it on the batch page if you like (e.g., "January Pledge Payments")
3. Under What do you want to import?, choose Installments

TIP

Use descriptive batch names to make them easy to find later. You can edit the batch name anytime before processing.

Adding Installments Manually

Click Add to open the installment form. Fill in the required fields and any optional information.

Required Fields

Field	Description
Pledge Profile	The pledge this payment applies to (offline pledges only)
Amount	The payment amount
Payment Date	When this payment was received

Optional Fields

Field	Description
Invoice ID	Link to a specific scheduled invoice (marks it as paid)
Reference ID	A unique identifier for this payment (useful for updates)

WARNING

If a payment with the same reference ID already exists, core and revenue payment fields will be updated; if more than one does, the row is refused. Revenue splits, credits, solicitors, and tags from the new import are handled as follows: tags are added (safe to re-import), custom values are replaced, and splits/credits/solicitors are only created on initial import.

Revenue Settings

Each installment payment creates a revenue record. You can optionally set payment details:

Field	Description
Payment Method	How the payment was made (none, cash, check, credit card, debit card, PayPal, cryptocurrency, bank transfer, gift in kind, other — defaults shown; your organization may customize these)
Payment Reference	Check number, wire reference, receipt number, etc.
Revenue Status	Payment status (defaults to completed)
Payment Channel	Online or offline (defaults to offline)
Payment Notes	Additional payment details
Fund	Which fund to allocate revenue to
Fund Amount	Amount to allocate to the fund (defaults to full payment amount)

TIP

For check payments, use "check" as the payment method and enter the check number in the Payment Reference field.

Revenue Credits

Link additional contacts or organizations to a payment as soft or hard credits. Each credit has:

Field	Description
Contact/Organization	Who receives the credit — a contact or a CRM organization (one required)
Amount	Credit amount
Type	soft (Soft Credit) or hard (Hard Credit). Default: soft
Category	Optional: tribute, matching (Matching Gift), solicitor, household, or other

Click Add Credit to add revenue credits.

Revenue Solicitors

Solicitors track who secured the payment. Each solicitor has:

Field	Description
Contact/Organization	The solicitor — a contact or a CRM organization (one required)
Amount	Attributed amount (for reporting)

Click Add Solicitor to add revenue solicitors.

Editing and Removing Rows

• Edit: Click anywhere on a row to open the form and make changes
• Delete: Click the trash icon on the right side of a row

Importing from Spreadsheet

For large batches, importing from a spreadsheet is faster:

1. Click Import from Spreadsheet at the bottom of the batch
2. Select your CSV or Excel file
3. Map your columns to the correct fields (if needed)
4. Review the imported rows

See Importing from Spreadsheet for detailed instructions on the import process.

Supported CSV Columns

Below is the full list of columns supported when importing installment payments from a CSV or Excel file.

Required

Column	Description
installment_profile_id	The pledge profile ID this payment applies to
amount	Payment amount, a plain number greater than 0. A row whose amount reads as 0 or less (including one with a currency symbol, like $100) is refused at upload; a thousands separator cuts the number off (1,200.00 reads as 1).
created_at	Date and time the payment was received (e.g., 2024-01-15 10:30:00)

Optional

Column	Description
invoice_id	Link to a specific scheduled invoice (marks it as paid)
reference_id	External or unique identifier — if a payment with the same reference ID exists, core and revenue payment fields will be updated. If more than one payment already has it, the row is refused. Revenue splits, credits, and solicitors are only set on initial import.

Payer (optional)

Leave these blank and the payment takes its payer details from the pledge. An email that belongs to an existing contact makes that contact the payer — except on a pledge whose donor is an organization.

Column	Description
display_name	Payer's display name
first_name	Payer's first name
last_name	Payer's last name
email	Payer's email address
contact_id	The contact who paid, if different from the pledge's donor
crm_organization_id	The organization that paid, by its CauseVox ID or its reference ID. Don't combine with contact_id.
line1, line2, city, state, zipcode, country	Payer's address

Revenue

Column	Description
revenue_payment_method	One of your organization's payment methods, by value or label (e.g., check, Cash, bank_transfer). Any other value refuses the row at upload.
revenue_payment_reference	Reference number (check number, wire reference, etc.)
revenue_status	Payment status (e.g., completed, pending)
revenue_payment_channel	Where the payment was received (e.g., online, offline)
revenue_payment_meta	Additional payment notes

Fund

Column	Description
fund_id	Fund designation ID
fund_amount	Amount to allocate to the fund

Custom Fields (numbered, via column mapping)

Add custom field values using numbered columns:

Column	Description
installment_custom_field_1	Value for the first installment custom field
installment_custom_field_2	Value for the second installment custom field
revenue_custom_field_1	Value for the first revenue custom field
revenue_custom_field_2	Value for the second revenue custom field

Add more numbered columns (_3, _4, etc.) as needed.

Revenue Splits (numbered, via column mapping)

Column	Description
revenue_split_fund_id_1	Fund ID for the first split
revenue_split_amount_1	Amount for the first split

Add more numbered pairs (_2, _3, etc.) as needed.

Revenue Credits (numbered, via column mapping)

Column	Description
revenue_credit_contact_id_1	Contact ID for the credit recipient
revenue_credit_crm_organization_id_1	CRM organization ID for the credit recipient (a credit needs a contact or an organization)
revenue_credit_amount_1	Credit amount
revenue_credit_type_1	soft or hard. Blank means soft
revenue_credit_category_1	Category: tribute, matching, solicitor, household, or other

Add more numbered sets (_2, _3, etc.) as needed.

Revenue Solicitors (numbered, via column mapping)

Column	Description
revenue_solicitor_contact_id_1	Contact ID for the first solicitor
revenue_solicitor_crm_organization_id_1	CRM organization ID for the first solicitor (a solicitor needs a contact or an organization)
revenue_solicitor_amount_1	Attributed amount

Add more numbered sets (_2, _3, etc.) as needed.

Tags (numbered, via column mapping)

Column	Description
revenue_tag_1	Tag name for the revenue record

Add more numbered columns (_2, _3, etc.) as needed.

TIP

Custom fields use numbered suffixes (_1, _2, etc.) and require the column mapping step during import. When you upload your file, map each numbered column to the correct field.

How Contacts Are Linked

Installments normally inherit their donor (the contact or the organization) from the parent pledge (installment_profile_id). If a row provides a contact_id or a crm_organization_id explicitly, that donor is used instead of the pledge's, and the installment doesn't carry the other one. A row that provides both is refused.

If a spreadsheet row's contact_id doesn't match a contact in your organization, it is cleared at upload with an "Invalid Contact … was cleared" warning — and a row with no donor left takes the pledge's donor, so fix the warning before processing if the payer should differ. A row added by hand or through the API that names an unknown contact fails at processing with "Invalid Contact ID specified". Installment processing never creates a contact.

A payer email that belongs to an existing contact makes that contact the payer, unless the pledge's donor is an organization.

See Importing from Spreadsheet for the full matching behavior across batch types.

Reviewing Your Batch

Before processing, review your data:

• Check that amounts are correct
• Verify pledge profile assignments
• Confirm payment dates
• Look for any error indicators

Processing the Batch

When you're ready to finalize:

1. Click Process Batch
2. Confirm the action
3. Wait for processing to complete

Important

Batch processing cannot be undone. Once processed, each installment payment becomes a permanent record. Double-check your data before processing.

After Processing

Once processed:

• Installment payments appear under the pledge in Manage > Pledges
• Revenue records are created automatically
• Pledge stats are updated (amount paid, remaining balance)
• Linked invoices are marked as paid

Tips and Best Practices

1. Start small - Test with a few records before importing thousands
2. Use reference IDs - Makes it easy to update records later
3. Review before processing - Check for duplicates and errors
4. Verify pledge profiles - Ensure each payment links to the correct pledge
5. Keep your spreadsheet - Useful for troubleshooting or re-imports
6. Process in batches - Split large imports into manageable chunks