Repository navigation
docs: how to customise subscription emails - #63
Merged
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs: how to customise subscription emails
Adds
docs/email-customization.md, linked from the README, covering what amerchant can actually use to change the design of subscription emails:
{chip_update_card_link}merge tag as the supported routesubscription_renewed,subscription_payment_failed,subscription_expired)for the email subject, body or content type
(
gform_notification), intercept any outgoing mail (gform_pre_send_email),or react to the outcome (
gform_post_payment_action)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:
a notification is configured for the same event, so a customer can receive
two messages for one failure.
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
links to the new file.
docs/is a new directory in this repository..gitattributesalreadyexport-ignores dev files from the release zip; confirm whetherdocs/should be excluded there too, or whether it is wanted in the distributed
plugin. Left as-is here.
wording should change before merge.