# Demo: A campaign for a date

> A store runs a one-day campaign with a fixed budget, for example 10 000 € on Earth Day. Each order of the day gives 5 €, billed at activation, until the budget runs out.

One variant of **A campaign for a date**, in Retail: A fixed budget spent on the orders of Earth Day.

A made-up site, your-brand.example/earth-day, 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 date's banner and budget, the order confirmation, the button that gives the donation and the card that confirms it.

The full guide, with edge cases: https://www.charitips.com/docs/use-cases/campaign-for-a-date.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": "Earth Day charities",
    "charityIds": [
      "<charityId>"
    ]
  }
  ```
- [`POST /v1/campaigns`](https://www.charitips.com/docs/api-reference/create-campaign.md) Create a campaign: once: a time-limited campaign with its budget, billed at activation

  ```json
  {
    "name": "Earth Day",
    "type": "TIME_BASED",
    "endDate": "2027-04-22",
    "amountType": "FIXED_AMOUNT",
    "budget": 1000000,
    "charitiesSelectionId": "<charitiesSelectionId>"
  }
  ```
- [`POST /v1/campaigns/{campaignId}/activate`](https://www.charitips.com/docs/api-reference/activate-campaign.md) Activate a campaign: once: the whole budget is billed, then the campaign takes donations

## Screens and calls

### 1. Today, every order gives 5 €

On 22 April only, up to 10 000 € in all. Once the budget is spent, the API answers 400 INSUFFICIENT_CAMPAIGN_BUDGET and the order goes through without a donation. After the end date it answers 403, so your server stops asking.

- Organic cotton tee: 35,00 €
- **Total: 35,00 €**
- Button: Buy now, 35,00 €

**Your server calls:**

- [`POST /v1/donations`](https://www.charitips.com/docs/api-reference/create-donation.md) Create a donation: from your payment webhook, for each order of the day; amount in cents

  ```json
  {
    "campaignId": "<campaignId>",
    "amount": 500,
    "uniqueExternalId": "order_2204"
  }
  ```

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

### 2. Choose the charity for your 5 €

The confirmation page shows the Earth Day charities, the most chosen one marked from the campaign metrics your server already caches. Without a choice, the donation still goes to one of them: none is lost.

- The customer picks a charity from your selection.
- Button: Give 5 € to the charity

**Your server calls:**

- [`POST /v1/donations/{donationId}/claim`](https://www.charitips.com/docs/api-reference/claim-donation.md) Claim a donation: donationId from the create-donation response

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

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

### 3. Where Earth Day goes

A public page with the running total, the share of each charity and what it funds, read on your server and cached.

- Button: See where Earth Day goes

**Your server calls:**

- [`GET /v1/campaigns/{campaignId}/metrics`](https://www.charitips.com/docs/api-reference/get-campaign-metrics.md) Get campaign metrics: on your server, cached for a few minutes; totalDonation, numberOfDonations and sortedCharities

## Clone it with a coding agent

```prompt
Clone the Charitips demo "A campaign for a date" into this project. Read https://www.charitips.com/docs/demos/moment.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.

- [A date with a budget](https://www.charitips.com/docs/use-cases/campaign-for-a-date/campaign-for-a-date.md) (Retail): A store runs a one-day campaign with a fixed budget, for example 10 000 € on Earth Day. Each order of the day gives 5 €, billed at activation, until the budget runs out. A fixed budget spent on the orders of Earth Day. Build spec: https://www.charitips.com/docs/demos/moment.md
- [Flash sale](https://www.charitips.com/docs/use-cases/campaign-for-a-date/flash-sale.md) (Retail): During a two-hour flash sale, a shop gives 5 % of each order into a capped pot. The buyer picks the charity after payment; the shop pays and the price does not change. 5 % of the sales during the slot. Build spec: https://www.charitips.com/docs/demos/moment/flash-sale.md
- [Happy hour](https://www.charitips.com/docs/use-cases/campaign-for-a-date/happy-hour.md) (Hotels and restaurants): A restaurant's charity happy hour puts 5 % of each order into the evening's pot for a named charity. At 8 pm, the till sends the pot as one donation; the restaurant pays. 5 % of the evening's happy-hour sales. Build spec: https://www.charitips.com/docs/demos/moment/happy-hour.md
- [In-game charity event](https://www.charitips.com/docs/use-cases/campaign-for-a-date/game-event.md) (Software and apps): A game runs a timed charity event: each challenge cleared adds 0,10 € to a pot for a named charity, up to a set budget. The server sends each hour's pot; the studio pays. 0,10 € per challenge, into a capped pot. Build spec: https://www.charitips.com/docs/demos/moment/game-event.md