Table of Contents

Associating a payment with a pledge ad-hoc

Background and Context

Sometimes pledge payments come in through unexpected channels. Perhaps a donor who usually sends checks decides to pay online one month.

Unfortunately, CiviCRM does not provide a user interface for updating the pledge history to indicate that the payment in question should be applied toward the promised total. Fortunately, this is not difficult to do via the API Explorer.

Before You Start

To start, you’ll need the ID of the pledge and the contribution in question. These can be found by hovering over the link to view or edit them and recording the value of the “id” parameter in the URL.

In recent versions, a lot of CiviCRM detail screens have been designed to open in modals. Though this is a good default behavior, it is not always desirable (e.g., if you wish to link directly to a detail screen.) To open a modal view in a full browser window instead, right-click on it and select “Open link in new tab.”

Using the API Explorer

Navigate to the API Explorer and select PledgePayment and create as the entity and action, respectively. Populate the following parameters to the API, clicking Add Parameter as needed:

  • Pledge: The numeric ID of the pledge you wish to update.
  • Payment Status: The status of the payment. Completed will be appropriate in most cases.
  • Contribution: The numeric ID of the contribution which should be counted toward the pledged total.
  • Actual Amount: The amount which should be counted toward the pledge total. (Note: Actual Amount does not need to match the total of the contribution.)
  • Payment ID: This is an optional field, and it is likely you can leave this off the API call in most cases. When a pledge is created, a payment record is created for each installment in the pledge. If you wish to specify the precise payment to update with this contribution, pass its numeric ID via this parameter. Otherwise, the oldest pledge with no associated contribution will be selected automatically.

Below your configurations, the API Explorer will update the API call in real time. You should end up with something like this in the PHP section:

$result = civicrm_api3('PledgePayment', 'create', array(
  'pledge_id' => 1094,
  'status_id' => "Completed",
  'contribution_id' => 53212,
  'actual_amount' => 8000,

Click Execute to effect these changes in your database. You will see some JSON output near the bottom of the page which will contain “is_error”: 0 on success.

Since using the API Explorer can change (and even destroy!) data, it is recommended that operations be tested in the sandbox copy of the site before they are performed in production. To request a sandbox refresh, send a request to [email protected].

Updated: 2-12-2019