Gift V2 Add Pledge Installments

Joshua Morlan · May 2023

Hi,

Using the NXT API Gift v2 Add Pledge Installments endpoint:

I'm running into an error: There were issues with the contract: The sum of the pledge installments’ amounts must equal the pledge’s amount ‘100’.

feeea3830b7aa869290c1640ffad1a90-huge-im

When pledges are created in my clients system they are automatically created with one installment of the full amount, so I'm pretty sure that's the reason my installments aren't adding up to 100, because there is already one installment for the full amount.

Is there any way to change this? No API endpoints to change installment amounts or remove an installment? My client says when they edit the installment schedule in their back end that any current installments automatically adjust to fit the new schedule. Wondering if there is some option somewhere for me to do this?

Alex Wong · May 2023

@Joshua Morlan
Definitely not the easiest and well documented at the moment AND there is a bug that BB isn't fixing yet.

First, you need to create a new pledge record, this actually does not create installment.

POST - Create a gift using the Blackbaud Add-ins Send HTTP Request

{
"amount": {
"value": 5000
},
"comments": "PG2305-15P",
"constituent": {
"id": "486387"
},
"gift_date": "2023-05-15",
"gift_post_status": "NotPosted",
"gift_post_date": "2023-05-15",
"gift_splits": [
{
"amount": {
"value": 5000
},
"fund_id": "5385",
"campaign_id": "88",
"appeal_id": "5589",
"package_id": "13347"
}
],
"gift_type": "Pledge",
"receipts": [
{
"receipt_amount": {
"value": 5000
},
"receipt_status": "DoNotReceipt"
}
],
"payments": [
{
"amount": {
"value": 5000
},
"method": "Other"
}
],
"send_reminder": true
}

The action will request in the Gift System ID of the pledge that was created, use it to “add the installment(s)"

POST - Add pledge installments

{
"installments": [
{
"amount": 5000,
"date": "2023-09-30T00:00:00Z",
"sequence": 1
}
]
}

That is it, BUT, here's the bug

The installment is actually “half" created. Meaning, somewhere in RE it is recognized as a valid installment, while in RE database view, it is not exactly done properly.

If you go into the pledge record in webview, everything looks good. if you go into the pledge record in database view, everything looks good as well. UNTIL you try to change a piece of info (any info), and try to “Save” the gift record, you will get an error.

Currently my automation has a last step that tells our data entry team the “post” work that needs to be done to the pledge to make it fully “legit”

Due to a Blackbaud Bug, Finance Support must do the follow (1x for each pledge gift created) until further notice
Open each pledge gift record created in RE Database View
Go to the Installments/Payments tab
Follow the steps below corresponding to the step # in the instruction image
Click on Schedule button
Click on Reschedule button
Copy the Date (shown in the image) to the Starting on: field in the Create New Schedule section
Click Next >
Finish the change by clicking on Finish button and then Save and Close out of the gift record.

Alex Wong · May 2023

@Joshua Morlan
By the way, you “might” think that if the add installment isn't really working, and requires to go into database view to “re-schedule” the installment anyway, why not create the pledge with Gift v2 API, but don't add the installment, instead just have the data entry do the “post work” of scheduling the installment.

I thought that too, but if you do not use Gift v2 API to add installment (even though buggy), you will NOT get the option to schedule the installment when you open the pledge gift in database view. You must do both the create a pledge API and add installment API then do the bug fix manually in database view.

So some may ask, then why bother, just have the data entry create pledges like they always have for now until Blackbaud fix the API. Yes, that is true, if your plan to create pledge through API is simply to create a pledge record, then it may not be worth the effort, however, for us, it was well worth it for the following reason, and you can gauge if the below reason fits you too:

Pledge creation standardization, no human error.
- we have a specific program for student sponsorship that need very specific gift attributes and exact entries, this has always been 50% error when manually entered, with the new automation process, we have 0% error
pledge agreement is uploaded as part of the request form filled in by fundraiser, this process automatically upload the pledge agreement pdf as attachment directly to each pledges created (sometime an agreement may result in multiple pledges)
- big time saver as data entry would have batched the pledge in database view, THEN have to go to webview and attach the pledge agreement pdf manually to each pledge

Joshua Morlan · May 2023

@Alex Wong
Thanks for the rundown and I appreciate pointing out that bug, seems wild but understandable since this is in development.

Unfortunately in my scenario the pledge record already exists, these records are being created in DB by staff, and when they are created they automatically have 1 installment for the full amount.

So my guess is, there currently is no api endpoint to modify/delete that one installment. I can't create new installments on the pledge because the single installment already equals the entire pledge.

Anthony Gallo · May 2023

@Joshua Morlan, @Alex Wong

We started our pledge work recently and that will end with us getting pledge into web view. The API is going to be fixed during this work that we have slated for Q3. We will allow for an input of a schedule and installments, just a schedule, or just installments at the end of this project. We are currently doing some backend batch work to get ready to accept the pledges from online donation forms and once that is complete, we will move into the pledge creation and management part of the project, just to give you a better view of what we are working on.

Alex Wong · May 2023

@Joshua Morlan
I don't know if the Add Installment API actually “replaces” what is currently there on the pledge or not. Nor do I know if the endpoint only works on Pledge created by the API.

However, depending on your business use case, you can very well automate the whole Pledge creation process rather than having the pledge created manually by someone in db view. Something to think about and potentially do

Gift V2 Add Pledge Installments

Comments

Categories