Add Giving API support for imported donation failure states distinct from refunds

[michaelhvisser]

Related Product
Giving

Is your feature request related to a problem? Please describe.
We import historical giving data from third-party providers into Planning Center Giving through the Giving API. Some providers expose transaction outcomes that distinguish between donations that were successfully
refunded and donations that ultimately failed.

A concrete example is Subsplash, which can export statuses such as refunded, failed, and disputed. In the current Giving API, we can detect those statuses during import, but the only write-side action we
have for an already-created donation is POST /giving/v2/donations/{donation_id}/issue_refund.

That creates a problem for imports and reconciliations because we cannot preserve the original provider semantics. Today, if we want the imported data in Planning Center to reflect a non-successful transaction,
the only API option appears to be to refund the donation. That conflates distinct source states:

• refunded: a completed donation that was later refunded
• failed: a donation/payment attempt that did not complete successfully
• disputed: a chargeback/dispute-like outcome that is not necessarily the same thing as a normal refund

As a result, integrations have to either:

• map multiple source statuses into the same Planning Center refund action, which loses fidelity, or
• leave those records in a manual/off-platform state and maintain provider-specific exceptions in our import logic.

Describe the solution you'd like
We would like the Giving API to expose a supported way to represent failed or otherwise non-refund negative outcomes distinctly from refunds.

Any of the following would solve the problem:

• Allow integrations to explicitly set a donation outcome/status through the API for imported batch donations, including a value such as failed
• Add a dedicated donation action such as mark_failed, void, mark_disputed, or similar
• Provide a documented import-specific field or action that maps third-party provider outcomes into the correct Giving state model without requiring everything to become a refund

At minimum, it would help if the API supported a distinct write path for:

• refunded donations
• failed donations

Ideally, the API would also clarify how disputed or chargeback-like outcomes should be represented for imported donations.

Describe alternatives you've considered
We have considered these alternatives, but each has drawbacks:

• Treat every non-success outcome as a refund using issue_refund
  • This is inaccurate for provider records that were failed rather than refunded
• Skip automatic handling for failed rows and require manual reconciliation in Planning Center
  • This adds operational overhead and prevents consistent provider imports
• Store the original provider status only in our own system and import a simplified result into Planning Center
  • This causes data divergence between our source import data and what admins see in Giving
• Encode the original status in notes or labels
  • This preserves some context, but it does not provide the correct donation lifecycle/state in the Giving model

Additional context
We reviewed the current public Giving API documentation and found:

• payment_status is documented as a readable donation attribute with values including pending, succeeded, and failed
• payment_status does not appear to be assignable on donation create/update
• the only donation action we found for this use case is POST /giving/v2/donations/{donation_id}/issue_refund

Because of that, it appears the public API currently supports "refunded" as a write action, but not "failed" as a distinct imported outcome.

This matters for provider integrations because we want to update our provider mappings according to the API’s supported state model rather than hard-coding inaccurate assumptions. If the intended model is
different, documented guidance on how imported provider statuses should map into Giving would also be very helpful.

I have..

• Reviewed the documentation found at https://developer.planning.center/docs
• Searched for previous issues asking for this feature request
• Removed all private information from this issue (credentials, tokens, emails, phone numbers, etc.)
• Reviewed my issue for completeness

[github-actions]

Potentially Related Issues

I found some existing issues that may be related to this one. Please check if any of them address your question before waiting for a response:

🟣 #1416 — Giving API seems to be out of date (Closed)

Summary: User reported the Giving API appeared outdated (last breaking change in 2019) and was missing features like joint donors and memo field. PCO clarified they continue adding features without breaking changes, and confirmed the memo field had just been added.

Key discussion points:

• The API version date (2019) caused confusion about whether the API was being actively maintained
• PCO continues to add features to the existing API version without creating breaking changes
• Joint donors feature was acknowledged as high priority but not yet available

Resolution: Resolved by PCO clarification that the API is actively maintained despite the 2019 version date. New features like the memo field are added incrementally. This demonstrates PCO's approach to API evolution - they add capabilities within existing versions rather than frequent versioning, which is relevant context for understanding how donation status features might be added.

🟣 #1408 — Please expose the new donation memo field (Closed)

Summary: User requested the new donation memo field be exposed in the API after it was added to the web interface. PCO added it as a read-only field in the API documentation.

Key discussion points:

• New features in the web UI don't automatically appear in the API simultaneously
• PCO's approach is to add read-only attributes first before considering write capabilities
• The memo field was successfully added to Donation responses as read-only

Resolution: PCO added the memo field to all Donation responses in the API documentation as a read-only attribute. This case shows PCO's pattern of incrementally adding fields to existing API versions and prioritizing read access before write access, which provides useful context for how payment_status or failure states might be approached.

🟣 #1400 — Rate limit guidance for large-scale donation migration 100k+ records (Closed)

Summary: User sought guidance for migrating 100k+ historical donations via API, concerned about rate limits and lack of bulk import. PCO confirmed no bulk endpoint exists and provided best practices for large-scale imports.

Key discussion points:

• No bulk donation creation endpoint exists or is planned in the immediate future
• Recommended approach includes local caching of person IDs, respecting Retry-After headers, and background workers
• Batch size matters for performance - keeping batches small (e.g., monthly) improves request speed
• Large migrations require several days even with optimization
• Community member shared successful experience with 30k records using self-throttling at 50 calls per 5 seconds

Resolution: PCO confirmed no bulk donation endpoint is available and provided detailed guidance on optimizing individual donation creation requests. This is relevant to the new issue because it confirms the current API architecture requires individual donation manipulation, making the lack of granular status control (failed vs. refunded) even more impactful for import scenarios.

🟣 #1434 — Error creating donations (Closed)

Summary: User encountered 403 errors when creating donations despite being an organization admin. The issue was a duplicate of #1431 and resolved by a bug fix deployment.

Key discussion points:

• User could create batches but not donations, suggesting permission checking happened at different levels
• Initial support response incorrectly suggested issue was with person ID vs giving number
• Error was actually caused by a backend permissions bug affecting administrators
• Issue affected multiple users with proper credentials

Resolution: Resolved by a PCO bug fix deployed on March 16, 2026. The issue was a backend permissions checking problem, not incorrect API usage. This demonstrates that donation creation permissions have recently had issues, which provides context that the donation lifecycle and permission system may still be evolving.

---

This comment was generated automatically. If none of these match your issue, no action is needed — a team member will review your issue soon.