GiveCampus API - Requesting Pledge Data – GiveCampus University

Overview

Pledges on GiveCampus are represented in two layers:

Commitments: the original pledge records with pledge-level details
Installments: the individual payments associated with a pledge subscription

To fully reconcile a pledge, you will typically read from two endpoints: one for gifts and one for subscriptions and installments.

Step 1 — Retrieve pledge commitments

Use the Gifts API for the original contribution record. For known pledge contribution IDs, use the ids parameter as shown below. Replace the example IDs and API token with your own.

curl --location --request GET 'https://www.givecampus.com/api/gifts?ids=30046063,30034463' --header 'Authorization: Bearer <your-api-token>'

A date-range gift request returns only the states explicitly selected. paid=true does not return pending or recurring commitment records. For pending gifts, select pending=true with the intended start/end timestamps and time_field=created_at. There is no recurring=true state filter; retrieve known recurring parent IDs with ids. An ID-based request does not require start/end timestamps.

Requests are asynchronous. The initial response returns status: in_progress and a request_id. Request /api/results/{request_id} with the same authorization header until the response is completed, then retrieve its download_url. The examples below show fields from the downloaded result, not the initial response.

What you get

The contribution records selected by your request
donation_type == "pledge" identifies pledge records.
Use contribution state, timestamps and subscription metadata to distinguish the original commitment from payments. Do not assume contribution value is the total pledge.

Example: pledge commitment (truncated, representative fields only)

[
  {
    "donation_type": "pledge",
    "id": 30046063,
    "constituent_identifier": "00012345",
    "state": "pending",
    "project": {"id": 7612, "type": "Form", "name": "Pledge Form"},
    "subscription": {
      "id": 2107,
      "state": "pending",
      "period": "limited_months",
      "length": 24,
      "installment_number": 1,
      "indefinite": false,
      "subscription_type": "pledge"
    },
    "timestamps": {
      "created_at": 1755696545,
      "datetime_of_pledge": 1755696545
    },
    "value": "5000.0"
  }
]

Example: pledge with multiple installments (commitment view)

[
  {
    "donation_type": "pledge",
    "id": 30034463,
    "currency": "USD",
    "state": "recurring",
    "project": {"id": 7565, "type": "Form", "name": "FY25 Pledge Form"},
    "subscription": {
      "id": 1865,
      "state": "active",
      "period": "limited_months",
      "length": 6,
      "installment_number": 1,
      "subscription_type": "pledge"
    },
    "timestamps": {
      "created_at": 1737727819,
      "updated_at": 1750723712
    },
    "value": "833.33"
  }
]

Step 2 — Retrieve pledge installments and payment activity

Use the subscription ID from the contribution’s subscription.id to request the subscription and its installments. Replace 1865 with the desired subscription ID.

curl --location --request GET 'https://www.givecampus.com/api/recurring_subscriptions/1865' --header 'Authorization: Bearer <your-api-token>'

What you get

The subscription includes installment amounts, state, timestamps, and summary totals.
The bulk endpoint /api/recurring_subscriptions returns subscription records, but excludes pending subscriptions. Filter downloaded results for subscription_type == "pledge".
For a known pending subscription, use the single-subscription endpoint shown above. Retrieve results through /api/results/{request_id} as for a gift request.

Example: selected fields from a subscription result. The installment list is truncated; summary totals cover the complete subscription, not only the installments shown.

{
  "id": 1865,
  "subscription_type": "pledge",
  "frequency": "monthly",
  "max_charges": 6,
  "state": "active",
  "installment_amount": "833.33",
  "installments": [
    {
      "id": 30040886,
      "state": "authorized",
      "value": "833.33",
      "timestamps": {
        "checkout_at": 1748045311,
        "captured_at": 1748045310
      }
    },
    {
      "id": 30038309,
      "state": "refunded",
      "value": "833.33",
      "timestamps": {
        "deposited_at": 1743638535,
        "refunded_at": 1744852172
      }
    }
  ],
  "total": "4999.98",
  "total_charges": 5,
  "total_paid": "4166.65",
  "timestamps": {
    "created_at": 1737727843
  },
  "total_remaining": "833.33"
}

Data model tips

Join key: Match subscription.id on the contribution to id on the subscription.
Status: Keep contribution, subscription and installment states separate.
Amounts: Use the subscription’s total for a finite pledge’s total commitment, installment_amount for its scheduled payment amount, and total_paid / total_remaining for reported progress. Contribution value may represent an installment amount.
Dates: Use installment timestamps for payment activity and contribution datetime_of_pledge for the original pledge date.

Common states and meanings

Contribution state: Examples include pending and recurring; these describe the contribution, not subscription completion.
Subscription state: Examples include active, ended, canceled and recurring_failed. Pledge responses can also display scheduled for a future start or no payment when no payment method is provided.
Installment state: Examples include authorized, paid, pending_authorization, failed, refunded, disputed and charged_back.
Payment events: Capture and deposit are represented by captured_at and deposited_at timestamps. Do not filter for invented captured or deposited installment states.

Reconciliation pattern

Retrieve the pledge contribution and its subscription.id.
Retrieve that subscription and confirm subscription_type == "pledge".
Use its total, total_paid and total_remaining for the subscription’s reported amounts.
Review individual installment states and capture, deposit and refund timestamps for cash reconciliation. Subscription summary totals alone do not establish that every amount has settled or reached your bank.
Re-fetch after payments or refunds, and investigate discrepancies against the payment/deposit reports rather than summing fictional state names.

Best practices

Treat gift records as the source of truth for pledge creation metadata
Treat subscription records as the source of truth for payment activity
Do not infer payment success from authorization alone
Cache lightly and re-fetch subscriptions for near-real-time payment state

FAQ

How do I tell whether a pledge is fully paid? Compare the subscription’s total, total_paid and total_remaining, then review its state, installments and any refunds or payment failures. Do not compare the total with contribution value alone.
Where do I find payer details? Use the contribution’s payer and constituent fields; the subscription supplies its schedule and payment activity.
Can installments be refunded? Yes. Review installment state and refunded_at along with the related gift and payment reports.

For API access and the general request workflow, see GiveCampus API: Understanding the Basics.