About Donation Campaigns

The Donation Campaign service enables you to create and manage fundraising campaigns on your site. Each campaign can be configured with specific goals, custom/predefined donation amounts, and progress tracking capabilities.

Using the Donation Campaign service, your app can:

  • Create and manage donation campaigns with specific fundraising goals.
  • Configure donation frequencies including one-time and recurring donations.
  • Set up custom or predefined donation amounts.
  • Track campaign progress and metrics.
  • Manage campaign lifecycles (activation, deadlines, completion).

Before you begin

It's important to note the following points before starting to code:

Donation amounts and frequencies

When creating donation campaigns, you must configure custom or predefined donation amounts (or both) for each campaign:

  • customAmountEnabled: Allows donors to specify their own amount.
  • predefinedDonationAmounts: Suggested donation options.

Enable both options for maximum flexibility.

At least one of the following donationFrequencies must be specified for each campaign:

  • ONE_TIME: Single donation.
  • WEEK: Weekly recurring donations.
  • MONTH: Monthly recurring donations.
  • YEAR: Yearly recurring donations.

Campaign goals and status

  • When setting up campaign goal, a target amount is required.
  • Campaign status is automatically calculated based on current state:
    • COLLECTING: Campaign is actively accepting donations.
    • EXPIRED: Campaign has passed its end date and acceptDonationsAfterEndDate is false.
    • GOAL_REACHED: Campaign has reached its target amount and acceptDonationsAfterGoal is false.
  • Status transitions are automatic and cannot be set manually.

Currency support

  • Currently supports donations in the site's default currency only.
  • Multi-currency donation support is planned for future releases.
  • Metrics are reported only in the site's default currency.

Campaign lifecycle

Understanding the donation campaign lifecycle is crucial for effective implementation:

1. Creation and setup

  1. Create a campaign with basic information.
  2. Configure custom donation amounts, predefined donation amounts, or both.
  3. Set donation frequencies.
  4. Optionally configure end date and post-completion behaviors.
  5. The campaign is automatically activated and can accept donations.

2. Active collection period

  • The campaign status is COLLECTING.
  • Donors can contribute based on preconfigured donation amounts.
  • Progress is tracked and can be retrieved via metrics endpoint.
  • Campaign settings can be updated while maintaining donation history.

3. Campaign completion

Campaigns can reach completion in two ways:

Goal achievement:

  • When total donations reach the target amount.
  • If acceptDonationsAfterGoal is false, status becomes GOAL_REACHED and donations stop.
  • If acceptDonationsAfterGoal is true (default), donations continue beyond the goal.

Time expiration:

  • When the current date passes the configured endDate.
  • If acceptDonationsAfterEndDate is false (default), status becomes EXPIRED and donations stop.
  • If acceptDonationsAfterEndDate is true, donations continue past the end date.

4. Post-completion

  • Completed campaigns can still be queried and their metrics retrieved.
  • Campaign settings can be updated to reactivate collection if needed.
  • Historical donation data is preserved.

Metrics and reporting

Campaign metrics provide insights into fundraising progress:

  • Available data: Total donation count and amount collected.
  • Currency: Currently limited to the site's default currency.
  • Real-time: Metrics reflect successful donations processed by the system.

Error handling

Be prepared to handle these common scenarios:

  • NO_PAYMENT_DEFINITION: At least one donation amount setting must be configured - customAmountEnabled and/or predefinedDonationAmounts.
  • NON_POSITIVE_CAMPAIGN_GOAL_AMOUNT: Campaign goal target amount cannot be negative or zero.
  • INVALID_CUSTOM_AMOUNT_RANGE: Maximum custom amount must be greater than minimum custom amount.
  • DUPLICATE_PREDEFINED_AMOUNTS: Predefined donation amounts cannot contain duplicate values.
  • NON_POSITIVE_PREDEFINED_AMOUNT: Predefined donation amounts cannot be negative or zero.
  • EMPTY_CAMPAIGN_NAME: Campaign name cannot be empty.
  • SITE_CURRENCY_UNAVAILABLE: Temporary issue reading store settings - retry the request.
  • EMPTY_ASSIGN_AND_UNASSIGN_LISTS: Tag operations require at least one tag to assign or unassign.
  • CAMPAIGN_GOAL_NOT_SET: Campaign goal must be configured before retrieving metrics.
  • METRICS_TEMPORARILY_UNAVAILABLE: Campaign metrics are temporarily unavailable - retry the request.

Use cases

Terminology

  • Campaign goal: The optional target fundraising amount with end date and completion behaviors.
  • Custom amount: Configuration allowing donors to specify their own contribution amount within optional limits.
  • Predefined amount: Preset donation amounts presented as options to donors, optionally with impact descriptions.
  • Donation frequency: The recurring interval for donations (one-time, weekly, monthly, or yearly).
  • Campaign status: Automatically calculated state indicating whether the campaign is collecting, expired, or has reached its goal.
Did this help?