Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 30 additions & 21 deletions docs/email-customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ Everything here was verified against the plugin's own code and Gravity Forms
core. Where a hook is a Gravity Forms hook rather than one of ours, that is
stated, so you know who owns it.

Two defects found while writing this are now fixed: the built-in email used to
send unconditionally alongside a configured notification, and a terminal
failure used to announce two events. Both produced two emails for one failed
payment.

## What already exists (build in the UI, don't code)

The plugin gives you a **merge tag**, not an email template:
Expand All @@ -28,34 +33,38 @@ notification on:
So a dunning email with your own design is: one notification, event set to
*Subscription Payment Failed*, body containing `{chip_update_card_link}`.

### Read this before configuring that notification
### The built-in email steps aside for yours

The plugin sends a **built-in fallback email** on every failed renewal, and it
does so unconditionally — it does not check whether you have configured a
notification for the event. **Verified on a live install:** with a
*Subscription Payment Failed* notification configured, one failed renewal
produced **two** messages:
The plugin sends a built-in fallback email so dunning works with no setup at
all. When you configure a notification on *Subscription Payment Failed*, the
built-in email **stands down** and yours is the only one the customer receives.

```
1. to=customer@example.com Action needed: payment failed for your subscription
2. to=probe@example.com the configured notification
```
The stand-down is decided the way Gravity Forms itself decides whether a
notification will send, so it holds in the cases that catch people out:

So use one or the other:
- a notification you have switched **off** does not suppress the built-in —
otherwise a merchant who parked their notification would leave the customer
with nothing
- a notification whose **conditional logic** will not pass for this entry does
not suppress it either — the fallback exists for the entries nothing else
covers

- Configure the notification and design it, or
- Configure nothing and let the built-in email do the work.
Pressing **Send update-card link** in the admin always sends, regardless. That
is a deliberate act by support, not the automated fallback.

If you need both — a designed customer email and an admin alert on the same
event — put your customer-facing message on the plugin's built-in email and
keep the admin one on a different event.
## The end of the retry ladder

There is a further consequence: a failure that exhausts the retry ladder fires
**both** the failed and the expired event in the same run, so a notification on
each sends twice. Make them distinct messages, not variations of one.
When the last retry fails the subscription is **expired** in the same pass, and
that is the only event announced — *Subscription Expired*. The failure event is
not also fired, so a notification on each will not produce two emails for one
payment.

Both are worth fixing in the plugin — the fallback should stand down when a
notification is configured. Documented here rather than silently worked around.
The built-in email is not sent on that path either. The card-update link stops
working the moment the subscription is expired, so an email carrying one would
hand the customer a link that is already dead. Customers are dunned on every
attempt *before* that, while action is still possible — so make the
*Subscription Expired* notification the one that tells them the subscription
has ended.

## When the customer saves a card on a failed renewal

Expand Down
62 changes: 61 additions & 1 deletion includes/class-gf-chip-renewal-notifications.php
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,53 @@ public static function should_send_dunning( $attempt_index, $last_dunned ) {
return (int) $attempt_index > (int) $last_dunned;
}

/**
* Whether Gravity Forms will send a notification for this event itself.
*
* The built-in email is a fallback, so it stands down when the merchant has
* built their own — otherwise one failed payment produces two emails.
*
* Mirrors what Gravity Forms does before sending, rather than just counting
* configured notifications. Both gates matter:
*
* - `isActive`. A notification the merchant has switched off is not a
* reason to stay silent. `GFCommon::get_notifications()` does NOT filter
* on this, so reading it and stopping there would send the customer
* nothing at all when the merchant had merely parked their own.
* - conditional logic. A notification that will not pass its conditions
* never sends, so the fallback must still cover that entry. Core's own
* evaluator is called, not a reimplementation: it returns true when a
* notification carries no conditions.
*
* @param string $event The event about to be dispatched.
* @param array $form The form the notification would be read from.
* @param array $entry The entry, for conditional logic.
* @return bool
*/
public static function has_active_notification( $event, $form, $entry ) {
if ( ! is_array( $form ) ) {
return false;
}

foreach ( (array) rgar( $form, 'notifications' ) as $notification ) {
if ( (string) rgar( $notification, 'event' ) !== (string) $event ) {
continue;
}

if ( isset( $notification['isActive'] ) && ! $notification['isActive'] ) {
continue;
}

if ( ! GFCommon::evaluate_conditional_logic( rgar( $notification, 'conditionalLogic' ), $form, $entry ) ) {
continue;
}

return true;
}

return false;
}

