Skip to content
Aller au contenu
Charitips

Use cases · Subscriptions

A saved choice, a periodic statement

Your customer picks a charity once, in their settings. Each period, you give a share and show it on their statement.

  • Who paysYour company
  • Starts withEvery period
  • Tax receiptIn your company's name

Needs API access on a validated account. Plans

Device
Charities shown as
Outline widget
your-app.example/settings/billing

your-app.example/settings/billing

Step by step

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

  2. 1Charity saved

    To come

    Your customer does…

    Clicks “Save”.

    Your server sends…

    Your app saves the workspace's charity on its side, for the next invoices.

    Charitips answers…

    Nothing: Charitips is not called at this step.

  3. 2Waiting donations claimed

    To come

    Your customer does…

    Clicks “Save”.

    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.

  4. 3Invoice paid

    To come

    Your customer does…

    Clicks “Simulate the next renewal”.

    Your server sends…

    Creates a 0,49 € donation for invoice 2026 10 0042 on the campaign “1 % of every plan”, 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.

  5. 4Invoice refunded

    To come

    Your customer does…

    Clicks “Refund this invoice”.

    Your server sends…

    Deletes that donation.

    DELETEdelete-donation

    Charitips answers…

    The donation is deleted and never billed.

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.

Software and appsShare of a subscriptionA SaaS gives 1 % of every plan at each renewal. The workspace admin saves a charity in the billing settings; invoices paid before that choice wait, then get claimed for it.1 % of each plan, every renewalOpen its page
Banking and insuranceCard cashbackA bank turns 1 % of a customer's monthly card spending into one donation, at no cost to them. The customer picks the charity from the monthly notification; it is kept for later.1 % of card spending, each monthOpen its page
EnergyEnergy savedAn energy supplier compares each bill with the customer's baseline and gives 1 cent per kWh saved. The supplier pays; the customer picks the charity once and sees it on each bill.0,01 € per kWh saved, on each billOpen its page
Banking and insuranceNo-claim year bonusAn insurer gives 5 % of the premium after a year without an at-fault claim, instead of a discount. The policyholder picks the charity on their statement; the premium is unchanged.10 € after a year with no claimOpen its page
Banking and insuranceUnused premium given backAn insurer works out, at year end, the premium not spent on claims and gives 5 % of it. The policyholder joins the programme and picks the charity today; the insurer pays.5 % of the unused premium, at year endOpen its page
Banking and insuranceMonthly share of a premiumAt renewal, a home insurer promises 1 € of each monthly premium to the charity the policyholder picks. Each payment creates the donation; the insurer pays, the premium stays put.1 € a month, inside the premiumOpen its page
Banking and insuranceShare of a card feeA bank's premium card gives 10 % of its yearly fee to a charity. The customer picks it when applying for the card; charging the fee creates the donation each year; the bank pays.10 % of the yearly fee of a premium cardOpen its page
Banking and insuranceCashback on purchasesA mobile bank gives 1 % of each customer's card purchases every month, paid by the bank. The customer picks the charity once; the month closes with one donation on the statement.1 % of each purchase, settled monthlyOpen its page
EducationPremium plan revenueAn online school gives 5 % of all Premium subscriptions each month to one charity it names for the year. Subscribers see in their account the total given since January.5 % of the Premium plan revenue, each monthOpen its page
Software and appsActive time convertedA community platform converts every 10 active minutes into 1 cent, settled monthly and paid by the platform. The member picks the charity once and watches the month add up.0,01 € per active period, settled monthlyOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaignclaim-donationcreate-donationdelete-donationlist-donations
Webhooksdonation_updatedonation_create

  1. Create the campaign

    Once, create a charities selection, create the 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": "Monthly share",    "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. Save the customer's choice

    In the customer's settings, let them pick a charity among the selection's. Your app saves the charityId on its side; each donation carries it later.

    Shell
    curl "https://api.sandbox.charitips.com/v1/charities-selections/<charitiesSelectionId>?includeCharities=true" \  -H "Authorization: Bearer $CHARITIPS_TOKEN"

  3. Send one donation per period

    At the end of each period, compute the amount on your side (a share of the plan, of the card fee or of the spending, or a meter such as kWh saved) and send one donation with the saved charityId: it is assigned at once. Build uniqueExternalId from the customer and the period, so a job that runs twice never gives twice. Small amounts per event (a cent per kWh, a few cents per transaction) add up on your side first: one donation per period keeps your bill and your webhooks short.

    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": 312,    "uniqueExternalId": "kwh_customer_4471_2026_10",    "externalId": "customer_4471",    "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. Claim it when the customer chooses

    When a customer has not chosen yet, create the donation without charityId. It waits for their choice: claim it when they pick, or let it be assigned automatically when it expires or when the campaign closes. None is lost. The donation_update webhook tells your server when a waiting donation gets its charity.

    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.

  5. Show it on the statement

    List the customer's donations with List donations, filtered by their externalId, and show each period's line on the statement.

    Shell
    curl "https://api.sandbox.charitips.com/v1/donations?externalId=customer_4471" \  -H "Authorization: Bearer $CHARITIPS_TOKEN"

Edge cases

  • A year-end settlement. A claim-free bonus or an unused premium is one donation a year, its amount computed when the year closes: the same call, with the year in uniqueExternalId.
  • The customer pays the share. When the share is added to their bill, their own money pays it: see Your users give their own money for the receipt in their name.
  • Fiscal receipts. You fund these donations, so the receipt goes to your company: one a year by default.

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