Merge Tags Reference

Email templates use {tag} placeholders that the merge-tag system resolves to real values when the message is sent. Merge tags are registered in includes/emails/class-igcf-merge-tags.php and grouped by context (for example campaign, pledge, backer). Register your own on the igcf_register_merge_tags action.

This page documents the two payment-related tags in the pledge group that were added in 0.22.0. Both prefer the payment attempt passed to the email — the amount that actually left the backer’s card — but they differ in what they do without one: {charged_amount} falls back to the pledge, while {charge_breakdown} resolves to an empty string.

Pledge group

Tag	Description
{charged_amount}	The amount actually charged, which may be larger than the pledge (for example when an add-on adds fees or a tip).
{charge_breakdown}	An itemised HTML breakdown of the charge, or an empty string when there is nothing extra to show.

{charged_amount}

Returns igcf_format_amount() of $data['attempt']->amount, formatted in the attempt’s own currency. This mirrors Igcf_Pledge_Breakdown::for_attempt(): the attempt currency wins so a cross-currency charge headline matches its breakdown total. If the attempt has no currency, it falls back to the pledge currency; if there is no attempt at all, it falls back to the pledge amount and pledge currency. With neither, it returns an empty string.

Because it reads the attempt, {charged_amount} can exceed {pledge_amount} — they are two separate figures and should never be merged into one “contribution total”.

{charge_breakdown}

Returns an empty string unless $data['attempt'] is an Igcf_Payment_Attempt and the breakdown built by Igcf_Pledge_Breakdown::for_attempt() passes Igcf_Pledge_Breakdown::is_renderable(). When it is renderable, it returns the itemised breakdown HTML from:

igcf_render_pledge_breakdown(
  $breakdown,
  array(
    'variant'     => 'email',
    'total_label' => __( 'Total charged', 'ignition-crowdfunding' ),
  )
);

A charge equal to the pledge — the default on a core-only install — is not renderable, so the tag resolves to an empty string and no table appears.

Worked example

The payment-received email template (public/views/emails/payment-received.php) uses both tags and guards the breakdown with the same condition the {charge_breakdown} tag uses internally, so the surrounding copy only promises a breakdown when one will actually render:

$igcf_has_breakdown = ! empty( $igcf_args['attempt'] )
  && $igcf_args['attempt'] instanceof Igcf_Payment_Attempt
  && Igcf_Pledge_Breakdown::is_renderable(
    Igcf_Pledge_Breakdown::for_attempt( $igcf_args['attempt'] )
  );

When there is a breakdown, the copy names both figures and then renders the table:

We received your payment of {charged_amount}. {pledge_amount} of that is your pledge to {campaign_name}; the breakdown below shows the rest.

{charge_breakdown}

When the charge equals the pledge, the guard is false, so the template falls back to a single-figure sentence and emits no {charge_breakdown}:

We received your payment of {charged_amount} for your pledge to {campaign_name}.

Currency is per pledge, not per site

Two long-standing tags were corrected in 0.22.0 to format their figure in the currency the pledge was actually taken in, rather than the site’s current currency setting:

• {pledge_amount} — the pledge amount.
• {payment_instructions} — the offline instructions block, whose {amount} placeholder tells a backer how much to send.

This was not only a wrong symbol. igcf_format_amount() reads the currency’s exponent, so a ¥5,000 pledge (a zero-exponent currency) rendered on a two-decimal site read $50.00 — the wrong currency and off by a factor of a hundred. If you register your own money tag, always pass the pledge’s or attempt’s own currency as the second argument.

{pledge_net} is a charge figure

{pledge_net} resolves to everything charged for a pledge less everything refunded — what the backer has paid in total. On a charge carrying an add-on’s voluntary additions that is not the campaign’s share, so backer-facing copy must not describe it as a contribution. The partial-refund email says “You have now paid … in total for this pledge” for exactly this reason. Its registered label still reads “Net Contribution”, which is stale relative to the copy.

See also

• igcf_register_merge_tags — the action to register your own merge tags.
• Igcf_Pledge_Breakdown — the service behind {charge_breakdown}.
• Email Notifications — the administrator-facing guide to which emails send when.