From 9d0ae8ddbd1308a868b662b7f7474d789fb8c1dd Mon Sep 17 00:00:00 2001 From: Wan Zulkarnain Date: Fri, 25 Sep 2026 10:36:24 +0200 Subject: [PATCH 1/2] docs: how to customise subscription emails, and two gaps found while writing it Documents what a merchant can actually use to change the design of subscription emails: the {chip_update_card_link} merge tag, the three notification events, the plugin's public filters, and the Gravity Forms hooks that apply. Every snippet and hook name was verified against Gravity Forms core and a live install before being written down, including the arity of each hook and the signature of replace_merge_tag(). Two findings are documented rather than worked around: - The built-in fallback email does not stand down when a notification is configured for the same event, so a customer could receive two messages for one failure. - A failure that exhausts the ladder fires both the failed and expired events in one run. Both look like defects in the plugin's behaviour rather than documentation problems, and are noted as such. --- README.md | 6 + docs/email-customization.md | 212 ++++++++++++++++++++++++++++++++++++ 2 files changed, 218 insertions(+) create mode 100644 docs/email-customization.md diff --git a/README.md b/README.md index a9f4752..38e2d26 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,12 @@ composer install ./vendor/bin/phpunit ``` +## Customising emails + +See [docs/email-customization.md](docs/email-customization.md) for the merge tag, +the available filters, and the Gravity Forms hooks for changing the design of +subscription notifications. + ## Documentation - [API Documentation](https://docs.chip-in.asia) diff --git a/docs/email-customization.md b/docs/email-customization.md new file mode 100644 index 0000000..d4a44b0 --- /dev/null +++ b/docs/email-customization.md @@ -0,0 +1,212 @@ +# Customising subscription emails + +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. + +## What already exists (build in the UI, don't code) + +The plugin gives you a **merge tag**, not an email template: + + {chip_update_card_link} + +Put it in the body of any Gravity Forms notification and it becomes the signed +card-update link, issued fresh for that entry when the notification is sent. + +Use **Forms → Settings → Notifications** to design the email: the subject, the +body, HTML, your logo, your branding. This is the supported way to customise +the design, because Gravity Forms renders and sends it — the plugin only +supplies the link. + +The plugin also registers three notification events you can build a +notification on: + + Subscription Renewed subscription_renewed + Subscription Payment Failed subscription_payment_failed + Subscription Expired subscription_expired + +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 plugin sends a **built-in fallback email** on a failed renewal, and it does +so unconditionally — it does not check whether you have configured a +notification for the event. So if you configure a *Subscription Payment Failed* +notification **and** that fallback fires, the customer receives **two** +messages for the same failure. + +Today the practical answer is to use one or the other: + +- Configure the notification and design it, or +- Configure nothing and let the built-in email do the work. + +If you need both — a designed customer email and an admin alert on the same +event — make the customer notification yours and keep the admin one on a +different event, or suppress one of them in your own code. + +There is a further consequence worth knowing: a failure that exhausts the retry +ladder fires **both** events in the same run, so a notification on +*Subscription Payment Failed* and one on *Subscription Expired* both send. Make +them distinct messages, not variations of one. + +Both of these are worth fixing in the plugin (the fallback should stand down +when a notification is configured). They are documented here rather than +silently worked around. + +## Filters + +The plugin exposes these, all `gf_chip_`-prefixed: + +| Filter | Purpose | +|---|---| +| `gf_chip_card_update_expiry_days` | Lifetime of a card-update link, in days (default 7). | +| `gf_chip_recurring_payment_method_whitelist` | Payment methods a recurring token may be issued for. **Card-only by design** — widening it does not work, because the gateway only issues recurring tokens for cards. | +| `gf_chip_brand_supports_cards` | Force the card capability on/off instead of probing the gateway. | +| `gf_chip_purchases_api_parameters` | Final say over the purchase payload sent to the gateway. Receives `( $params, array( $feed, $submission_data, $form, $entry ) )`. | +| `gf_chip_sslverify` | TLS verification for API calls. Leave it on. | +| `gf_chip_purchase_timezone` | Timezone sent with a purchase. | +| `gf_chip_plugin_settings_fields`, `gf_chip_feed_settings_fields`, `gf_chip_client_info_fields`, `gf_chip_purchase_info_fields`, `gf_chip_miscellaneous_info_fields` | Add fields to the settings screens. | + +**There is no filter for the email subject, body, or content type.** The +built-in fallback email is not templated: those three values are built inline. +That is worth knowing before you go looking for one. + +## Gravity Forms hooks that apply + +These are core hooks, not ours — the plugin does not hook them itself, so if +you use one you are the only thing running on it. + +**To redesign a notification you configured in the UI:** + +```php +// Gravity Forms. Fires for every notification, before it is sent. +add_filter( 'gform_notification', function ( $notification, $form, $entry ) { + if ( 'subscription_payment_failed' !== rgar( $notification, 'event' ) ) { + return $notification; + } + + $notification['message'] = '

