Giving API: Cannot update labels on Planning Center online-giving donations via Donation PATCH

[mattmeccadata]

Related Product
API / Giving

Describe the question
I’m trying to update the labels on Giving donations through the API.

According to the Giving Donation API documentation, PATCH /giving/v2/donations/{id} supports replacing associated labels by passing a labels key in the relationships object.

This works for donations that were manually entered / batch processed in Planning Center Giving. However, it fails with a 403 Forbidden for donations that were submitted directly through a Planning Center donation form / online giving flow.

The online-giving donations can be read successfully, and their labels can be listed successfully, but attempting to update the donation’s labels through the documented donation PATCH endpoint fails.

The error returned is:

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have access to this resource",
      "meta": {
        "description": "User with id _<id>_ cannot update AppGraph::V2019_10_18::Vertices::DonationVertex with id _<id>_."
      }
    }
  ]
}

The API credentials being used are account-admin credentials with Giving access. The same credentials can successfully update labels on manually entered / batch donations.

My question: Is there a supported API method to add/remove existing labels from donations that were processed through Planning Center online giving? Or are Planning Center-source donations intentionally not updateable via the donation PATCH endpoint, even for label-only relationship changes?

What have you tried that worked?

• GET /giving/v2/donations/{donation_id} works.
• GET /giving/v2/donations/{donation_id}/labels works for the affected online-giving donations.
• PATCH /giving/v2/donations/{donation_id} with relationships.labels works for donations that were manually entered / batch processed.
• The same API credentials successfully update labels on manually entered / batch donations.

Example successful label read for an affected online-giving donation:

GET /giving/v2/donations/{id}/labels

returns 200 with labels including:

[
  {
    "type": "Label",
    "id": "_<id>_",
    "attributes": {
      "slug": "acknowledge-needs"
    }
  },
  {
    "type": "Label",
    "id": "_<id>_",
    "attributes": {
      "slug": "source-planning-center"
    }
  }
]

What have you tried that didn't work?

1. Updating labels through the documented donation PATCH endpoint:

PATCH /giving/v2/donations/{id}
Content-Type: application/json

with a payload shaped like:

{
  "data": {
    "type": "Donation",
    "id": "_<id>_",
    "relationships": {
      "labels": {
        "data": [
          { "type": "Label", "id": "_<id>_" },
          { "type": "Label", "id": "_<id>_" },
          { "type": "Label", "id": "_<id>_" },
          { "type": "Label", "id": "_<id>_" },
          { "type": "Label", "id": "_<id>_" }
        ]
      }
    }
  }
}

This fails only for donations processed through Planning Center online giving, with:

{
  "status": "403",
  "title": "Forbidden",
  "detail": "You do not have access to this resource",
  "meta": {
    "description": "User with id _<id>_ cannot update AppGraph::V2019_10_18::Vertices::DonationVertex with id _<id>_."
  }
}

2. Trying a JSON:API-style relationship endpoint:

POST /giving/v2/donations/_<id>_/relationships/labels

This returns:

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "The resource you requested could not be found"
    }
  ]
}

3. Trying to POST to the labels association endpoint:

POST /giving/v2/donations/_<id>_/labels

This returns a 403, and appears to be interpreted as an attempt to create a new Label rather than attach an existing Label:

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have access to this resource",
      "meta": {
        "description": "User with id _<id>_ cannot create a Label."
      }
    }
  ]
}

Additional context

The goal is to automate acknowledgment workflow labels on donations.

Current workflow:

• Donations with label acknowledge-needs should have that label removed.
• Label acknowledge-done should be added.
• The label update works for manually entered / batch donations.
• The label update fails for donations submitted directly through Planning Center online giving.
• The affected online-giving donations include a label like source-planning-center.

I’m trying to determine whether this is expected behavior, a permissions issue, or whether there is another supported endpoint for assigning existing labels to online-giving donations without updating the full Donation resource.

I have..

• Reviewed the documentation found at https://developer.planning.center/docs
• Searched for previous issues answering this question
• 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:

