# Demo: A share of each subscription

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

One variant of **A saved choice, a periodic statement**, in Software and apps: 1 % of each plan, every renewal.

A made-up site, your-app.example/settings/billing, 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 and their profiles. Your own UI, built with the API: the plans, the button that saves the charity and the giving summary.

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

The full guide, with edge cases: https://www.charitips.com/docs/use-cases/subscription-share.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": "Plan 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": "1 % of every plan",
    "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 1 % of your plan

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

- The customer picks a charity from your selection.
- Button: Save

No call: this screen only shows the result.

### 2. Your waiting donations go to your charity

The donations of invoices paid before the choice were created without a charity. Once the workspace saves one, your server claims each of them for it.

- Button: Save

**Your server calls:**

- [`POST /v1/donations/{donationId}/claim`](https://www.charitips.com/docs/api-reference/claim-donation.md) Claim a donation: for each donation still waiting, found with list-donations and the workspace's externalId

  ```json
  {
    "charityId": "<charityId>"
  }
  ```

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

### 3. Payment received

- Team plan, October: 49,00 €
- Our 1 % donation: 0,49 €
- **You pay: 49,00 €**
- Button: Simulate the next renewal

**Your server calls:**

- [`POST /v1/donations`](https://www.charitips.com/docs/api-reference/create-donation.md) Create a donation: on every paid invoice; with the saved charity as charityId, or without it while none is saved, so the donation waits for the choice; amount in cents

  ```json
  {
    "campaignId": "<campaignId>",
    "amount": 49,
    "charityId": "<charityId>",
    "uniqueExternalId": "invoice_2026_10_0042",
    "externalId": "workspace_88"
  }
  ```

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

### 4. Refund

The invoice is refunded: your server deletes its donation, as long as it is not billed yet.

- Button: Refund this invoice

**Your server calls:**

- [`DELETE /v1/donations/{donationId}`](https://www.charitips.com/docs/api-reference/delete-donation.md) Delete a donation: donationId kept with the invoice; once billed, the donation stays

## Clone it with a coding agent

```prompt
Clone the Charitips demo "A share of each subscription" into this project. Read https://www.charitips.com/docs/demos/subscription.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.
```