Skip to content
Aller au contenu
Charitips

Use cases · Commerce

Unused gift card balance

Let card holders give what is left, or redistribute expired cards.

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

Needs API access on a validated account. Plans

One variant of Loyalty points turned into donations

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-store.example/gift-cards

your-store.example/gift-cards

Step by step

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

  2. 1Balance given

    To come

    Your customer does…

    Clicks “Give 3,40 € to the charity”.

    Your server sends…

    Creates a 3,40 € donation for card #5521 on the campaign “Gift card balances”, 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.

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. Remaining balance given by the holder: 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_create

  1. Set up the campaign

    Once, set up a campaign as in steps 3 to 5 of Your first donation: a charities selection, a campaign created with its charitiesSelectionId, then activated. Both ways below use it.

  2. Offer to give the balance

    On the card's balance page, keeping the balance stays the default. For a small balance or a card about to expire, suggest giving it. The holder picks the charity first, then confirms once.

  3. Give the remaining balance

    Create one donation for the balance with the chosen charityId and the card id as uniqueExternalId, then set the card to zero in your system. With charityId, the donation is assigned at once, with no separate claim. Your store funds the donation and gets the fiscal receipt.

    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": 340,    "charityId": "<charityId>",    "uniqueExternalId": "card_5521"  }'
    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. Redistribute expired cards

    Once a month, sum the balances of the cards that expired and give the total to a campaign of your choice. Use the period as uniqueExternalId, for example expired_2026_10, so the batch never runs 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": 128450,    "uniqueExternalId": "expired_2026_10"  }'
    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 holder makes no choice. Nothing is created and the card keeps its balance. Once it expires, its balance joins the monthly redistribution.
  • Setting the card to zero fails. Delete the donation, then show the error. Deleting works until the donation is billed.
  • Accounting. Each donation is billed to you; keep uniqueExternalId to match each donation with its card.

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