---
title: "Create a donation"
description: "This donation will then have to be claimed i.e linked to a Charity."
canonical: https://www.charitips.com/docs/api-reference/create-donation
---

# Create a donation

`POST /v1/donations`

This donation will then have to be claimed i.e linked to a Charity.

**Authentication**: Bearer access token.

## Body

- `campaignId` (string, required, UUID): Id of the campaign
- `amount` (integer (int64), required, minimum 1): Donation amount in minor currency unit i.e cents.
- `externalId` (string): An optional internal id of your system e.g orderId or customerId. Can be used to link a donation to an entity in your system.
- `uniqueExternalId` (string): Similar to externalId but should be unique across all donations. Can be used to prevent duplicate donations.
- `donor` (PartialDonor): Only required for EMAIL, SLACK or POSTAL campaigns. Attach useful user data to donations for a better usage tracking. POSTAL campaigns require firstName, lastName, street, zip, city and country (FR only): the card is posted to this address.
  - `street` (string): Address line 1
  - `streetAddition` (string): Address line 2
  - `city` (string): City
  - `country` (string): Country alpha 2 ISO code
  - `zip` (string): Zip code
  - `firstName` (string): Donor's first name
  - `lastName` (string): Donor's last name
  - `email` (string, email address): Donor's email.
  - `companyName` (string): Donor's company name.
  - `phone` (string): Donor's phone number.
  - `birthdate` (string (date))
  - `pictureUrl` (string, URL): Donor's phone number.
  - `title` (string): Donor's job title.
  - `personalEmail` (string, email address): Donor's personal email.
  - `persona` (string): Persona of the donor. One of `CSR`, `MARKETING`, `HR`, `SALES`, `COMMUNICATION`, `PRODUCT`, `SMB`, `OTHER`.
  - `extraInfo` (string): Additional information about the donor.
  - `externalId` (string): Optional id to link this donor to an entity on your side.
  - `uniqueExternalId` (string): Similar to externalId but should be unique across all donors. Can be used to prevent duplicate donors
  - `slackId` (string): Donor's slack id. Required for SLACK campaigns.
- `language` (string): Locale to be used to communicate with the donor. Default to the campaign's language value. One of `fr`, `en`.
- `hasBeenCharged` (boolean): Restricted to B2C use cases. True if the donor has been charged for this donation. In this case, the fiscal receipt will be issued to the donor. Fiscal receipt issuance requires the donor property to be provided including all fiscal information such as names, address etc. This property is commonly used in a B2C scenario where your customers are charged for the donation.
- `withFiscalReceipt` (boolean): Restricted to B2C use cases. False if the donor has opted out of the fiscal receipt issuance. It's mostly used in a B2C scenario when the donor has been charged for a donation but doesn't want to provide their fiscal information. Default is campaign.withFiscalReceipt which default is true
- `charityId` (string, UUID): Id of the Charity to which the donation will be made. Optional can be set on claim after getting the user's choice.
- `parentDonationId` (string, UUID): Restricted to B2C use cases. Id of a claimed donation you funded on the same campaign, when the beneficiary tops it up with their own money. Requires hasBeenCharged and the charityId of that donation. The top-up is created claimed and is not sent.
- `sendingDate` (string (date-time)): Required for EMAIL and SLACK campaigns, when Charitips sends it to the donor. For POSTAL campaigns, the day the card is handed to La Poste (Paris time): a business day, from the next posting batch (16:00 Paris) up to a year ahead, defaults to the next posting batch. Delivery takes 2 to 3 business days.
- `hideAmount` (boolean): Hide the donation amount from the donor. Defaults to the campaign's defaultHideAmount value.

## Response 201

- `donationId` (string, required)
- `amount` (integer (int64))
- `externalId` (string)
- `uniqueExternalId` (string)
- `status` (DonationStatus, required) One of `PENDING`, `DONE`, `PROCESSED`, `CANCELED`.
- `secret` (string, required)
- `withFiscalReceipt` (boolean, required)
- `hasBeenCharged` (boolean, required)
- `claimedAt` (string (date-time))
- `validatedAt` (string (date-time))
- `processedAt` (string (date-time))
- `billingStatus` (BillingStatus, required) One of `PENDING`, `BILLED`, `PAID`.
- `hideAmount` (boolean, required)
- `billedOn` (DonationBilledOn, required) One of `CREATION`, `CLAIM`.
- `autoAssigned` (boolean)
- `expiryDate` (string (date-time))
- `sendingMode` (CampaignSendingMode, required) One of `MANUAL`, `EMAIL`, `PHYSICAL`, `SLACK`, `POSTAL`.
- `sendingDate` (string (date-time))
- `sendingStatus` (DonationSendingStatus, required) One of `PENDING`, `FAILED`, `DONE`.
- `externalSendingId` (string)
- `lastReminderId` (string)
- `message` (string)
- `reminderMessage` (string)
- `from` (string)
- `language` (Language, required) One of `fr`, `en`.
- `sharedOn` (SocialNetwork) One of `LINKEDIN`, `INSTAGRAM`, `FACEBOOK`, `TWITTER`, `WHATSAPP`.
- `ptoType` (PaidTimeOffType, required) One of `NONE`, `PAID_TIME_OFF`, `WORKING_TIME_REDUCTION`.
- `accountId` (string, required)
- `campaignId` (string, required)
- `charityId` (string)
- `recurringDonationId` (string)
- `transactionId` (string)
- `donorId` (string)
- `orderPlatformUserId` (string)
- `usageId` (string)
- `parentDonationId` (string)
- `parentVoteId` (string)
- `parentRecurringDonationId` (string)
- `createdAt` (string (date-time), required)
- `updatedAt` (string (date-time), required)

