GiveCampus API - Requesting Pledge Data

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 to fetch gifts, then filter for pledge commitments.

curl --location --request GET 'https://www.givecampus.com/api/gifts?start=1721606400&end=1724543999&paid=true>'' \\
  --header 'Authorization: Bearer <your-api-token>'

(Please note the example above has has specific timestamps. If you simply copy/paste, you'll want to make that adjustment).

What you get

• All gifts, including pledge commitments
• Identify pledges by checking donation_type == "pledge"
• Useful fields include pledge state, value, timestamps, and subscription metadata

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": "4999.98"
  }
]

Step 2 — Retrieve pledge installments and payment activity

Use the Subscriptions API to fetch the pledge subscription and its installments.

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

What you get

• Recurring subscriptions with installment arrays
• Each installment includes value, state, and timestamps for lifecycle events

Example: subscription with installments (truncated)

{
  "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,
    "end_date": "2025-07-01",
    "last_run_date": "2025-06-23",
    "next_run_date": "2025-07-24"
  }
}

Data model tips

• Join key: Use subscription.id from the commitment record to match the subscription from the Subscriptions API
• Pledge status: Use the commitment state for pledge lifecycle and each installment state for payment outcomes
• Amounts: value on the commitment is the pledged total. Installment values sum toward the total
• Dates: Prefer installment timestamps when reporting payment activity. Use commitment datetime_of_pledge for the original pledge date

Common states and meanings

• Commitment states
  • pending: pledge recorded but not yet on a recurring schedule
  • recurring: pledge is active with scheduled installments
  • completed: all installments satisfied
  • canceled: pledge canceled before completion
• Installment states
  • authorized: payment authorized, may settle later
  • deposited: funds deposited
  • refunded: payment refunded in full
  • failed: payment attempt failed

Reconciliation pattern

1. Fetch commitments and filter for donation_type == "pledge"
2. For each pledge, read subscription.id
3. Fetch the subscription by id and iterate installments
4. Compute totals
   • Total pledged: use commitment value
   • Total paid: sum installments with states deposited or captured
   • Total remaining: pledged minus paid

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 if a pledge is fully paid?
  • Compare commitment value to total_paid on the subscription and confirm no remaining scheduled installments
• Where do I find the payer details?
  • Commitment includes payer name and email. Use subscription for the latest payment method context
• Can installments be refunded?
  • Yes. Check installment state == "refunded" and use installment timestamps for refund timing

Support

If you have questions contact support@givecampus.com