Skip to content

docs: how to customise subscription emails - #63

Merged
wzul merged 2 commits into
mainfrom
docs/email-customization
Sep 25, 2026
Merged

wzul merged 2 commits into
mainfrom
docs/email-customization

Conversation

@wzul

@wzul wzul commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator

docs: how to customise subscription emails

Adds docs/email-customization.md, linked from the README, covering what a
merchant can actually use to change the design of subscription emails:

  • the {chip_update_card_link} merge tag as the supported route
  • the three notification events (subscription_renewed,
    subscription_payment_failed, subscription_expired)
  • the plugin's public filters, and an explicit note that there is no filter
    for the email subject, body or content type
  • the Gravity Forms hooks that apply to change the design
    (gform_notification), intercept any outgoing mail (gform_pre_send_email),
    or react to the outcome (gform_post_payment_action)
  • how to change the From address, including the case where a host panel plugin
    has claimed the filter on the last priority and your own filter therefore
    cannot win

Every hook name, arity and method signature was verified against Gravity Forms
core and a live install before being written down. The merge-tag example was
run and resolves a real signed link; a one-time payment correctly resolves to no
link rather than a broken one.

Two findings are documented rather than silently worked around, because both
look like defects in the plugin rather than gaps in the docs:

  1. The built-in fallback email sends unconditionally. It does not check whether
    a notification is configured for the same event, so a customer can receive
    two messages for one failure.
  2. A failure that exhausts the retry ladder fires both the failed and the
    expired event in the same run, so a notification on each will both send.

Fixing either is a behaviour change, not a docs change, so they are recorded
here for a decision rather than bundled into this PR.

Potential Risks & Review Items

  • Documentation only; no code path changes. The README gains one section that
    links to the new file.
  • docs/ is a new directory in this repository. .gitattributes already
    export-ignores dev files from the release zip; confirm whether docs/
    should be excluded there too, or whether it is wanted in the distributed
    plugin. Left as-is here.
  • The two findings above are described as defects. If they are intentional, the
    wording should change before merge.

…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.
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.
@wzul
wzul merged commit 03393a0 into main Sep 25, 2026
7 checks passed
@wzul
wzul deleted the docs/email-customization branch September 25, 2026 09:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant