Skip to content
Aller au contenu
Charitips

Use cases · Subscriptions

A share of each subscription

Give a percentage of every plan to the charity your customer selected.

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

Needs API access on a validated account. Plans

One variant of A saved choice, a periodic statement

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

This demo is one example. 1 % of each plan: 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-campaignclaim-donationcreate-donationdelete-donation
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": "Subscription 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. Add a charity picker

    Add a charity picker to your settings page, with the charities of the selection. Store the charityId the customer saves on your side.

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

  3. Give a share on each renewal

    On each successful renewal, create a donation for the share. With the stored charity as charityId, it is assigned at once; while the customer has not chosen yet, leave charityId out so it waits for the choice. Use the invoice id of your billing system as uniqueExternalId: renewals retried by your billing provider never donate twice.

    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": 49,    "uniqueExternalId": "invoice_in_1Q7",    "externalId": "workspace_219",    "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 the waiting donations

    When the customer saves a charity, find the donations still waiting for it with List donations and the customer's externalId, then claim each one. A donation nobody claims is still 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.

Edge cases

  • The invoice is refunded. Delete the donation before it is billed. Once billed it stays: donate less on the next renewal instead.
  • Show it in the customer's account. List donations filtered by externalId.
  • Fiscal receipts. You fund the share, so the fiscal 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