Understanding Contributions endpoints in the REST Services

Nick Reilingh — Wed, 20 May 2020 06:22:55 GMT

Current Revision posted to Community Docs Wiki by Nick Reilingh on 5/20/2020 6:22:55 AM

As of 15.1.10:

CRM - Constituent Contributions

API Method/Endpoint:

GetAll: GET CRM/Contributions?constituentId={constituentId}

Useful for retrieving existing contributions for a constituent.

Note: ReferenceNumber in the response object may be referred to as Id or LineItemId in other resources' responses.

Finance - Finance Contributions

API Methods/Endpoints:

Get: GET Finance/Contributions/{contributionId}
GetAll: GET Finance/Contributions?planId={planId}

Useful for retrieving information about just a single contribution at a time, or all of the contributions for a particular plan.

Note that the response type is slightly different between this and the Constituent Contributions resource.

TXN - Contributions

These endpoints CANNOT be used. They are present in order to be able to trigger interceptor plugins at certain times. (Interceptors must hook themselves into API methods).

Web - Cart

API Methods/Endpoints:

AddContribution: POST Web/Cart/{sessionKey}/Contributions
UpdateContributionCustomData: PUT Web/Cart/{sessionKey}/Contributions/{lineItemId}/CustomData/{customId}
RemoveContribution: DELETE Web/Cart/{sessionKey}/Contributions/{lineItemId}
RemoveContributionCustomData: DELETE Web/Cart/{sessionKey}/Contributions/{lineItemId}/CustomData/{customId}

These endpoints can be used to add/remove contribution to a cart and optionally modify custom data for that contribution. The LineItemId will be returned by the POST used to create the contribution.

CustomData for contributions must be preconfigured before use; this is described in the documentation: Contribution Custom Data Tab.

NOTE that a cart is equivalent to a ticket order in the client, so advanced contribution functionality found in the contributions module (like pledges) is not possible. Basic membership renewals and upgrades are supported, but not much else is. The traditional workaround for this is to save contribution income as on-account monies and create a CSI for later manual processing by an agent. In the SOAP API, this was built-in functionality, but in REST you must create the CSI yourself (CRM/Issues) and apply the contribution amount as new on-account money using AddOnAccount (POST Web/Cart/{sessionKey}/OnAccount).

In the event that you are adding a contribution for a cart that will be displayed by TNEW, please see Custom Contributions in TNEW for additional requirements.

Tags: contributions, REST API