---
title: "List donations"
description: "List all your claimed and unclaimed donations."
canonical: https://www.charitips.com/docs/api-reference/list-donations
---

# List donations

`GET /v1/donations`

List all your claimed and unclaimed donations.

**Authentication**: Bearer access token.

## Parameters

- `limit` (number): The max number of items to return.
- `cursor` (string): The id of the last item from the previous page. Used to fetch the next page.
- `createdAt_lt` (string (date-time)): Format: YYYY-MM-DDTHH:MM:SSZ.
- `createdAt_lte` (string (date-time)): Format: YYYY-MM-DDTHH:MM:SSZ.
- `createdAt_gt` (string (date-time)): Format: YYYY-MM-DDTHH:MM:SSZ.
- `createdAt_gte` (string (date-time)): Format: YYYY-MM-DDTHH:MM:SSZ.
- `campaignId_notIn` (string[], at least 1 items, UUID)
- `campaignId_in` (string[], at least 1 items, UUID)
- `campaignId` (string, UUID): Id of one your campaigns
- `status` (string): Filter on donation status One of `PENDING`, `DONE`, `PROCESSED`, `CANCELED`.
- `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.
- `accountId` (string, UUID): Id of the account. Only useful for Platform customers to filter donations by child accounts
- `includeUrl` (boolean): Include the url to the page where the donation can be claimed
- `includeAssets` (boolean): Include dynamic assets such as donation cards and QR code
- `includeMatchedDonations` (boolean): Include matched donations made by and charged to the beneficiary after using their free donation.
- `donorId` (string, UUID): Id of the donor.
- `includeChildDonations` (boolean): Include child donations i.e matched donations linked to a given donation
- `hasBeenCharged` (boolean): Include only donations which have been charged to the donor

## Response 200

- `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 `Invalid parameter includeDonor`: `includeDonor` is not available with API credentials. Remove it, and read the donor with its own endpoint. See https://www.charitips.com/docs/api-reference/get-donor.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.
- 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.

## Example

```bash
curl -X GET https://api.sandbox.charitips.com/v1/donations \
  -H "Authorization: Bearer $CHARITIPS_TOKEN"
```

```javascript
const response = await fetch('https://api.sandbox.charitips.com/v1/donations', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CHARITIPS_TOKEN}`,
  },
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();
```

```python
import os, requests

response = requests.get(
    "https://api.sandbox.charitips.com/v1/donations",
    headers={"Authorization": f"Bearer {os.environ['CHARITIPS_TOKEN']}"},
)
response.raise_for_status()
data = response.json()
```

## Response example (200, placeholder values)

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