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, payment options, and progress tracking capabilities.

Using the Donation Campaign service, your app can:

• Create and manage donation campaigns with specific fundraising goals.
• Configure payment options 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:

Payment options and donation frequencies

At least one payment option must be configured 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 payment options (custom amounts, predefined 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 configured payment options.
• 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 payment option must be enabled - 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

• Create a fundraising campaign with both custom and predefined donation amounts.
• Monitor campaign progress and adjust settings.
• Manage multiple campaigns with bulk operations.
• Set up recurring donation campaigns.

Terminology

• Donation campaign: A structured fundraising initiative with defined goals, payment options, and duration settings.
• 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.