Skip to content
Aller au contenu
Charitips

Use cases · Engagement

A donation for an achievement

A success in your product, such as a signed lease, a passed exam or a completed survey, gives a donation, and the person picks its charity on the success screen.

  • 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
Reward per referral
your-app.example/referrals

your-app.example/referrals

Step by step

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

  2. 1Charity chosen

    To come

    Your customer does…

    Clicks “Save”.

    Your server sends…

    The referrer picks the charity upfront, so every invite can name it. Your app saves it on its side.

    Charitips answers…

    Nothing: Charitips is not called at this step.

  3. 2Friend joined

    To come

    Your customer does…

    Clicks “Simulate Sam's sign-up”.

    Your server sends…

    Creates a 10 € donation for referral #871 on the campaign “Referral rewards”, for the charity your customer picks.

    POSTcreate-donation

    Creates a 10 € donation for referral 871 friend on the campaign “Referral rewards”.

    POSTcreate-donation

    Charitips answers…

    Charitips records the donation and returns its id: it goes to the charity your customer picks at once.

    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.

  4. 3Friend's charity chosen

    To come

    Your customer does…

    Clicks “Give 10 €”.

    Your server sends…

    Assigns that donation to another charity.

    POSTclaim-donation

    Charitips answers…

    The donation now goes to another charity.

    Charitips will then tell your server the donation was updated.

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

Software and appsCustomer referralA product gives 10 € when a referred friend signs up. The referrer picks the charity upfront, so every invite names it; the friend's own welcome gift waits for their choice.10 € when the friend signs upOpen its page
Professional servicesLease signed onlineA rental agency gives 3 € for each lease signed online. On the last step before the keys, the tenant signs and picks the charity on the success screen; the agency pays.3 € for each lease signed onlineOpen its page
EducationCertification passedA training provider gives 5 € for each certification passed. When the jury publishes the results, the certified candidate picks the charity on their results page.5 € for each certification passedOpen its page
Software and appsSurvey completedA SaaS gives 0,50 € for each in-app survey completed. Three questions, two minutes, then the user picks the charity on the thank-you screen; the company pays.0,50 € for each survey completedOpen its page
Travel and mobilityUnused rental kilometresA car rental company gives 5 cents for each kilometre left in the allowance at return. The renter picks the charity on the return screen; the rental company pays.0,05 € per kilometre not drivenOpen its page
Hotels and restaurantsUnused buffet portionsA caterer counts the portions not served after a seminar and gives 1 € for each. The client approves the buffet report and picks the charity; the caterer pays.1 € per portion saved, after the eventOpen its page
Banking and insuranceInsurance deductible settledAn insurer gives 5 % of the excess when the policyholder pays it to close a claim. The policyholder picks the charity on the claim's closing screen; the insurer pays.5 % of the deductible, on each settled claimOpen its page
EnergyEnergy contract referralAn energy supplier gives 10 € once a referred friend's contract is active, after the cooling-off period. The referrer picks the charity on their referrals page; the supplier pays.10 € once the referred contract is activeOpen its page
Hotels and restaurantsHousekeeping skippedA hotel gives 1 € for each day a guest skips housekeeping. At check-out the guest sees the total and picks the charity; the hotel pays and nothing appears on the bill.1 € per day without housekeeping, at check-outOpen its page
Travel and mobilityShared ride completedA ride-hailing app gives 0,50 € each time a passenger shares the ride. On arrival, the passenger picks the charity on the receipt screen; the platform pays.0,50 € per shared rideOpen its page
Software and appsNew seller's first listingA marketplace gives 5 € when a new seller publishes a first listing within a week. The seller picks the charity on the publish confirmation; the marketplace pays.5 € when a new seller lists within a weekOpen its page
Professional servicesCharity clause in a contractA law firm adds a charity clause to its contracts: article 14 names the charity, and each signature gives 2 €. The donation is created already assigned; the firm pays.2 € per contract signed, to the charity the clause namesOpen its page
Culture and eventsFestival ticketsA festival gives 1 € per ticket sold, paid by the festival. Right after payment, the buyer picks the charity on the order confirmation; the ticket price does not change.1 € per ticket, chosen after paymentOpen its page
Professional servicesProperty sale completedAn estate agency gives 1 % of the sale price at completion, taken from its own fee. The seller picks the charity on the completion page; what they receive does not change.1 % of the sale price, from the agency's feeOpen its page
Software and appsProject milestones delivered earlyA project tool gives 10 € each time a team delivers a milestone ahead of its date. The team picks the charity when the milestone closes; the company pays.10 € per milestone delivered earlyOpen its page
Software and appsStand-up streakA team tool gives 5 € when a team holds 10 daily stand-ups in a row on time. The team picks the charity when the streak milestone is reached; the company pays.5 € for every 10 stand-ups on timeOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-donationclaim-donation
Webhooksdonation_createdonation_update

  1. 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
    curl -X POST https://api.sandbox.charitips.com/v1/campaigns \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Leases signed online",    "charitiesSelectionId": "<charitiesSelectionId>"  }'
    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. Give when the event happens

    When the contract is signed or the certificate issued, your server creates the donation with the event's id as uniqueExternalId. One event gives one donation. The amount can come from the event (0,05 € per kilometre not driven, 1 € per buffet portion saved, a share of an insurance deductible): compute it on your side and send it in cents.

    POST /v1/donations
    curl -X POST https://api.sandbox.charitips.com/v1/donations \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "campaignId": "<campaignId>",    "amount": 300,    "uniqueExternalId": "lease_77120",    "externalId": "tenant_5531"  }'
    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. Let the person pick a charity

    The success screen offers the charities. Save the choice with Claim a donation.

    POST /v1/donations/<donationId>/claim
    curl -X POST https://api.sandbox.charitips.com/v1/donations/<donationId>/claim \  -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.

  4. Name the charity yourself

    A contract clause or a partnership can name the charity in advance. Create the donation with that charityId: it is assigned at once, with no claim and no choice screen.

    POST /v1/donations
    curl -X POST https://api.sandbox.charitips.com/v1/donations \  -H "Authorization: Bearer $CHARITIPS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "campaignId": "<campaignId>",    "amount": 300,    "charityId": "<charityId>",    "uniqueExternalId": "lease_77120",    "externalId": "tenant_5531"  }'
    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

  • The person leaves without choosing. The donation is assigned automatically when it expires or when the campaign closes: none is lost. Bring them back to the choice from your product, or let Charitips email them: see A gift sent by email, Slack or post.
  • The event is undone. Delete the donation before it is billed.
  • 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

Related pages