---
title: "A share of each subscription"
description: "Give a percentage of every plan to the charity your customer selected."
canonical: https://www.charitips.com/docs/use-cases/subscription-share
---

# A share of each subscription

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

This use case is one variant of **A saved choice, a periodic statement**: https://www.charitips.com/docs/use-cases/periodic-statement.md
- **Who pays**: Your company
- **Starts with**: Every period
- **Tax receipt**: In your company's name
- Needs [API access](https://www.charitips.com/docs/overview/plans.md#api-access-for-webhooks-and-credentials) on a validated account. [Plans](https://www.charitips.com/docs/overview/plans.md#what-every-flow-needs)

Interactive demo on the page. The same flow as a build spec: https://www.charitips.com/docs/demos/subscription.md

**This demo is one example**: 1 % of each plan. The same flow also covers:

- [Insurance: unused premiums](https://www.charitips.com/docs/use-cases/periodic-statement/unused-premium.md): An insurer gives part of the premiums it did not pay out in claims, once a year.
- [A share of annual plans](https://www.charitips.com/docs/use-cases/subscription-share.md#give-a-share-on-each-renewal): The donation is made once a year, on the annual renewal, instead of every month.
- [An amount per seat](https://www.charitips.com/docs/use-cases/subscription-share.md#give-a-share-on-each-renewal): A team plan gives a fixed amount for every active seat.
- [Customers vote instead](https://www.charitips.com/docs/use-cases/vote-on-a-budget.md): The year's share becomes a budget your customers split between charities by voting.
- [Billing software for your merchants](https://www.charitips.com/docs/use-cases/account-hierarchy.md): Each merchant gets a child account and gives a share of its own subscriptions, billed to it.

## Build it
- **Calls**: [`create-charities-selection`](https://www.charitips.com/docs/api-reference/create-charities-selection.md), [`create-campaign`](https://www.charitips.com/docs/api-reference/create-campaign.md), [`activate-campaign`](https://www.charitips.com/docs/api-reference/activate-campaign.md), [`claim-donation`](https://www.charitips.com/docs/api-reference/claim-donation.md), [`create-donation`](https://www.charitips.com/docs/api-reference/create-donation.md), [`delete-donation`](https://www.charitips.com/docs/api-reference/delete-donation.md)
- **Webhooks**: `donation_update`, `donation_create`

### 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](https://www.charitips.com/docs/get-started/first-donation.md#3-pick-your-charities).

```bash
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>"
  }'
```

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

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

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

```bash
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>"
  }'
```

### Claim the waiting donations

When the customer saves a charity, find the donations still waiting for it with [List donations](https://www.charitips.com/docs/api-reference/list-donations.md) 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.

```bash
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>"
  }'
```

## Edge cases

- **The invoice is refunded.** [Delete the donation](https://www.charitips.com/docs/api-reference/delete-donation.md) 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.

## Related pages

- [Campaigns](https://www.charitips.com/docs/concepts/campaigns.md)
- [Donation lifecycle](https://www.charitips.com/docs/concepts/donation-lifecycle.md)
- [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md)