Skip to content
Aller au contenu
Charitips

Use cases · Commerce

A donation for every referral

Reward the customer who brings a friend with a donation to the charity they pick.

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

Needs API access on a validated account. Plans

One variant of A donation for an achievement

The family page plays this case next to the other sectors that run the same calls.

See every variant
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.

This demo is one example. 10 € when the friend signs up: that is the case the demo plays. The same flow also covers:

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

Before you start

  • For the email variant: a TIME_BASED campaign and a donor.

  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": "Referral program",    "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. Let the referrer pick a charity

    On your referral page, the referrer picks the charity upfront, so every invite can name it. Your app saves the charityId on its side.

  3. Give when the friend signs up

    When the friend's account is confirmed, create the referrer's donation with the saved charityId. It is assigned at once, with no separate claim.

    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": 1000,    "charityId": "<charityId>",    "uniqueExternalId": "referral_3301",    "externalId": "customer_118"  }'
    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. Give the friend a welcome gift

    To reward the friend too, create a second donation without charityId, with the friend's id as externalId. Their first screen offers the charities.

    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": 1000,    "uniqueExternalId": "referral_3301_friend",    "externalId": "customer_119"  }'
    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. Let the friend pick a charity

    When the friend picks, claim the donation for that charity. Without a choice, it is assigned automatically when it expires or when the campaign closes: none is lost.

    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.

  6. Let Charitips email the referrer

    create the campaign with sendingMode set to EMAIL. Then pass the referrer as donor with both email and firstName, and the day to send the email in sendingDate: Charitips emails them a link to choose the charity. On an EMAIL campaign, the API returns 400 when donor is missing or has neither, or when sendingDate is missing.

    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": 1000,    "uniqueExternalId": "referral_3301",    "externalId": "customer_118",    "sendingDate": "2026-06-30T09:00:00Z",    "donor": {      "firstName": "Camille",      "email": "camille.martin@example.com"    }  }'
    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 friend cancels during a trial. Delete the donations before they are billed.
  • Fiscal receipts. You pay both 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