Concepts

Campaigns

Build with AI

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.

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.

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.

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.

Monthly giving

A campaign for recurring donations takes only recurring donations, created with Create a recurring donation; 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 while it is still pending. See Monthly giving by your users.

The other settings

• donationValidityPeriod: how long a donation waits for its charity, 2 months by default, one year at most. See Donation lifecycle.
• withDonationsValidation: each donation waits for your approval (Validate a donation) 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.
• fiscalReceiptType: YEARLY (default) groups receipts once a year; SINGLE_DONATION issues them when the campaign closes. See Billing and fiscal receipts.
• 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 sets a rate and budgets. See Donation matching.

1curl -X POST https://api.sandbox.charitips.com/v1/campaigns \2  -H "Authorization: Bearer $CHARITIPS_TOKEN" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Year-end budget",6    "charitiesSelectionId": "<charitiesSelectionId>",7    "type": "TIME_BASED",8    "endDate": "2026-12-31",9    "amountType": "FIXED_AMOUNT",10    "budget": 100000011  }'

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: it takes donations, votes or recurring donations.
3. Closed (COMPLETE), by you with Close a campaign 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.

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.
• The campaign_create and campaign_update webhook events report every change, including activation and closing. See Webhooks configuration.

Related

Donation lifecycle, Billing and fiscal receipts, Account hierarchy, Create a campaign, Update a campaign.