🟣 #1432 — 403 Forbidden when creating pledge via Giving API despite administrator permissions (Closed)

Summary: Users experienced 403 Forbidden errors when creating pledges via the Giving API despite having administrator permissions. This relates to the new issue as both involve 403 errors on write operations (PATCH/POST) while read operations succeed, suggesting a pattern of permission-checking issues in the Giving API.

Key discussion points:

• Authentication worked correctly - GET /giving/v2/me returned administrator permissions and read operations succeeded
• Multiple users with Giving administrator permissions experienced the same 403 error
• Error message pattern was identical: 'You do not have access to this resource' with user/resource details in meta

Resolution: This was a backend bug in Planning Center's permission checking system, not a user error. A fix was deployed on March 17, 2026 that corrected the permission validation logic, allowing administrators to create pledges as expected.

🟣 #1431 — Unable to create pledges via API – POST /giving/v2/people/{personid}/pledges returns 403 (Closed)

Summary: Users could not create pledges via POST /giving/v2/people/{person_id}/pledges, receiving 403 Forbidden despite successful authentication and admin permissions. This directly relates to the new issue's pattern of write operations failing with 403 while read operations succeed with the same credentials.

Key discussion points:

• Authentication was confirmed working - People API and Giving API read requests returned 200
• Tested with multiple admin users and tokens, all receiving the same 403 error
• Tested both via Apps Script and direct curl with HTTP Basic authentication
• PCO staff member acknowledged seeing a potential issue and discussed with team

Resolution: Resolved by a backend fix deployed on March 17, 2026. The issue was a permission-checking bug on Planning Center's side. After the fix, pledges could be created successfully. Additionally, PCO simplified the API by removing the requirement to include the Person relationship in the request body since it's already in the URL path.

🟣 #1434 — Error creating donations (Closed)

Summary: User received 403 Forbidden when creating donations with error 'User with id XXXXXXXX cannot create a Donation.' This is closely related to the new issue as both involve 403 errors on write operations despite having proper admin permissions and successful read access.

Key discussion points:

• User could create batches but not donations despite being organization admin with full access
• PCO help desk initially suggested an ID mismatch issue, but this was not the root cause
• User was unaware that issue Unable to create pledges via API – POST /giving/v2/people/{person_id}/pledges returns 403 #1431's fix on March 16, 2026 had resolved the underlying permission bug

Resolution: Resolved by the same backend permission fix that was deployed on March 16, 2026 to address issue #1431. The user's script worked successfully once they retried after becoming aware of the fix. This was not an API usage error but a backend permission validation bug.

🟣 #1360 — Unable to Post donations via API, 403 error (Closed)

Summary: User received 403 Forbidden when attempting to POST donations to the Giving API despite successful authentication and proper permissions. While this shares the 403 error pattern with the new issue, the root cause was different - incorrect endpoint usage rather than a permissions bug or source-based restriction.

Key discussion points:

• User had proper authentication (200 response), included User-Agent header, had bookkeeping access and admin permissions
• Could successfully create batches and query People API
• Was attempting to POST to /giving/v2/donations directly

Resolution: The issue was resolved by using the correct nested endpoint /giving/v2/batches/{batch_id}/donations instead of the top-level /giving/v2/donations endpoint. Creating donations requires using the batch-specific endpoint, though reading and updating can use the top-level endpoint. This is documented in the Donation API docs under the 'Creating' section.

---

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

[ojameso]

Thanks @mattmeccadata for surfacing this issue. This is actually a known behavior that we plan to address soon. Currently, the only other way to update labels on these donations is to do so manually on the admin-ui. Thanks for your patience!

[mattmeccadata]

Hi @ojameso do you have any update or expected timeline on this issue? Appreciate any info you might have, as we have a workflow that's currently limited by this behavior. Thanks!

[mattmeccadata]

Bump

[molawson]

Hi @mattmeccadata. While this is something we intend to address, we don't have any specific timelines we can share at this point. I'm going to close this issue for now, but as soon as we've made the change we'll update you here. Thanks!