--- title: "A campaign for a date" description: "A time-limited campaign with its own budget and charities, for a day or a season. Set it up once, give with every order of the date, and let it close." canonical: https://www.charitips.com/docs/use-cases/campaign-for-a-date --- # A campaign for a date > A time-limited campaign with its own budget and charities, for a day or a season. Set it up once, give with every order of the date, and let it close. - **Who pays**: Your company - **Starts with**: A purchase - **Tax receipt**: In your company's name - Needs [API access](https://www.charitips.com/docs/overview/plans.md#api-access-for-webhooks-and-credentials) on a validated account. [Plans](https://www.charitips.com/docs/overview/plans.md#what-every-flow-needs) Interactive demo on the page. The same flow as a build spec: https://www.charitips.com/docs/demos/moment.md **This demo is one example**: Earth Day budget spent on orders. The same flow also covers: - [A give-away every quarter or year](https://www.charitips.com/docs/use-cases/vote-on-a-budget/budget-vote.md): A fixed budget, renewed each period, shared according to your customers' choices. - [A vote for the day](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md): For a date such as International Women's Day, people vote between charities chosen for it. - [End-of-year redistribution](https://www.charitips.com/docs/use-cases/vote-on-a-budget/budget-vote.md): What is left of a yearly budget goes, in December, to the charities your community picks. **Variants**: the same flow in other sectors, each with its build spec. - [A date with a budget](https://www.charitips.com/docs/use-cases/campaign-for-a-date/campaign-for-a-date.md) (Retail): A store runs a one-day campaign with a fixed budget, for example 10 000 € on Earth Day. Each order of the day gives 5 €, billed at activation, until the budget runs out. A fixed budget spent on the orders of Earth Day. Build spec: https://www.charitips.com/docs/demos/moment.md - [Flash sale](https://www.charitips.com/docs/use-cases/campaign-for-a-date/flash-sale.md) (Retail): During a two-hour flash sale, a shop gives 5 % of each order into a capped pot. The buyer picks the charity after payment; the shop pays and the price does not change. 5 % of the sales during the slot. Build spec: https://www.charitips.com/docs/demos/moment/flash-sale.md - [Happy hour](https://www.charitips.com/docs/use-cases/campaign-for-a-date/happy-hour.md) (Hotels and restaurants): A restaurant's charity happy hour puts 5 % of each order into the evening's pot for a named charity. At 8 pm, the till sends the pot as one donation; the restaurant pays. 5 % of the evening's happy-hour sales. Build spec: https://www.charitips.com/docs/demos/moment/happy-hour.md - [In-game charity event](https://www.charitips.com/docs/use-cases/campaign-for-a-date/game-event.md) (Software and apps): A game runs a timed charity event: each challenge cleared adds 0,10 € to a pot for a named charity, up to a set budget. The server sends each hour's pot; the studio pays. 0,10 € per challenge, into a capped pot. Build spec: https://www.charitips.com/docs/demos/moment/game-event.md ## Build it - **Calls**: [`create-charities-selection`](https://www.charitips.com/docs/api-reference/create-charities-selection.md), [`create-campaign`](https://www.charitips.com/docs/api-reference/create-campaign.md), [`activate-campaign`](https://www.charitips.com/docs/api-reference/activate-campaign.md), [`create-donation`](https://www.charitips.com/docs/api-reference/create-donation.md), [`claim-donation`](https://www.charitips.com/docs/api-reference/claim-donation.md), [`get-campaign-metrics`](https://www.charitips.com/docs/api-reference/get-campaign-metrics.md) - **Webhooks**: `donation_create`, `donation_update` - **Before you start**: A `TIME_BASED`, `FIXED_AMOUNT` campaign with an end date and a budget, billed when it is activated. ### Pick the charities of the date Put the charities of the date in a charities selection, as in [step 3 of Your first donation](https://www.charitips.com/docs/get-started/first-donation.md#3-pick-your-charities). See [Charities and selections](https://www.charitips.com/docs/concepts/charities.md). ```bash curl -X POST https://api.sandbox.charitips.com/v1/charities-selections \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Earth Day", "charityIds": [ "", "" ] }' ``` ### Create the campaign Create one campaign per date: `TIME_BASED` with an `endDate`, and `FIXED_AMOUNT` with a `budget` in cents. `endDate` is read as midnight UTC, so pass the day after the date: `2027-04-23` keeps Earth Day open until its end. ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Earth Day", "charitiesSelectionId": "", "type": "TIME_BASED", "endDate": "2027-04-23", "amountType": "FIXED_AMOUNT", "budget": 1000000 }' ``` ### Activate the campaign The whole budget is billed when you activate the campaign. By card or direct debit, the campaign starts at once; paid by bank transfer, it stays `PENDING` until the transfer arrives, so activate it a few days ahead. An active campaign takes donations at once, before its `startDate` too: if you activate ahead of the date, create donations only for orders placed during it. What activation checks is listed in [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md#what-activation-checks). ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns//activate \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ### Give with each order From your payment webhook, for each paid order of the date, create a donation with the set amount and the order id as `uniqueExternalId`. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "amount": 500, "uniqueExternalId": "order_2204" }' ``` ### Save the buyer's choice On the confirmation page, show the charities of the date and save the buyer's choice with [Claim a donation](https://www.charitips.com/docs/api-reference/claim-donation.md). A buyer who does not choose loses nothing: the donation is assigned automatically when the campaign closes. ```bash curl -X POST https://api.sandbox.charitips.com/v1/donations//claim \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "charityId": "" }' ``` ### Show the running total To show the running total and the share of each charity, read [Get campaign metrics](https://www.charitips.com/docs/api-reference/get-campaign-metrics.md) on your server (`totalDonation`, `numberOfDonations`, `sortedCharities`) and cache it for a few minutes. ```bash curl -X GET https://api.sandbox.charitips.com/v1/campaigns//metrics \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ### Close the campaign Once the end date has passed, a daily scheduled job closes the campaign; on sandbox, close it yourself. You can close it at any time with [Close a campaign](https://www.charitips.com/docs/api-reference/close-campaign.md), and closing cannot be undone. Donations still without a charity and the budget not yet given are then assigned to charities automatically; once the budget is paid, the money goes to the charities and a report is generated. With `fiscalReceiptType: SINGLE_DONATION`, your fiscal receipts are issued at that point, one per charity, otherwise they come with the yearly ones (see [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md)). ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns//close \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ## Edge cases - **The budget runs out.** The next donation answers `400 Insufficient campaign budget.` (`INSUFFICIENT_CAMPAIGN_BUDGET`) and the order goes through without one. The check is per donation: one larger than what is left is refused in full. - **An order comes after the end.** Once the campaign is closed, creating a donation answers `403 Campaign has ended.`; stop asking on your side. - **A retried webhook.** The same `uniqueExternalId` answers `409` instead of giving twice. - **An order is cancelled.** Once the budget is paid, the donation cannot be deleted (`403 Donation already paid`): it stays and counts towards the budget. - **No donation at all.** The scheduled job leaves a fixed-budget campaign open if it received no donation, or none with a charity. With donations still waiting for a charity, close it yourself; with no donation at all, closing it answers `403 NOTHING_TO_CLOSE`: ask us. - **A vote instead of orders.** For a budget shared by votes of customers or employees, see [Customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md). ## Related pages - [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md) - [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md)