## Errors

- 400 `Campaign is a DISTRIBUTION one. Only votes can be created`: On a DISTRIBUTION campaign, people vote on a budget: create a vote, not a donation. See https://www.charitips.com/docs/api-reference/create-vote.md.
- 400 `donor is required for EMAIL campaigns.`: EMAIL campaigns send the donation to someone: pass `donor` with at least `email` and `firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Both donor.email and donor.firstName are required for email campaigns`: Pass both `donor.email` and `donor.firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `donor is required for SLACK campaigns.`: SLACK campaigns send the donation in Slack: pass `donor` with `slackId` and `firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Both donor.slackId and donor.firstName are required for slack campaigns`: Pass both `donor.slackId` and `donor.firstName`. See https://www.charitips.com/docs/api-reference/create-donation.md.
- 400 `Donations of an order campaign cannot be created through the API.`
- 400 `Bad Request`: The `campaignId` does not exist on your account and environment. Ids from the sandbox do not exist in production. See https://www.charitips.com/docs/api-reference/errors.md.
- 400 `charityId cannot be set for POSTAL campaigns: the recipient chooses the charity with the card.`
- 400 `Invalid parentDonationId`
- 400 `Insufficient campaign budget.`: This donation would take the campaign over its budget. Create a smaller donation, or use another campaign: the API does not change the budget of an existing campaign. See https://www.charitips.com/docs/api-reference/errors.md.
- 400 `A field is missing, has the wrong type, or is not part of the request schema.`: `message` lists every problem. Unknown fields are rejected, not ignored: remove them rather than sending extra data. See https://www.charitips.com/docs/api-reference/errors.md.
- 401 `Unauthorized`: The access token is missing, expired or invalid. Create a new one with your client id and secret, send it as `Authorization: Bearer <accessToken>`, then retry once. Sandbox tokens only work on api.sandbox.charitips.com. See https://www.charitips.com/docs/get-started/authentication.md.
- 402 `Missing payment method`: The account that pays for the donations (your (parent) account or a child account if they are billed directly) has no payment method. Add one in the dashboard, under Settings > Billing, then retry. On the sandbox, creating a single donation skips this check, but other calls can still return it, like activating a FIXED_AMOUNT campaign that is billed on order. See https://www.charitips.com/docs/concepts/billing-and-receipts.md#payment-methods.
- 403 `Campaign has ended.`: The campaign is COMPLETE or CANCELED: nothing can be created, claimed or cast on it any more. Use an active campaign. See https://www.charitips.com/docs/api-reference/list-campaigns.md.
- 403 `Campaign has to be activated first.`: Activate the campaign once it has its charities selection, then retry. See https://www.charitips.com/docs/api-reference/activate-campaign.md.
- 403 `Only recurring donations can be created for recurring campaigns.`: This campaign has a recurring frequency: create a recurring donation. See https://www.charitips.com/docs/api-reference/create-recurring-donation.md.
- 403 `Account not validated`: The account behind your credentials has not finished onboarding. Complete it in the dashboard, or contact us. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed.
- 403 `Account closed`: The account behind these credentials is closed: no token is issued and every call is refused, reads included. Contact Charitips to reopen it. See https://www.charitips.com/docs/api-reference/troubleshooting.md#calls-answer-403-account-not-active-account-not-validated-or-account-closed.
- 409 `Unique constraint failed on uniqueExternalId`: A resource with this uniqueExternalId already exists: your previous call succeeded. Fetch it with the list endpoint filtered by uniqueExternalId (donations, votes, donors) instead of creating it again; for recurring donations, keep the id you received at creation. See https://www.charitips.com/docs/api-reference/list-donations.md.

## Example

```bash
curl -X POST https://api.sandbox.charitips.com/v1/donations \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "<campaignId>",
    "amount": 2000,
    "uniqueExternalId": "<orderId>"
  }'
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/donations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "campaignId": "<campaignId>",
    "amount": 2000,
    "uniqueExternalId": "<orderId>"
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();
```

```python
import os, requests

response = requests.post(
    "https://api.sandbox.charitips.com/v1/donations",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
    json={
      "campaignId": "<campaignId>",
      "amount": 2000,
      "uniqueExternalId": "<orderId>"
    },
)
response.raise_for_status()
data = response.json()
```

## Response example (201, placeholder values)

```json
{
  "donationId": "<donationId>",
  "amount": 2000,
  "externalId": "<externalId>",
  "uniqueExternalId": "<uniqueExternalId>",
  "status": "PENDING",
  "secret": "<secret>",
  "withFiscalReceipt": false,
  "hasBeenCharged": false
}
```