--- title: "Customers vote on a budget" description: "Set a budget and let customers, employees or policyholders decide where it goes." canonical: https://www.charitips.com/docs/use-cases/vote-on-a-budget --- # Customers vote on a budget > Set a budget and let customers, employees or policyholders decide where it goes. - **Who pays**: Your company - **Starts with**: A customer action - **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/vote.md **This demo is one example**: Customers split a yearly budget. The same flow also covers: - [Employees or policyholders vote](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md#create-one-vote-per-person): The people who vote are your employees or policyholders instead of your customers. - [Some votes count more](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md#create-one-vote-per-person): Votes are weighted, for example by seniority or by how much a customer spent. - [A public vote page](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md#edge-cases): Charitips hosts the vote page, so you only share a link. - [A private vote by email](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md#or-send-each-person-a-voting-link): Each voter receives a personal link by email, and nobody else can vote. **Variants**: the same flow in other sectors, each with its build spec. - [Customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget/budget-vote.md) (Retail): A retailer sets a yearly budget, 20 000 € for example, and lets customers decide where it goes. Each customer casts one vote on a hosted ballot; the budget is billed at activation. A yearly budget split by the votes. Build spec: https://www.charitips.com/docs/demos/vote.md - [Visitors vote at an exhibition](https://www.charitips.com/docs/use-cases/vote-on-a-budget/exhibition-ballot.md) (Culture and events): A museum funds a pot of 1 € per ticket for an exhibition. Each ticket is one vote on a screen at the exit; the pot is split by the votes when the exhibition closes. 1 € per ticket, split by the votes. Build spec: https://www.charitips.com/docs/demos/vote/exhibition-ballot.md - [The tournament winner picks](https://www.charitips.com/docs/use-cases/vote-on-a-budget/tournament-winner.md) (Software and apps): An e-sport league puts 2 € per entry into a charity pot. Players sign up and compete; the tournament winner picks the charity the whole pot goes to; the league pays. 2 € per entry, the winner picks the charity. Build spec: https://www.charitips.com/docs/demos/vote/tournament-winner.md - [Collective adoption goal](https://www.charitips.com/docs/use-cases/vote-on-a-budget/adoption-goal.md) (Software and apps): A SaaS ties a donation to a feature's adoption: once 500 users have turned it on, it gives 0,50 € per user. Each user picks their own charity. 0,50 € per user, paid once the goal is reached. Build spec: https://www.charitips.com/docs/demos/vote/adoption-goal.md - [Poll after a webinar](https://www.charitips.com/docs/use-cases/vote-on-a-budget/webinar-poll.md) (Education): A training company gives 5 % of each webinar ticket. When the live session ends, a poll opens and the attendees choose the charity together; the company pays. 5 % of each ticket, the attendees choose. Build spec: https://www.charitips.com/docs/demos/vote/webinar-poll.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-vote`](https://www.charitips.com/docs/api-reference/create-vote.md), [`cast-vote`](https://www.charitips.com/docs/api-reference/cast-vote.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) - **Webhooks**: `vote_create`, `vote_update`, `donation_create`, `donation_update` - **Before you start**: A `DISTRIBUTION`, `FIXED_AMOUNT` campaign with a budget, billed when it is activated. ### Create the vote campaign Set up a campaign as in [steps 3 to 5 of Your first donation](https://www.charitips.com/docs/get-started/first-donation.md#3-pick-your-charities), with `type` set to `TIME_BASED` and an `endDate`, `donationType` set to `DISTRIBUTION`, `amountType` set to `FIXED_AMOUNT`, a `budget` in cents and the `charitiesSelectionId` of the charities people can vote for. The budget is whatever you set, for example 2 % of last year's profit. A `DISTRIBUTION` campaign takes votes only: the API refuses donations on it. ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer vote 2027", "charitiesSelectionId": "", "type": "TIME_BASED", "endDate": "2027-12-31", "donationType": "DISTRIBUTION", "amountType": "FIXED_AMOUNT", "budget": 2000000 }' ``` ### Activate the campaign Activate it with [Activate a campaign](https://www.charitips.com/docs/api-reference/activate-campaign.md). The budget is billed at activation. ```bash curl -X POST https://api.sandbox.charitips.com/v1/campaigns//activate \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ### Create one vote per person Create one vote for each person, with your id for them as `uniqueExternalId`. `weight` lets some votes count more. ```bash curl -X POST https://api.sandbox.charitips.com/v1/votes \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "campaignId": "", "uniqueExternalId": "employee_4410" }' ``` ### Cast each vote Cast each vote for the charity the person picks. When the campaign ends, the budget is shared in proportion to the cast votes and their `weight`; a vote never cast does not count. ```bash curl -X POST https://api.sandbox.charitips.com/v1/votes//cast \ -H "Authorization: Bearer $CHARITIPS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "charityId": "" }' ``` ### Or send each person a voting link Instead of casting from your server, let each person vote on a page Charitips hosts. [Get a vote](https://www.charitips.com/docs/api-reference/get-vote.md) with `includeUrl=true` returns the vote's `url`, a link for that person only: send it by email or show it in your product, and the vote is cast when they choose. To keep the choice inside your product, show the [charity selection widget](https://www.charitips.com/docs/widgets/charity_selection.md) with the `claim` type and the vote's `secret` as `voteSecret`. ```bash curl -X GET https://api.sandbox.charitips.com/v1/votes/ \ -H "Authorization: Bearer $CHARITIPS_TOKEN" ``` ## Edge cases - **Someone votes twice.** The second cast returns `409 Vote already casted`. - **Anyone can vote, without a link.** Create the campaign with `audienceType` set to `PUBLIC`: anyone who opens its page votes, without a vote created in advance, so the number of votes is not known beforehand. [Get a campaign](https://www.charitips.com/docs/api-reference/get-campaign.md) with `includeSiteUrl=true` returns the page's address. A `PRIVATE` campaign, the default, only takes the votes you create. ## 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)