---
title: "Campaigns"
description: "What a campaign holds, the settings that shape it (duration, budget, donations or votes, recurrence), its statuses, and when it is billed."
canonical: https://www.charitips.com/docs/concepts/campaigns
---

# Campaigns

> What a campaign holds, the settings that shape it (duration, budget, donations or votes, recurrence), its statuses, and when it is billed.

A campaign holds the settings of one giving flow: which charities people choose from, how long it runs, with what budget, and how the charity is picked. Every donation, vote and recurring donation belongs to a campaign.

> **In short**
>
> - A campaign is created `PENDING` and takes donations only once activated. Closing it is final.
> - It runs until you close it (`PERMANENT`, the default) or until an end date (`TIME_BASED`).
> - Donations are billed as they are used (`FREE_AMOUNT`, the default), or the whole budget is billed when the campaign starts (`FIXED_AMOUNT`).
> - Each donation has its own amount (`FACE_VALUE`, the default), or votes share a fixed budget between charities (`DISTRIBUTION`).
> - One campaign per flow is the usual start. Add campaigns when the settings, the branding or the reporting must differ.

## What a campaign decides

### Which charities

The `charitiesSelectionId` points to the charities people choose from. A campaign cannot be activated without one: `400 No charity selection linked to this campaign`. See [Charities and selections](https://www.charitips.com/docs/concepts/charities.md).

### How long it runs: `type`

- `PERMANENT` (default): it runs until you close it. Suited to giving built into your product, like a donation with every order.
- `TIME_BASED`: set an `endDate`. Once the end date has passed, a scheduled job closes it. Suited to a moment: a day, a season, a year-end budget. See [A campaign for a date](https://www.charitips.com/docs/use-cases/campaign-for-a-date.md).

### How much: `amountType`

- `FREE_AMOUNT` (default): no budget set in advance. Each donation is billed as it is used: when it is created, or when a charity is chosen if you set `donationsBilledOn` to `CLAIM`.
- `FIXED_AMOUNT`: you set a `budget` in cents (`400 Budget is required for FIXED_AMOUNT campaigns` otherwise). The whole budget is billed when the campaign is activated, and donations can never exceed it: past it, creating a donation answers `400 Insufficient campaign budget.` Raising the budget later bills the difference. With `budgetFrequency` (an ISO 8601 recurring interval), a new budget period starts and is billed again with each monthly invoice.

### Who decides where the money goes: `donationType`

- `FACE_VALUE` (default): each donation has its own amount. You create a donation, then the person picks the charity (the claim), or you pass the charity at creation.
- `DISTRIBUTION`: people vote instead. The budget is shared between charities in proportion to the votes and their weights. A `DISTRIBUTION` campaign must also be `FIXED_AMOUNT`, and only takes votes: a donation answers `400 Campaign is a DISTRIBUTION one. Only votes can be created`. See [Customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md).

### Monthly giving

A campaign for recurring donations takes only recurring donations, created with [Create a recurring donation](https://www.charitips.com/docs/api-reference/create-recurring-donation.md); a one-off donation on it answers `403 Only recurring donations can be created for recurring campaigns.`

Create it with `frequency`, an ISO 8601 recurring interval, for example `R/2026-11-01/P1M` for every month from 1 November. Such a campaign is `FREE_AMOUNT`: with `FIXED_AMOUNT`, creating it answers `400 Recurring campaigns must be FREE_AMOUNT campaigns`.

If creating a recurring donation answers `403 Recurring donations can only be created for recurring frequency campaigns.`, the campaign has no `frequency`: set one with [Update a campaign](https://www.charitips.com/docs/api-reference/update-campaign.md) while it is still pending. See [Monthly giving by your users](https://www.charitips.com/docs/use-cases/recurring-donations.md).

### The other settings

- `donationValidityPeriod`: how long a donation waits for its charity, `2 months` by default, one year at most. See [Donation lifecycle](https://www.charitips.com/docs/concepts/donation-lifecycle.md).
- `withDonationsValidation`: each donation waits for your approval ([Validate a donation](https://www.charitips.com/docs/api-reference/validate-donation.md)) before it counts.
- `sendingMode`: `MANUAL` by default, your product shows the donation. With `EMAIL` or `SLACK`, Charitips sends it on the donation's `sendingDate` and reminds the person until they choose. Each donation needs a `donor` (`400 donor is required for EMAIL campaigns.` otherwise) and a `sendingDate` (`400 sendingDate is required for EMAIL and SLACK campaigns.` otherwise). Set the reminders with [Update campaign reminders](https://www.charitips.com/docs/api-reference/update-campaign-reminders.md).
- `fiscalReceiptType`: `YEARLY` (default) groups receipts once a year; `SINGLE_DONATION` issues them when the campaign closes. See [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md).
- `defaultHasBeenCharged`: the donors pay every donation of the campaign with their own money, as with `hasBeenCharged` on each donation. It needs the B2C use case, is set at creation only, and is required for `givingTarget`.
- `audienceType`: `PRIVATE` by default. A `PUBLIC` campaign, open to anyone without signing in, must be `FIXED_AMOUNT` and `DISTRIBUTION` (unless `defaultHasBeenCharged` is set).
- `title`, `description`, `logoUrl`, `titleColor`, `accentColor`, `language`, `slug`: what the campaign's pages and emails show. A `slug` already in use answers `409 Slug already used`.
- Matching: once the campaign exists, [Update a donation matching](https://www.charitips.com/docs/api-reference/update-donation-matching.md) sets a rate and budgets. See [Donation matching](https://www.charitips.com/docs/use-cases/donation-matching.md).

```bash
curl -X POST https://api.sandbox.charitips.com/v1/campaigns \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Year-end budget",
    "charitiesSelectionId": "<charitiesSelectionId>",
    "type": "TIME_BASED",
    "endDate": "2026-12-31",
    "amountType": "FIXED_AMOUNT",
    "budget": 1000000
  }'
```

## The life of a campaign

1. **Created** (`PENDING`): it takes no donation yet, `403 Campaign has to be activated first.`
2. **Activated** (`ACTIVE`) with [Activate a campaign](https://www.charitips.com/docs/api-reference/activate-campaign.md): it takes donations, votes or recurring donations.
3. **Closed** (`COMPLETE`), by you with [Close a campaign](https://www.charitips.com/docs/api-reference/close-campaign.md) or, for a `TIME_BASED` one, after its end date. Every new donation, claim or vote then answers `403 Campaign has ended.`

Closing cannot be undone. When a campaign closes:

- donations still waiting for a charity are assigned to one automatically (with `donationsBilledOn: CLAIM`, only those already billed);
- on a `FIXED_AMOUNT` campaign, the part of the budget not yet given becomes donations too, assigned the same way.
- once the campaign is paid, the money goes to the charities, a report is generated, and receipts are issued if `fiscalReceiptType` is `SINGLE_DONATION`.

### What activation checks

Activation is where most setup problems show up:

- `400 No charity selection linked to this campaign`: set `charitiesSelectionId` first.
- `402 No active subscription found` (`NO_ACTIVE_SUBSCRIPTION`): the account billed for the campaign has no active monthly subscription. That is your account, or a child account when they are billed directly.
- `400 No budget set for this campaign` (`MISSING_BUDGET`), on a `FIXED_AMOUNT` campaign.
- `402 Missing payment method` (`MISSING_PAYMENT_METHOD`), on a `FIXED_AMOUNT` campaign, when the billed account has no payment method (not checked on the sandbox).
- `400` with `PAYMENT_CARD_AMOUNT_LIMIT_EXCEEDED` or `SDD_AMOUNT_LIMIT_EXCEEDED`: the budget is above what a card or a direct debit can pay at once.
- `403 Account not validated`: your account has not finished its onboarding.
- `403 Campaign has ended.`: the campaign is `COMPLETE` or `CANCELED`, and cannot be activated again.

When the budget is paid by bank transfer, activation returns the campaign still `PENDING`: it becomes `ACTIVE` once the invoice is paid. Calling activate again meanwhile answers `403 Campaign is waiting for payment`.

## One campaign or several

One campaign per flow fits most integrations. Create more when:

- the branding (logo, colours, texts) differs between two experiences;
- you want separate figures, by team, theme or product line, or you already have a matching notion on your side;
- the settings differ: a permanent flow next to a time-limited one, donations next to votes.

With account hierarchy enabled, each business customer has its own campaigns, created with its `accountId`. See [Account hierarchy](https://www.charitips.com/docs/concepts/account-hierarchy.md).

## What developers handle

- Keep the `campaignId` (for donations and votes) and the `publicKey` (for widgets) returned on creation.
- Read a campaign's figures with [Get campaign metrics](https://www.charitips.com/docs/api-reference/get-campaign-metrics.md).
- The `campaign_create` and `campaign_update` webhook events report every change, including activation and closing. See [Webhooks configuration](https://www.charitips.com/docs/webhooks/configuration.md).

## Related

[Donation lifecycle](https://www.charitips.com/docs/concepts/donation-lifecycle.md), [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md), [Account hierarchy](https://www.charitips.com/docs/concepts/account-hierarchy.md), [Create a campaign](https://www.charitips.com/docs/api-reference/create-campaign.md), [Update a campaign](https://www.charitips.com/docs/api-reference/update-campaign.md).