Use cases · Engagement

Progress and tiers

A counter, a streak or a gauge reaches a tier: a donation unlocks, the person picks its charity once, and the next tiers follow.

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

app.your-insurer.example

Step by step

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

1At each 10,000-step day
To come
Your customer does…
Clicks “Sync my steps”.
Your server sends…
No call: your side saves it.
Charitips answers…
Nothing: Charitips is not called at this step.
2At the end of the month
To come
Your customer does…
Clicks “Close the month”.
Your server sends…
Creates a 1,90 € donation for activity 40922 2026 10 on the campaign “Your insurer”.
POSTcreate-donation
Charitips answers…
Charitips records the donation and returns its id: it waits for your customer to pick a charity.
Charitips will then tell your server the donation was created.
3When the charity is chosen
To come
Your customer does…
Clicks “Choose the charity”.
Your server sends…
Assigns that donation to the charity your customer picks.
POSTclaim-donation
Charitips answers…
The donation now goes to the charity your customer picks.
Charitips will then tell your server the donation was updated.
4At the end of the next month
To come
Your customer does…
Clicks “Close the month”.
Your server sends…
Creates a 2,20 € donation for activity 40922 2026 11 on the campaign “Your insurer”, for the charity your customer picks.
POSTcreate-donation
Charitips answers…
Charitips records the donation and returns its id: it goes to the charity your customer picks at once.
Charitips will then tell your server the donation was created.

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.

Scenarios this flow covers The same calls cover each of these.

One flow, 10 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.

Banking and insurance10 000 steps a dayAn insurer's app sets aside 0,10 € each day the member reaches 10 000 steps. On the 1st, the month's total goes out as one donation, paid by the insurer, to the member's charity.0,10 € per day at 10 000 steps, sent monthlyOpen its page

Health and sportGym check-insEvery time a member taps their phone at the gym's front desk, the gym adds 0,50 € to a monthly pot. On the 1st, the pot becomes one donation to the charity the member chose.0,50 € per check-in, sent monthlyOpen its page

EducationCourse modules completedOn a training platform, each module passed adds 0,10 € and more to a pot, plus 5 € when the course is complete. The learner picks the charity at the end; the platform pays.0,10 €, then 0,20 € and up per module, plus 5 € at the endOpen its page

EducationE-learning pathAn e-learning path unlocks 0,20 € from the school at each step finished. The learner picks the charity at the first step; every later step goes to the same one.0,20 € per step completedOpen its page

Software and appsOnboarding milestonesA SaaS turns its setup checklist into donations: each step completed unlocks 0,20 € to 1 €, paid by the vendor. The new user picks the charity once, at the first milestone.0,20 € to 1 € per milestone reachedOpen its page

Banking and insuranceSavings tiersA bank gives 5 € each time a customer's savings pass another 1 000 €. The customer picks the charity on the milestone screen; the money stays in their savings account.5 € for each 1 000 € savedOpen its page

Software and appsGame levelsIn a game, each level gained adds 0,05 € to the day's pot, paid by the studio. At midnight, the server sends the day's pot as one donation to the charity the player chose.0,05 € per level, sent dailyOpen its page

Software and appsWeekly health goalA wellbeing app gives 1 € each week the user completes four sessions. The user picks the charity at the first goal; every week the streak holds goes to the same charity.1 € per weekly goal metOpen its page

Health and sportFollow-up visits on timeA health centre gives 1 € for each follow-up visit kept on time, 2 € from the third. The patient checks in on arrival and picks the charity once; later visits keep it.1 € or 2 € per visit kept on timeOpen its page

Software and appsGame milestones for a chosen charityIn any game, the player picks a charity before playing. Each milestone adds 0,25 € from the studio for it; the player sees the real impact and never pays.0,25 € every 20 levels for the charity picked before playing, paid by the studioOpen its page

Build it

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

Callscreate-charities-selection create-campaign activate-campaign create-donation claim-donation

Webhooksdonation_createdonation_update

Set up the campaign

Once, create a charities selection, a campaign with its charitiesSelectionId, then activate it, as in steps 3 to 5 of Your first donation.
POST /v1/campaigns
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": "Savings tiers",6 "charitiesSelectionId": "<charitiesSelectionId>"7 }'
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.
Count the progress in your app

Steps walked, modules passed, levels won, euros saved: your app counts them and shows the gauge, the streak or the tiers. Nothing goes to Charitips while the person progresses.
Give at the first tier

When the person reaches the first tier, create a donation without charityId, with the tier in uniqueExternalId. Then offer the charities.
POST /v1/donations
1curl -X POST https://api.sandbox.charitips.com/v1/donations \2 -H "Authorization: Bearer $CHARITIPS_TOKEN" \3 -H "Content-Type: application/json" \4 -d '{5 "campaignId": "<campaignId>",6 "amount": 500,7 "uniqueExternalId": "savings_88213_tier_1",8 "externalId": "customer_88213"9 }'
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.
Let the person pick a charity

When the person picks, claim the donation for that charity and save the charityId on your side.
POST /v1/donations/<donationId>/claim
1curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/claim \2 -H "Authorization: Bearer $CHARITIPS_TOKEN" \3 -H "Content-Type: application/json" \4 -d '{5 "charityId": "<charityId>"6 }'
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.
Give at the next tiers

Send each next tier's donation with the saved charityId. It is assigned at once, with no claim and no choice screen.
POST /v1/donations
1curl -X POST https://api.sandbox.charitips.com/v1/donations \2 -H "Authorization: Bearer $CHARITIPS_TOKEN" \3 -H "Content-Type: application/json" \4 -d '{5 "campaignId": "<campaignId>",6 "amount": 500,7 "charityId": "<charityId>",8 "uniqueExternalId": "savings_88213_tier_2",9 "externalId": "customer_88213"10 }'
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.
Add up micro amounts per period

When a step is worth a few cents (0,10 € per day at 10 000 steps, 0,05 € per level), add them up in your app. Create one donation per week or month, with the period in uniqueExternalId. The person still sees each step count, and your bill and your webhooks get one line per period.
Pay at the end

A course can give a growing amount per module and a bonus at the end. Keep the running total on your side and create one donation when the course is done, then let the person pick its charity. update-donation changes an amount only before the claim and before billing, so the total stays in your app.

Edge cases

The person never chooses. A waiting donation is assigned automatically when it expires or when the campaign closes: none is lost.
Health and personal data. Steps, visits and goals stay in your product: never put them in externalId, uniqueExternalId or the donor fields.
Fiscal receipts. You fund the donations, so the receipt goes to your company.

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

One flow, 10 variants

Build it

Set up the campaign

Count the progress in your app

Give at the first tier

Let the person pick a charity

Give at the next tiers

Add up micro amounts per period

Pay at the end

Edge cases

Send the memo to your team

Already written for this flow

Related pages