Skip to content
Aller au contenu
Charitips

Use cases · Community

Customers vote on a budget

Set a yearly budget and let customers, employees or policyholders decide where it goes.

  • Who paysYour company
  • Starts withA customer action
  • Tax receiptIn your company's name

Needs API access on a validated account. Plans

Device
Charities shown as
Outline widget
Voter
your-brand.example/vote

your-brand.example/vote

Step by step

Click through the site. Each step shows what your customer does, what your server sends and what Charitips answers.

  2. 1Vote created

    To come

    Your customer does…

    Clicks “Vote for the charity”.

    Your server sends…

    Creates a vote of weight 1 for customer #204 on the campaign “Our 2026 budget”.

    POSTcreate-vote

    Charitips answers…

    Charitips creates the vote and returns its id.

    Charitips will then tell your server the vote was created.

  3. 2Vote cast

    To come

    Your customer does…

    Clicks “Vote for the charity”.

    Your server sends…

    Casts that vote for the charity your customer picks.

    POSTcast-vote

    Charitips answers…

    The vote counts for the charity your customer picks.

    Charitips will then tell your server the vote was updated.

  4. 3Second vote refused

    To come

    Your customer does…

    Clicks “Simulate a second vote”.

    Your server sends…

    Casts that vote for another charity.

    POSTcast-vote

    Charitips answers…

    Charitips refuses the call: this was already done, so the first one stands.

How to read this demo: the site shows what your customer does, and the panel what your server sends and what Charitips answers, step by step.

Build spec

The site is made up and nothing is sent. The endpoints, fields and webhook events are the real ones, and so are the charities.

This demo is one example. Customers split a yearly budget: that is the case the demo plays. The same flow also covers:

One flow, 5 variants

Each card is this flow in another sector or use case. Pick one: the demo above plays it, with its site, its amounts and its charities. The API calls stay the same.

RetailCustomers vote on a budgetA 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 votesOpen its page
Culture and eventsVisitors vote at an exhibitionA 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 votesOpen its page
Software and appsThe tournament winner picksAn 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 charityOpen its page
Software and appsCollective adoption goalA 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 reachedOpen its page
EducationPoll after a webinarA 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 chooseOpen its page

Build it

The calls behind the demo, in order. Each step shows the request your server sends.

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-votecast-votecreate-donationclaim-donation
Webhooksvote_createvote_updatedonation_createdonation_update

Before you start

  • A DISTRIBUTION, FIXED_AMOUNT campaign with a budget, billed when it is activated.

  1. Create the vote campaign

    Set up a campaign as in steps 3 to 5 of Your first donation, 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.

    POST /v1/campaigns
    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": "<charitiesSelectionId>",    "type": "TIME_BASED",    "endDate": "2027-12-31",    "donationType": "DISTRIBUTION",    "amountType": "FIXED_AMOUNT",    "budget": 2000000  }'
    Built from the spec and the API code

    Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

  2. Activate the campaign

    Activate it with Activate a campaign. The budget is billed at activation.

    POST /v1/campaigns/<campaignId>/activate
    curl -X POST https://api.sandbox.charitips.com/v1/campaigns/<campaignId>/activate \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    Built from the spec and the API code

    Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

  3. Create one vote per person

    Create one vote for each person, with your id for them as uniqueExternalId. weight lets some votes count more.

    POST /v1/votes
    curl -X POST https://api.sandbox.charitips.com/v1/votes \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "campaignId": "<campaignId>",    "uniqueExternalId": "employee_4410"  }'
    Built from the spec and the API code

    Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

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

    POST /v1/votes/<voteId>/cast
    curl -X POST https://api.sandbox.charitips.com/v1/votes/<voteId>/cast \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "charityId": "<charityId>"  }'
    Built from the spec and the API code

    Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

  5. 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 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 with the claim type and the vote's secret as voteSecret.

    GET /v1/votes/<voteId>
    curl -X GET https://api.sandbox.charitips.com/v1/votes/<voteId> \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    Built from the spec and the API code

    Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

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 with includeSiteUrl=true returns the page's address. A PRIVATE campaign, the default, only takes the votes you create.

The memo

Send the memo to your team

Already written for this flow

  • What it does and who pays, in a few sentences
  • What you need: plan, API calls and webhooks
  • What you can report: donations, charities, impact and receipts

To paste in an email, a document or a note.

Email it

Related pages