Recurring Upsell Modal (NGP VAN Payments)

When a donor submits a one-time donation on an NGP VAN Payments page, the recurring upsell modal intercepts the submission and offers them the option to upgrade to a recurring gift. If the donor accepts, the donation is processed as recurring at the suggested amount and period. If they decline, the original one-time donation proceeds.

Enabling the Upsell

The upsell is disabled by default. Enable it with a recurring_upsell custom field on the page or templateset, or via URL parameter. Any truthy value enables it; a falsy value explicitly disables it, overriding a broader setting.

Priority: URL param > page custom field > templateset custom field

Values that enable: 1, true, y, yes (case-insensitive)

Values that disable: 0, false, n, no

Example URL param to suppress upsell on a page that has it enabled:

https://example.com/donate/my-page/?recurring_upsell=0

Requirements: The page must use NGP VAN Payments and support at least one recurring period. The upsell only fires on one-time (non-recurring) submissions.

Customizing Modal Content

Note that the custom fields described below are not created by default, you must add them to your instance before attempting to use them.

recurring_upsell_content

Page or templateset custom field

Full HTML replacement for the modal body. When set, the heading and pitch fields below are ignored. Supports the template placeholders documented under Dynamic Amount Display. The modal close button and CSS are still provided by the template.

This field is for HTML only — <script> tags placed inside it are not guaranteed to execute. To define the akRecurringUpsellComputeAmount JS hook, use recurring_upsell_script (see below).

recurring_upsell_heading

Page or templateset custom field

Heading text at the top of the modal. Supports the template placeholders documented under Dynamic Amount Display. Default: Make it {recurringPeriod}!

Not used when recurring_upsell_content is set.

recurring_upsell_pitch

Page or templateset custom field

Body copy below the heading. Supports the template placeholders documented under Dynamic Amount Display. Not used when recurring_upsell_content is set.

Customizing Button Text

recurring_upsell_accept_text

Page or templateset custom field

HTML for the accept (upgrade) button. Supports the template placeholders documented under Dynamic Amount Display. Default: Yes, donate ${recurringAmount} {recurringPeriod}

recurring_upsell_decline_text

Page or templateset custom field

HTML for the decline button. Supports the template placeholders documented under Dynamic Amount Display, so e.g. No, just donate ${oneTimeAmount} once will echo the original one-time amount. Default: No thanks, make it a one-time gift

Recurring Period

recurring_upsell_period

Page or templateset custom field, or URL parameter

Which recurring period to convert the donor to when they accept the upsell. Valid values: months (default), weeks, years.

When the frequency picker is present (weekly_amounts, monthly_amounts, or annual_amounts URL params), accepting the upsell clicks the corresponding tab, which updates the amount list and sets the recurring period correctly. If the target tab is not present (including when the frequency picker is not shown at all), the Make it monthly checkbox is used and the period is set directly — so recurring_upsell_period=weeks works on a plain donation page without frequency tabs.

The default heading, pitch, and button text use {recurringPeriod}, which is replaced client-side with the human-readable label (monthly, weekly, or annually).

Recurring Amount Calculation

By default the suggested recurring amount equals the one-time donation amount. To suggest a lower ask, configure tiers using recurring_upsell_amount.

recurring_upsell_amount

Page or templateset custom field, or URL parameter

Comma-separated threshold:ask pairs. For a given one-time donation amount, the first tier whose threshold is greater than the donation amount determines the ask. If the donation meets or exceeds all thresholds, the last tier’s ask is used.

Format:

threshold:ask,threshold:ask,...

Example: 10:5,20:10,50:25,1000:50

One-time donation

Recurring ask

$1–$10

$5

$10.01–$20

$10

$20.01–$50

$25

$50.01+

$50 (last tier)

Spaces around values are tolerated. When set as a URL parameter, it takes priority over the custom field value. The tiers apply regardless of which recurring period is configured.

JavaScript Extension Points

recurring_upsell_script

Page or templateset custom field

Custom JavaScript rendered as a standalone <script> block on every page that has the upsell enabled. Use this to define the akRecurringUpsellComputeAmount hook below, or any other client-side customizations. The contents are inserted as-is, so they should be valid JavaScript.

window.akRecurringUpsellComputeAmount

Define this function (typically in recurring_upsell_script) to override the suggested recurring amount calculation:

window.akRecurringUpsellComputeAmount = function(onetimeAmount, period) {
    // Return the recurring ask as a string, e.g. "10.00".
    // Return null/0/"" to skip the upsell entirely and let the one-time donation proceed.
    return (onetimeAmount * 0.5).toFixed(2);
};

The function receives the one-time amount and the configured period (months, weeks, or years). Returning a falsy value (null, "", 0) causes the modal to be skipped and the original one-time donation to proceed.

This hook takes priority over the recurring_upsell_amount tiers.

Dynamic Amount Display

Use these placeholders in button text or recurring_upsell_content to display values that are substituted client-side when the modal opens:

  • {recurringAmount} — the suggested recurring ask

  • {oneTimeAmount} — the original one-time donation amount

  • {recurringPeriod} — the recurring period label (monthly, weekly, or annually)

Placeholders are case-insensitive and tolerate surrounding whitespace, so { RecurringAmount } is equivalent to {recurringAmount}.

Example:

Upgrade to ${recurringAmount} {recurringPeriod}

Tracking

When an upsell interaction occurs, two action custom fields are stored on the donation action:

  • action_recurring_upsell_shown — set to 1 when the modal is displayed

  • action_recurring_upsell_accepted — set to 1 when the donor accepts, 0 when they decline

These can be used in reports to measure upsell conversion rates.