--- title: "Donation lifecycle" description: "How a donation goes from created to claimed for a charity, then paid to it, what happens when nobody chooses, and what you can still change or delete." canonical: https://www.charitips.com/docs/concepts/donation-lifecycle --- # Donation lifecycle > How a donation goes from created to claimed for a charity, then paid to it, what happens when nobody chooses, and what you can still change or delete. A donation is created with an amount, gets its charity when someone chooses one (the claim), then Charitips pays it to that charity. Its `status` tells you where it stands, and a webhook tells your server each time it moves. > **In short** > > - `PENDING`: created, no charity yet (or waiting for your approval). > - `DONE`: the charity is chosen and the donation counts. > - `PROCESSED`: Charitips has transferred the money to the charity. > - A donation nobody claims is not lost: it is assigned to a charity automatically when its campaign ends, or, on most permanent campaigns, once it has expired. > - You can change the amount only while a donation is neither claimed nor billed, and delete it until it is invoiced. ## The steps 1. **Created**, `PENDING`. Your server calls [Create a donation](https://www.charitips.com/docs/api-reference/create-donation.md) with the campaign, the amount in cents and your own id in `uniqueExternalId`. If you already know the charity, pass `charityId` and the donation is `DONE` at once (on a campaign without validation). 2. **Claimed**, `DONE`. The person picks a charity and your server calls [Claim a donation](https://www.charitips.com/docs/api-reference/claim-donation.md) with its `charityId`. They can also pick it on a Charitips page: the donation's page (its link comes with `includeUrl` on [Get a donation](https://www.charitips.com/docs/api-reference/get-donation.md)), the email sent on an `EMAIL` campaign, or the charity selection widget. 3. **Validated**, only on a campaign with `withDonationsValidation`. After the claim the donation stays `PENDING` until you call [Validate a donation](https://www.charitips.com/docs/api-reference/validate-donation.md), which may set the final `amount`. Then it is `DONE`. 4. **Processed**, `PROCESSED`. Once the donation is paid and its charity known, Charitips transfers the money to the charity and records the date in `processedAt`. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations//claim \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "charityId": "" }' ``` Each step sends a webhook: `donation_create` when the donation is created, then `donation_update` on every change of status, with the donation and the fields that changed. See [Webhooks configuration](https://www.charitips.com/docs/webhooks/configuration.md). ## When nobody chooses Every donation gets an `expiryDate` when it is created, from the campaign's `donationValidityPeriod` (2 months by default, one year at most). Once it has passed, Charitips may choose for the person. - **On a permanent campaign** billed on creation, without a fixed budget, votes or validation, a donation still unclaimed after its expiry date, and already paid, is assigned to a charity automatically. - **When a campaign closes**, by you or after its end date, every donation still waiting for a charity is assigned the same way (on a campaign billed on claim, only those already billed). An assigned donation has `autoAssigned` set to `true`. The money always reaches a charity of the campaign. ## Changing or removing a donation - **Amount:** [Update a donation](https://www.charitips.com/docs/api-reference/update-donation.md) changes it while the donation is `PENDING` and not billed. Your `externalId` and `uniqueExternalId` can change at any time. - **Delete:** [Delete a donation](https://www.charitips.com/docs/api-reference/delete-donation.md) works until the donation is invoiced. Use it when an order is cancelled before your next invoice. - **Not validated:** on a campaign with `withDonationsValidation`, a donation still `PENDING` and not billed seven days after its creation is deleted by a daily job. - **Cancelled:** `CANCELED` is set, on a campaign with validation, for a donation you refuse before it is billed. ## What can stop a donation from being created - `403 Campaign has to be activated first.` or `403 Campaign has ended.`: check the campaign status. See [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md). - `400 Insufficient campaign budget.` (`INSUFFICIENT_CAMPAIGN_BUDGET`): a `FIXED_AMOUNT` campaign has no budget left for this amount. - `400 Campaign is a DISTRIBUTION one. Only votes can be created`: this campaign takes votes. - `402 Missing payment method` (`MISSING_PAYMENT_METHOD`), in production: the account billed for the donations has no payment method. - `403 Providing hasBeenCharged and withFiscalReceipt is only enabled for customers with a B2C use case.`: see [Your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md). - `409`: a donation with the same `uniqueExternalId` already exists in this account. Your retry is safe: find the existing one with the `uniqueExternalId` filter of [List donations](https://www.charitips.com/docs/api-reference/list-donations.md). The full list, per call, is on [Errors](https://www.charitips.com/docs/api-reference/errors.md). ## Donations linked to another one A donation can have child donations, linked by their `parentDonationId`: - the part your company adds on a campaign with [donation matching](https://www.charitips.com/docs/use-cases/donation-matching.md), created when the user's donation becomes `DONE`; - the top-up a person pays with their own money after claiming a donation you funded, on a Charitips page. [List donations](https://www.charitips.com/docs/api-reference/list-donations.md) leaves them out unless you pass `includeMatchedDonations`; [Get a donation](https://www.charitips.com/docs/api-reference/get-donation.md) returns them with `includeChildDonations`. ## Billing and receipts along the way - A donation is billed when it is created, or when it is claimed if the campaign has `donationsBilledOn: CLAIM`. On a `FIXED_AMOUNT` campaign the budget is billed instead, at activation. Its `billingStatus` goes from `PENDING` to `BILLED`, then `PAID`. - A donation your company funds is part of the company's fiscal receipt. A donation the user paid (`hasBeenCharged: true`) has its own receipt in the donor's name: [Create a donation fiscal receipt](https://www.charitips.com/docs/api-reference/create-donation-fiscal-receipt.md) works once it is `PROCESSED`, and `fiscalreceipt_generated` tells you when a receipt is ready. See [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md). ## Votes follow the same path On a `DISTRIBUTION` campaign, [Create a vote](https://www.charitips.com/docs/api-reference/create-vote.md), then [Cast a vote](https://www.charitips.com/docs/api-reference/cast-vote.md) for a charity (`409 Vote already casted` the second time), and [Validate a vote](https://www.charitips.com/docs/api-reference/validate-vote.md) when the campaign validates them. The budget is shared between charities in proportion to the votes. See [Customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md). ## Related [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md), [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md), [Your first donation](https://www.charitips.com/docs/get-started/first-donation.md), [Errors](https://www.charitips.com/docs/api-reference/errors.md).