---
title: "Customers vote on a budget: donations with the Charitips API"
description: "A retailer sets a yearly budget, 20 000 € for example, and lets customers decide where it goes."
canonical: https://www.charitips.com/docs/use-cases/vote-on-a-budget/budget-vote
---

# Customers vote on a budget: donations with the Charitips API

> 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.

- **Use case**: [Customers vote on a budget](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md)
- **Sector**: Retail
- **Who pays**: Your company
- **What starts the donation**: A customer action
- **Example**: A yearly budget split by the votes
- **Calls**: [`POST /v1/charities-selections`](https://www.charitips.com/docs/api-reference/create-charities-selection.md), [`POST /v1/campaigns`](https://www.charitips.com/docs/api-reference/create-campaign.md), [`POST /v1/campaigns/{campaignId}/activate`](https://www.charitips.com/docs/api-reference/activate-campaign.md), [`POST /v1/votes`](https://www.charitips.com/docs/api-reference/create-vote.md), [`POST /v1/votes/{voteId}/cast`](https://www.charitips.com/docs/api-reference/cast-vote.md)
- **Webhooks**: `vote_create`, `vote_update`

Interactive demo on the page. The same flow as a build spec: https://www.charitips.com/docs/demos/vote.md

## How it works

The screens of the demo in order, with the calls your server makes at each one.

### Once, before the first customer

- [`POST /v1/charities-selections`](https://www.charitips.com/docs/api-reference/create-charities-selection.md) Create a charities selection: once: the charities people can vote for, from the catalog

  ```json
  {
    "name": "Vote 2026",
    "charityIds": [
      "<charityId>"
    ]
  }
  ```
- [`POST /v1/campaigns`](https://www.charitips.com/docs/api-reference/create-campaign.md) Create a campaign: once: a DISTRIBUTION campaign with a fixed budget, billed at activation

  ```json
  {
    "name": "Our 2026 budget",
    "type": "TIME_BASED",
    "endDate": "2026-12-31",
    "donationType": "DISTRIBUTION",
    "amountType": "FIXED_AMOUNT",
    "budget": 2000000,
    "charitiesSelectionId": "<charitiesSelectionId>"
  }
  ```
- [`POST /v1/campaigns/{campaignId}/activate`](https://www.charitips.com/docs/api-reference/activate-campaign.md) Activate a campaign: once: the campaign starts taking votes

### 1. We give 20 000 € this year. You decide where.

The ballot opens on the page, in a random order for each customer, with no results before the vote. When the customer confirms, your server creates their vote, then casts it: two taps in all.

- The customer picks a charity from your selection.
- Button: Vote for the charity

**Your server calls:**

- [`POST /v1/votes`](https://www.charitips.com/docs/api-reference/create-vote.md) Create a vote: when the customer confirms, just before casting it: one vote per customer, with its weight

  ```json
  {
    "campaignId": "<campaignId>",
    "uniqueExternalId": "customer_204",
    "weight": 1
  }
  ```

Charitips then sends the `vote_create` webhook to your endpoint.

### 2. Your vote is recorded

- Button: Vote for the charity

**Your server calls:**

- [`POST /v1/votes/{voteId}/cast`](https://www.charitips.com/docs/api-reference/cast-vote.md) Cast a vote: right after create-vote, with its voteId

  ```json
  {
    "charityId": "<charityId>"
  }
  ```

Charitips then sends the `vote_update` webhook to your endpoint.

### 3. You have already voted

The same customer tries again: the API keeps the first vote.

- Button: Simulate a second vote

**Your server calls:**

- [`POST /v1/votes/{voteId}/cast`](https://www.charitips.com/docs/api-reference/cast-vote.md) Cast a vote: the same voteId, cast a second time

  ```json
  {
    "charityId": "<anotherCharityId>"
  }
  ```

## Other ways to run it

- [Visitors vote at an exhibition](https://www.charitips.com/docs/use-cases/vote-on-a-budget/exhibition-ballot.md) (Culture and events): 1 € per ticket, split by the votes
- [The tournament winner picks](https://www.charitips.com/docs/use-cases/vote-on-a-budget/tournament-winner.md) (Software and apps): 2 € per entry, the winner picks the charity
- [Collective adoption goal](https://www.charitips.com/docs/use-cases/vote-on-a-budget/adoption-goal.md) (Software and apps): 0,50 € per user, paid once the goal is reached
- [Poll after a webinar](https://www.charitips.com/docs/use-cases/vote-on-a-budget/webinar-poll.md) (Education): 5 % of each ticket, the attendees choose
- [Full guide: edge cases, webhooks, receipts](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md)
- [All use cases](https://www.charitips.com/docs/use-cases.md)