' . esc_html( get_bloginfo( 'name' ) ) . '

' . $notification['message']; + + return $notification; +}, 10, 3 ); +``` + +This is the hook to use for HTML, branding and layout. It filters the whole +notification array — `subject`, `message`, `to`, `from` — for any notification. + +**To change what is sent, whatever built it:** + +```php +// Gravity Forms. Last stop before the mailer, for GF-generated mail. +add_filter( 'gform_pre_send_email', function ( $args, $format, $notification, $entry ) { + if ( 'subscription_payment_failed' !== rgar( $notification, 'event' ) ) { + return $args; + } + + $args['subject'] = 'Your card needs attention'; + + return $args; +}, 10, 4 ); +``` + +This one also fires for the plugin's own built-in email, with `$notification` +empty — so it can be used to filter that too. Check `$entry` rather than +assuming a notification. + +**To react to the outcome rather than change the email:** + +```php +// Gravity Forms. Fires for every gateway payment action. +add_action( 'gform_post_payment_action', function ( $entry, $action ) { + if ( 'subscription_payment_failed' !== rgar( $action, 'type' ) ) { + return; + } + + // Your own alerting, CRM, or log. +}, 10, 2 ); +``` + +**To send your own mail instead**, use the merge tag from your own code. The +signature is `( $text, $form, $entry, $url_encode, $esc_html )`: + +```php +$entry = GFAPI::get_entry( $entry_id ); +$form = GFAPI::get_form( rgar( $entry, 'form_id' ) ); + +$body = '

Payment failed

Update your card: here

'; + +$html = GF_Chip_Renewal_Notifications::replace_merge_tag( $body, $form, $entry, false, true ); +``` + +Pass `$esc_html = true` for an HTML body, so the link is escaped for the +attribute it sits in. Verified: a one-time payment resolves to no link at all +rather than a broken one, because there is no future charge to redirect. + +A custom `wp_mail()` call gives you full control of subject, body and HTML. +Note `wp_mail()` sends **plain text by default**; set +`Content-Type: text/html` in the headers for HTML. + +## Changing the content type of the built-in email + +**Do not use `wp_mail_content_type` for this.** That filter is global: it would +turn every other email on the site into HTML for the rest of the request, +including the ones the plugin builds as plain text. + +There is currently no supported way to change the built-in email's content +type. It sets `Content-Type: text/plain; charset=UTF-8` on its own `wp_mail()` +call, and that call is not filtered. + +You can override it anyway with the `wp_mail` filter, since it runs per call — +but you have to identify the message, and the built-in email carries no marker +you can identify it by. Matching on the subject is fragile: change the +notification's subject in the UI and the filter silently stops applying. This +is the gap to close if you need HTML there. + +The built-in email is deliberately plain text: it is a transactional notice +about money, and a text body cannot be broken by a theme, a template plugin or +a mail client's HTML handling. **If you want designed mail, build a +notification in the UI with `{chip_update_card_link}` in the body** — that is +the supported route, and it gives you full control of subject, body, HTML and +layout. + +## Changing who the email comes from + +The plugin never sets a From address. WordPress decides it, from the site name +and host, and Gravity Forms falls back to the admin email when the plugin's +address is not valid. + +To set it site-wide, use the core filters: + +```php +add_filter( 'wp_mail_from', function ( $email ) { + return 'billing@example.com'; +} ); + +add_filter( 'wp_mail_from_name', function ( $name ) { + return 'Example Sdn Bhd'; +} ); +``` + +**Check for another plugin already on these hooks first.** A host panel plugin +commonly sets its own From on the *last* possible priority, and then a filter +of your own at any priority still loses: theirs is registered later and wins +the tie. If you find yourself unable to change the From, that is why — the way +out is to set it on the mailer itself: + +```php +add_action( 'phpmailer_init', function ( $phpmailer ) { + $phpmailer->From = 'billing@example.com'; + $phpmailer->FromName = 'Example Sdn Bhd'; + $phpmailer->Sender = 'billing@example.com'; // the envelope MAIL FROM +} ); +``` + +WordPress calls `setFrom()` and *then* fires `phpmailer_init`, so this is the +last word. Set `Sender` as well: left unset, the mail relay substitutes its own +envelope address, which is how a message ends up with a From that does not +appear in its envelope. + +Whichever route you take, the sending domain must be one your mail service is +authorised to send as, and it should have SPF and DKIM records. A From on a +domain with neither is filtered or junked by the recipient. From f35d4c8f47a54fdd854bc8229811760bab2386fb Mon Sep 17 00:00:00 2001 From: Wan Zulkarnain Date: Fri, 25 Sep 2026 10:39:49 +0200 Subject: [PATCH 2/2] docs: add the money path to the email doc, with verified evidence Records what happens when a customer saves a card on a failed renewal - the question a merchant actually asks before switching dunning over to a designed notification. The charge is decided by subscription state, and the table is the real payload built for a live install, not a reading of the code: past due / on-hold -> 'Outstanding payment', card's subscription amount, charged not due / cancelled / expired -> 'Update payment method', 0, card saved only Also sharpens the double-send note: it now states that the behaviour was reproduced on a live install with a configured notification, and shows the two messages that resulted, rather than asserting it from the code. --- docs/email-customization.md | 59 +++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/email-customization.md b/docs/email-customization.md index d4a44b0..3bed321 100644 --- a/docs/email-customization.md +++ b/docs/email-customization.md @@ -30,29 +30,58 @@ So a dunning email with your own design is: one notification, event set to ### Read this before configuring that notification -The plugin sends a **built-in fallback email** on a failed renewal, and it does -so unconditionally — it does not check whether you have configured a -notification for the event. So if you configure a *Subscription Payment Failed* -notification **and** that fallback fires, the customer receives **two** -messages for the same failure. +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: -Today the practical answer is to use one or the other: +``` +1. to=customer@example.com Action needed: payment failed for your subscription +2. to=probe@example.com the configured notification +``` + +So use one or the other: - Configure the notification and design it, or - Configure nothing and let the built-in email do the work. If you need both — a designed customer email and an admin alert on the same -event — make the customer notification yours and keep the admin one on a -different event, or suppress one of them in your own code. +event — put your customer-facing message on the plugin's built-in email and +keep the admin one on a different event. + +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. + +Both are worth fixing in the plugin — the fallback should stand down when a +notification is configured. Documented here rather than silently worked around. + +## When the customer saves a card on a failed renewal + +The card-update link charges the outstanding amount **as part of saving the +card** — it is not a free token swap. The customer does not have to be chased +separately for the missed payment; settling the card settles the debt. + +Whether it charges is decided by the subscription's state, and the outcome is +visible in the purchase itself. Verified against a live install, printing the +real payload sent to the gateway: + +| Subscription state | Product sent | Amount | Result | +|---|---|---|---| +| Active, past due | Outstanding payment | the subscription amount | **charged** | +| On-hold (dunning) | Outstanding payment | the subscription amount | **charged** | +| Active, not yet due | Update payment method | 0 | card saved only | +| Cancelled | Update payment method | 0 | card saved only | +| Expired | Update payment method | 0 | card saved only | -There is a further consequence worth knowing: a failure that exhausts the retry -ladder fires **both** events in the same run, so a notification on -*Subscription Payment Failed* and one on *Subscription Expired* both send. Make -them distinct messages, not variations of one. +So a customer who is merely replacing an expiring card is **not** charged, and +a customer whose renewal failed **is**. The amount charged is the one the +subscription was set up with, not whatever the form currently resolves to, so a +settled cycle matches what the customer agreed to pay. -Both of these are worth fixing in the plugin (the fallback should stand down -when a notification is configured). They are documented here rather than -silently worked around. +The customer's new card is captured in the same transaction, so there is no +window where the old card is gone and no new one is stored. ## Filters