Skip to content
Aller au contenu
Charitips

Use cases · Engagement

A gift sent by email, Slack or post

Your server creates the donation with the recipient's email or Slack id; Charitips sends the message, and the recipient picks the charity on a hosted page.

  • 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
registry.your-school.example

registry.your-school.example

Step by step

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

  2. 1At graduation

    To come

    Your customer does…

    Clicks “Send the gift to Camille”.

    Your server sends…

    Creates a 5 € donation for diploma 2026 student 0412 on the campaign “Graduation gift 2026”.

    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.

  3. 2On the choice, on the Charitips page

    To come

    Your customer does…

    Clicks “Choose the charity”.

    Your server sends…

    No call: your side saves it.

    Charitips answers…

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

EducationGraduation giftOn ceremony day, a school's registry sends each graduate 5 € by email through Charitips. The graduate opens the hosted page and picks the charity; the school pays.5 € for each graduate, sent on ceremony dayOpen its page
Software and appsSecure merge, on SlackA dev team gives 5 € for each merge request approved with no critical vulnerability. Charitips messages the author on Slack, who picks the charity from the message.5 € for each merge request with no critical flawOpen its page
Professional servicesAudit report deliveredA consulting firm gives 50 € when the client signs off the final audit report. Charitips emails the client, who picks the charity on a hosted page; the firm pays.50 € when the final report is signedOpen its page
Professional servicesProperty estimate sentAn estate agency sends a valuation report and gives the seller 0,1 % of the estimated value. Charitips emails the seller, who picks the charity; the agency pays.0,1 % of the estimated valueOpen its page
Software and appsAPI usage milestoneAn API platform gives 10 € in a client account's name when its usage passes a milestone. Charitips emails the account owner, who picks the charity; the platform pays.10 € in the client's name at each milestoneOpen its page
Software and appsUpsell signedWhen a customer signs a seat expansion, the vendor sets aside 5 % of its value as a donation in the customer's name. The signer receives a Charitips email and chooses the charity.5 % of the upsell, offered to the clientOpen its page
Culture and eventsGift after an eventAt a trade show, an exhibitor scans a visitor's badge and emails them 1 € to 5 € instead of a goodie. The visitor picks the charity on their phone; the exhibitor pays.1 € to 5 € per visitor, sent by emailOpen its page
RetailGreeting card with a giftA card maker ships business greeting cards that each carry a 5 € gift. The dispatch scan triggers the email; the recipient picks the charity on a hosted page; the sender pays.5 € in each business card, sent when it shipsOpen its page
Professional servicesClient gift as a donationA gifting platform offers each client a 50 € present or a donation. When the client picks the donation, Charitips sends them the link to choose the charity; the company pays.A 50 € client gift, turned into a donationOpen its page
Professional servicesGreeting card by postA company orders a year-end card for each client: Charitips prints and posts it with a 25 € gift, and the client picks the charity online. The sender pays.A year-end card with a 25 € gift, posted to each clientOpen its page

Build it

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

Callscreate-charities-selectioncreate-campaignactivate-campaigncreate-donationlist-card-designsclaim-donation
Webhooksdonation_createdonation_update

Before you start

  • A campaign created with sendingMode EMAIL, SLACK or POSTAL, a donor on each donation, and a sendingDate for email and Slack.

  1. Create the email campaign

    Once, pick the charities in a charities selection, then create the campaign with its charitiesSelectionId and sendingMode set to EMAIL. Then activate it.

    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": "Graduation gifts",    "charitiesSelectionId": "<charitiesSelectionId>",    "sendingMode": "EMAIL"  }'
    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. Send the gift by email

    For each recipient, create the donation with their first name and email in donor, and the day to send it in sendingDate: the API answers 400 when donor is missing or lacks one of them, or when sendingDate is missing. Charitips emails the recipient within ten minutes of that date, hosts the page where they pick the charity, and sends the reminders. To send it right away, pass the current time.

    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": 500,    "uniqueExternalId": "graduate_2026_3307",    "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.

  3. Or send it by Slack

    Create the campaign with sendingMode set to SLACK. Then send each donation with the person's Slack member id in donor.slackId, their first name in donor.firstName and the day to send it in sendingDate. The message goes through the Charitips Slack app installed on your workspace.

    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": 500,    "uniqueExternalId": "merge_request_8812",    "sendingDate": "2026-06-30T09:00:00Z",    "donor": {      "firstName": "Camille",      "slackId": "U04ABCD1234"    }  }'
    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. Handle the recipient's choice

    When the recipient picks the charity, your server gets the donation_update webhook. Your product makes no other call.

  5. Or send it by post

    Charitips prints a card in one of the designs it validated, with the code to choose the charity, and posts it as a tracked letter to an address in France. Each card handed over is billed to your company on top of the donation: 1,50 € for the printed card and 2,50 € for tracked postage, excluding VAT. First pick the design: List card designs (language fr or en) lists each one with its momentSlug, its accentColor and a previewUrl of the card's front, and the default Charitips card has a momentSlug of null.

    GET /v1/card-designs
    curl -X GET https://api.sandbox.charitips.com/v1/card-designs \  -H "Authorization: Bearer $CHARITIPS_TOKEN"
    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. Create the postal campaign

    Create the campaign with sendingMode set to POSTAL and the design's momentSlug, then activate it. The design is set once for the campaign.

    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": "Year-end cards",    "charitiesSelectionId": "<charitiesSelectionId>",    "sendingMode": "POSTAL",    "momentSlug": "cadeau-client-fin-d-annee"  }'
    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.

  7. Send each card

    For each card, create the donation with the recipient's postal address in donor and the posting day in sendingDate. donor needs firstName, lastName, street, zip, city and country set to FR, with a French postal code; companyName, streetAddition and email are optional. sendingDate is a business day, from the next batch (16:00, Paris time) up to a year ahead; leave it out to post with the next batch. Leave out charityId too, which the API refuses here: the recipient picks the charity with the code on the card.

    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": 2500,    "uniqueExternalId": "year_end_card_2026_client_0412",    "donor": {      "firstName": "Camille",      "lastName": "Martin",      "companyName": "Architects office",      "street": "12 rue des Lilas",      "zip": "69003",      "city": "Lyon",      "country": "FR"    },    "sendingDate": "2026-12-14"  }'
    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.

  8. Track the card's status

    Each change of the donation reaches your server as a donation_update webhook, and its sendingStatus reads PENDING while the card waits for its batch. DONE means Charitips handed the card over at the 16:00 batch of its posting day, and it arrives 2 to 3 business days later; the status stops at this hand-over. FAILED means the postal partner refused the card or it came back, and a card that cannot be delivered comes back to your company. When the recipient picks the charity, another donation_update follows.

Edge cases

  • The recipient never chooses. Reminders follow, then the donation is assigned automatically when it expires or when the campaign closes: none is lost.
  • Fiscal receipts. You fund the donations, so the receipt goes to your company.
  • A postal address is refused. A missing field, a country other than FR or a postal code outside France answers 400 INVALID_POSTAL_ADDRESS.
  • A posting day is refused. A day that is not a business day, before the next batch or more than a year ahead answers 400 INVALID_SENDING_DATE.
  • Cancel a card. Until the batch takes the card (16:00 on its posting day), deleting the donation cancels it and nothing is billed. After, deleting it or changing its amount answers 403.
  • The claim deadline runs from the creation. The donation's expiry date is set when you create it, not on the posting day: a card scheduled far ahead leaves its recipient less time to choose.

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