/**
* The subject line for the fallback dunning email.
*
Expand Down Expand Up @@ -307,11 +354,17 @@ private static function strip_tag( $text ) {
* that can be updated — emailing a link to a cancelled subscription would
* send the customer somewhere that tells them there is nothing to do.
*
* Stands down when the merchant has configured a Gravity Forms notification
* that will fire for this event: two emails about one failed payment is
* worse than none, and the merchant's own design wins. The stand-down is
* skipped for an explicit send ($force), because an operator pressing
* "Send update-card link" is asking for this email deliberately.
*
* @param int $entry_id Entry id.
* @param int $attempt_index Current attempt index.
* @param bool $force Send even if already dunned for this attempt.
* @param array $extra Optional currency/amount overrides.
* @return bool
* @return bool Whether an email was sent.
*/
public static function maybe_send_dunning_email( $entry_id, $attempt_index, $force = false, $extra = array() ) {
$entry = GFAPI::get_entry( $entry_id );
Expand All @@ -326,6 +379,13 @@ public static function maybe_send_dunning_email( $entry_id, $attempt_index, $for
return false;
}

// The merchant's notification takes priority over the built-in email.
// Checked before a link is issued, so a suppressed send leaves no
// trace behind it either.
if ( ! $force && self::has_active_notification( self::EVENT_FAILED, GFAPI::get_form( rgar( $entry, 'form_id' ) ), $entry ) ) {
return false;
}

$recipient = self::resolve_recipient( $entry );

if ( '' === $recipient ) {
Expand Down
44 changes: 29 additions & 15 deletions includes/class-gf-chip.php
Original file line number Diff line number Diff line change
Expand Up @@ -2483,21 +2483,19 @@ private function handle_renewal_failure( $entry, $feed, $purchase, $result, $pla
'error'
);

// Tell the customer. One email per attempt position, so a cron that
// runs twice inside a retry window does not send two identical
// messages. Sent only to the entry's own address.
GF_Chip_Renewal_Notifications::maybe_send_dunning_email( $entry_id, $retry_count );

$this->post_payment_action(
$entry,
array(
'type' => GF_Chip_Renewal_Notifications::EVENT_FAILED,
'amount' => rgar( $plan, 'amount' ),
'transaction_id' => $purchase,
'payment_status' => 'Failed',
)
);

// The ladder is exhausted, so the subscription ends in this same pass.
//
// ONE event is announced here, not two. The failure and the expiry are
// the same moment, and firing both means two emails for one payment --
// a merchant who configured a notification on each would double-message
// the customer. The expiry is what has actually happened, so it is the
// expiry that gets announced.
//
// The built-in "update your card" email is deliberately not sent on this
// path either. The card-update link stops working the moment the
// subscription is expired, so mailing one here hands the customer a link
// that is already dead by the time they click it. They were dunned on
// every earlier attempt, while action was still possible.
if ( null === $next ) {
gform_update_meta( $entry_id, 'chip_sub_status', 'expired', $form_id );
gform_update_meta( $entry_id, 'chip_sub_next_payment', '', $form_id );
Expand All @@ -2524,6 +2522,22 @@ private function handle_renewal_failure( $entry, $feed, $purchase, $result, $pla
);
}

// There are retries left, so the customer still has something to do.
// One email per attempt position, so a cron that runs twice inside a
// retry window does not send two identical messages. Sent only to the
// entry's own address.
GF_Chip_Renewal_Notifications::maybe_send_dunning_email( $entry_id, $retry_count );

$this->post_payment_action(
$entry,
array(
'type' => GF_Chip_Renewal_Notifications::EVENT_FAILED,
'amount' => rgar( $plan, 'amount' ),
'transaction_id' => $purchase,
'payment_status' => 'Failed',
)
);

gform_update_meta( $entry_id, 'chip_sub_status', 'on-hold', $form_id );
gform_update_meta( $entry_id, 'chip_sub_next_payment', $next, $form_id );

Expand Down
6 changes: 6 additions & 0 deletions readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,12 @@ In the WordPress admin, open the entry for the subscription under **Forms → En

Yes. The plugin adds three notification events you can attach a notification to: **Subscription Renewed**, **Subscription Payment Failed**, and **Subscription Expired**. It also provides the merge tag `{chip_update_card_link}`, which inserts a secure card-update link for that customer. The link is generated fresh each time a notification sends, so a link that has already been used is replaced by a working one.

= Will customers get two emails if I write my own dunning notification? =

No. The plugin sends a built-in dunning email so recovery works with no setup, and that email steps aside as soon as you configure a notification on **Subscription Payment Failed** — yours is then the only one the customer receives. A notification you have switched off, or one whose conditional logic does not pass for that entry, does not count as a replacement: the built-in email still covers those customers. Re-sending the link from the admin always sends, since that is a deliberate action.

When the retry ladder is exhausted the subscription is marked **Expired** and only that event is announced, so a notification on both **Subscription Payment Failed** and **Subscription Expired** will not double up. The built-in email is not sent at that point either — an update-card link stops working once the subscription is expired, so customers are dunned on the attempts before it instead.

= Are subscription payments refundable? =

Subscription charges appear in the entry's payment transactions and can be refunded like any other payment, subject to CHIP's refund policy. Refunds do not cancel the subscription — cancel it separately if you also want charges to stop.
Expand Down
Loading
Loading