# Demo: Loyalty points turned into donations

> A store lets customers spend loyalty points on a charity at the voucher rate, 100 points for 1 €. The customer picks the charity and the points; the store funds the donation.

One variant of **Loyalty points turned into donations**, in Retail: 100 points for 1 €.

A made-up site, your-store.example/rewards, walked through screen by screen with the Charitips API calls the product makes at each step. Rebuild it in your own project to start from a working flow.

The charity choice in this demo is the Charitips [charity selection widget](https://www.charitips.com/docs/widgets/charity_selection.md), a ready-made proposal. Use it whole, use parts of it, or build your own experience from scratch with the API: [List charities](https://www.charitips.com/docs/api-reference/list-charities.md) gives the charities to show, and the calls below carry the chosen `charityId`.

Charitips widget: the charity cards, their profiles and the thank-you card with sharing, matching and newsletter. Your own UI, built with the API: the points balance, the points to give and the confirmation once the thank-you card is closed.

The full guide, with edge cases: https://www.charitips.com/docs/use-cases/loyalty-points.md.

**Once, before the first customer:**

- [`POST /v1/charities-selections`](https://www.charitips.com/docs/api-reference/create-charities-selection.md) Create a charities selection: once: the charities you offer, from the catalog

  ```json
  {
    "name": "Rewards charities",
    "charityIds": [
      "<charityId>"
    ]
  }
  ```
- [`POST /v1/campaigns`](https://www.charitips.com/docs/api-reference/create-campaign.md) Create a campaign: once: the campaign the donations go to

  ```json
  {
    "name": "Points for charities",
    "charitiesSelectionId": "<charitiesSelectionId>"
  }
  ```
- [`POST /v1/campaigns/{campaignId}/activate`](https://www.charitips.com/docs/api-reference/activate-campaign.md) Activate a campaign: once: the campaign starts taking donations

## Screens and calls

### 1. Give your points to a charity

The customer picks the charity, then the points, and confirms once. One call records the donation, already assigned. Your store funds it at the voucher rate and gets the fiscal receipt.

- Your points: 1 240
- 100 points: 1,00 €
- **500 points as a donation: 5,00 €**
- The customer picks a charity from your selection.
- Button: Give 500 points to the charity

**Your server calls:**

- [`POST /v1/donations`](https://www.charitips.com/docs/api-reference/create-donation.md) Create a donation: once the customer confirms, with the chosen charity: the donation is assigned at once; amount in cents; then your app takes the points off

  ```json
  {
    "campaignId": "<campaignId>",
    "amount": 500,
    "charityId": "<charityId>",
    "uniqueExternalId": "redemption_3318",
    "externalId": "customer_204"
  }
  ```

Charitips then sends the `donation_create` webhook to your endpoint.

## Clone it with a coding agent

```prompt
Clone the Charitips demo "Loyalty points turned into donations" into this project. Read https://www.charitips.com/docs/demos/loyalty.md: it lists each screen and the Charitips API calls behind it. Build the same flow in this codebase, on the sandbox (https://api.sandbox.charitips.com), with my client id and secret read from environment variables, and follow the rules of https://www.charitips.com/docs/skill.md. Make every API call from the server, never from the browser. When it works, show me each call and its response.
```

## Variants

**Variants**: the same flow in other sectors, each with its build spec.

- [Store loyalty points](https://www.charitips.com/docs/use-cases/loyalty-points/loyalty-points.md) (Retail): A store lets customers spend loyalty points on a charity at the voucher rate, 100 points for 1 €. The customer picks the charity and the points; the store funds the donation. 100 points for 1 €. Build spec: https://www.charitips.com/docs/demos/loyalty.md
- [Unused gift card balance](https://www.charitips.com/docs/use-cases/gift-card-balance.md) (Retail): When a gift card keeps a small balance or is about to expire, the store suggests giving it. The holder picks the charity, the card drops to zero and the store funds the donation. The remaining balance, given by the holder. Build spec: https://www.charitips.com/docs/demos/gift-cards.md
- [Travel loyalty points](https://www.charitips.com/docs/use-cases/loyalty-points/travel-points.md) (Travel and mobility): A travel company lets members give expiring loyalty points at the same rate as flights, 100 points for 5 €. The member picks the charity; the company pays, tier progress stays. 100 points for 5 €. Build spec: https://www.charitips.com/docs/demos/loyalty/travel-points.md
- [Cultural member card](https://www.charitips.com/docs/use-cases/loyalty-points/member-card.md) (Culture and events): A museum's membership card lets members give points about to expire, 100 points for 1 €, to an art or heritage charity. The museum pays; the visit count does not change. 100 points for 1 €. Build spec: https://www.charitips.com/docs/demos/loyalty/member-card.md
- [In-game currency](https://www.charitips.com/docs/use-cases/loyalty-points/game-currency.md) (Software and apps): A game lets players convert in-game gems into a real donation at a fixed rate. The player picks the charity; the studio pays, and level, items and season pass stay untouched. Virtual currency at a fixed rate. Build spec: https://www.charitips.com/docs/demos/loyalty/game-currency.md
- [Solidarity items in an in-game shop](https://www.charitips.com/docs/use-cases/loyalty-points/in-game-shop.md) (Culture and events): In a game's shop, some items are tied to a charity. When the player buys one with gems earned in play, the studio gives 1 € or 2 € for it; the player never pays. 1 € or 2 € from the studio for each solidarity item bought. Build spec: https://www.charitips.com/docs/demos/loyalty/in-game-shop.md
- [Employee solidarity voucher](https://www.charitips.com/docs/use-cases/loyalty-points/solidarity-voucher.md) (Professional services): An employer funds a 60 € solidarity voucher for each employee. In the benefits portal, the employee gives all or part of it to the charity they pick; the rest stays for later. A 60 € voucher funded by the employer, given all or part. Build spec: https://www.charitips.com/docs/demos/loyalty/solidarity-voucher.md