Email Templates

From invoice receipts to declined payments, Recurly can email your subscribers on your behalf. The emails can be customized to match your brand and enabled one-by-one so that you have control over which messages are sent to your customers over their subscription lifecycle.

Email Types

Recurly can send emails for the below actions. Emails can only be sent to accounts with a valid email address, which cannot be "@test.com" or "@example.com". If an account does not have an email address, Recurly will only send the email to the site billing contact. Please note that, unless you customize the content, these emails will always be sent in English.

Account Templates

Activate Account

Sent when a customer visits your hosted account management login page and requests to create an account for the email address they used for their subscription signup.

Password Reset

Sent when a customer visits your hosted account management login page and requests a password reset.

Password Has Been Reset

Sent when a customer changes their password via reset link or while logged in. This email alerts them of the change in case they did not make it.

New Invoice

Sent when a manual invoice is generated, or when a new subscription using manual collection is created on account. This email is only relevant to manual payments.

Payment Confirmation

Sent whenever payment is successfully processed through Recurly. This email will not be sent for $0 invoices. Email is not sent for new subscribers as they receive the New Subscription email instead.

You can choose to send this email to all your customers, regardless of payment method or, per Mastercard mandate, to only customer's using Mastercard (includes debit and credit).

Per Mastercard's regulations, explicit details on how to cancel a subscription must be included in the email.

Please refer to the contractual obligations of your Mastercard agreement for more details.

Payment Refunded

Sent when a customer's transaction has been refunded (either full or in part).

Subscription Templates

New Subscription

Sent when the customer successfully signs up for a subscription with a future start date is activated. This initial email includes the customer's first invoice.

Subscription Change

Sent when a customer's subscription is changed. When a customer's subscription is changed "at term renewal", the email will be sent at the time of the change. However, if a subscription term contains more than 1 billing period, the email may not reflect the change applied since the email will only reflect the next invoice. (if Credit Invoices has not yet been enabled on your site, at renewal changes will only trigger this email when the change is applied)

Subscription Canceled

Sent when the customer selects to cancel their subscription. The Subscription Expired email would be sent when the canceled subscription reaches the end of its bill cycle.

Subscription Expired

Sent when a subscription is either immediately terminated or when a canceled subscription has reached the end of its bill cycle.

Trial Ending

Sent 3 days prior to the end of a customer's free trial as a reminder that their trial will be converting to a paid subscription. This is required by law in many regions. Can only be enabled if trial length is greater than 3 days (see below for more info).

Term Renewal Reminder

Sent as a reminder of a customer's subscription renewal to remind them of their upcoming term renewal. The date of this email is configurable with a range of 1-180 days in advance. This is required by law in many regions, or based on card brand terms of conditions.

Bill Date Reminder

Sent as a reminder of a customer's subscription renewal to remind them of their upcoming bill date renewal. The date of this email is configurable with a range of 1-180 days in advance. This is required by law in many regions, or based on card brand terms of conditions.

Annual Reminder

This template will be sent to customers on an annual basis from the start date of their subscription. There are state and regional specific mandates which require this notification to be sent annually. Add this email template to plans where there is a term renewal less than one year, based on your compliance needs.

Mastercard Renewal Reminder

Sent only to customers whose recurring payment method is Mastercard (includes debit and credit). Mastercard has specific rules around when this email needs to be sent, and the information that needs to be included. Be sure to meet the specific contractual obligations of your Mastercard agreement.

Per Mastercard’s regulations:

  1. You can configure your emails to be sent 3-7 days prior to the customer’s bill date.
  2. You will wish to ensure that your email includes clear instructions for how the customer can cancel their subscription.

If multiple renewal reminder emails are scheduled for the same days prior, then the Mastercard template will take precedence over other renewal reminder templates.

Ramp Price Change Renewal Notification Template

There is an email template to notify customers of an upcoming pricing change.

  • The Ramp Price Change email template can be configured in your email configuration under the Subscription Renewal templates.
  • This template will be sent to customers when a new ramp interval is starting.
  • There are also new email params that have been added to support this email template:, {{next_ramp_interval_start_date}}, and {{next_ramp_interval_price}}.
  • The Ramp Price Change email will be sent in priority over the other renewal reminder emails when configured the same days prior as the other reminder templates.

SEPA Renewal Reminder

Sent as a reminder of a customer's upcoming subscription bill date if using the SEPA payment method. SEPA has specific rules around when this email template needs to be sent, and the information that needs to be included. Be sure to meet the specific contractual obligations of your SEPA agreement, utilizing the Direct Debit fields.

Credit Card Expired

Sent as a reminder of a customer's upcoming subscription bill date if the credit card on file is either expired at the time of the email reminder or will be expired when the bill date occurs. Only credit cards having expired within 1 month of a recurring subscription transaction will have an email sent.

Gift Card Emails

Recurly's support for Gift Cards includes support for several emails to either the gifter or the recipient. Learn more about Gift Card emails.

Dunning Management Templates

Post-Trial Payment Declined

Sent when the first payment following a free trial is attempted and fails. After the initial failure, this email can be sent additional times according to your Dunning Management settings.

Payment Declined

Sent whenever a payment is attempted and fails. After the initial failure, this email will be sent additional times according to your Dunning Management settings. This email is not sent for failed signup attempts.

Invoice Past Due

Sent when a manual invoice reaches its net terms without recording a payment. After the initial failure, this email will be sent additional times according to your Dunning Management settings. This email is only relevant to manual payments.

Expired for Non-Payment

Sent when a customer has completed the dunning process without making a successful payment. The subscription is terminated at this point.

Enabling and Disabling Email Templates

We offer two options for enabling or disabling email templates on your Recurly site. You have the option to make the setting on a site level for all of your plans, or on a plan-by-plan level.

To disable or enable any email template (except Trial Ending) for your entire site, follow these steps. Note that this will affect all emails sent from your site:

  1. Navigate to your Email Templates page.
  2. Click Customize next to an enabled template, or Enable next to a disabled template.
  3. Click Edit next to Settings.
  4. Change the status dropdown to the status you want.

If you disable an email template at a site level, it will also be disabled for all of your plans.

If you would like to disable an email template at the plan level and continue to use the email template for other plans, follow these steps:

  1. Ensure that the email template is enabled at the site level on the Email Templates page.
  2. Navigate to Customization > Plans.
  3. Find the plan for which you would like to disable a particular email.
  4. Deselect the checkbox next to the email template you would like to disable. Note that the Renewal Reminder and Trial Ending Templates will only be enabled by default if the plan utilizes these emails.
837

Trial Ending and Renewal Reminder Emails

Trial Ending and Renewal Reminder emails allow you to automatically notify your customers before their free trial ends, or their subscription renews. Unlike other emails, the Trial ending email is enabled on a per-subscription plan basis by checking the respective Send Trial Ending Emails? checkbox when creating or editing a plan (FYI, you will only see the option to enable Trial Ending emails if the subscription plan includes a free trial).

Trial Ending Emails

When activated for a plan, subscribers will receive a Trial Ending email 3 days prior to the end of their free trial. If a custom trial period is used, the trial period must be at least 4 days in length in order for the Trial Ending emails to be sent.

Renewal Reminder Emails

When enabled for a plan, subscribers will receive a Subscription Renewal Reminder email based on the configuration of number of days prior to the renewal of their subscription. If a custom plan period is used, the plan period must be at least 2 days greater in length than the configured send day prior, in order for the Renewal Reminders to be sent.

FAQ

What happens if you use the API to override the trial_ends_at date?

If the trial_ends_at date is less than 3 days in the future, the email will not be sent.

If I set a future start date, will the Renewal Reminder be sent?

Yes! As long as the future date is more than 2 days in the future.

If no email address is on file, will the site's default email be used?

Yes. Best practices would be to make sure you collect/pass the email address through to Recurly.

Can you set Renewal Reminders and Trial Ending emails via the API?

Not currently. Your only option is to use the admin console but this is something we are looking to add in the future.

If I enable the Trial Ending or specific Renewal Reminder email templates on a subscription plan, will that effect existing subscribers?

Yes, as long as the existing subscription meets the criteria for one of these emails (3+ days until the trial ends for Trial Ending, or 2+ days until the next subscription renewal for Renewal Reminders) the email will be sent.

Can I include future invoice, subscription, transaction, etc information in the Trial Ending or Renewal Reminder emails?

No, the Trial Ending/Renewal Reminder emails will reference the information available at the time the email is generated. For example, if an account's subscription is scheduled to change at renewal, the emails will reference the current subscription information available on the account, not the new subscription information scheduled to take effect in the future.

Customization

Recurly allows you to customize your emails in a variety of ways, from adding images to inserting dynamic parameters.

Adding CC or BCC Addresses

Recurly gives you the option to add CC/BCC email addresses on any of the automated emails that are sent to your customers. This is especially helpful if you’d like to be notified of certain customer actions, such as when a customer cancels their subscription or when a payment is declined. You can add CC/BCC addresses via your admin console. To do so:

  1. Navigate to your Email Templates page.
  2. Click the Customize button associated with the appropriate email template.
  3. Click the Edit button.
  4. Add the appropriate email address into the CC Email Address field (you can add multiple email addresses separated by a comma).
  5. Click the Update Email Template button.

If necessary, you can then repeat these steps for any other email templates that you’d like to be copied on.
If you’d prefer to be BCC’ed on your emails, you can check the Send email copies as BCC’s box on the Site Settings page under Advanced Settings > Email Settings, then click the Save Changes button.

Customizing the From Address

By default, emails are sent from the company's email address. The from email address can be changed on a per email type basis in the email settings. A sender name can be included by formatting your From field as "Recurly Support" <[email protected]>.

HTML Emails

By default, Recurly sends both a plain-text and HTML email to your customers. Your users’ mail client will display the HTML version if it can, otherwise it will fall back to the text-only version. We recommend customizing both templates to suit your needs. However, you may also choose to disable the HTML version on a per email basis. This setting can be found when editing the settings for an email template.

Header and Footer

Recurly has a default header and footer ({{{header}}} and {{{footer}}}) that are already included in the default email templates. If you remove these tags, the header and footer will not be applied to your emails.

Currencies and HTML Encoded Values

All parameters are HTML encoded by default when enclosed with two curly braces ({{). To properly display a foreign currency, the parameter needs to be enclosed with three curly braces ({{{) – this does not escape the text and allows currency symbols to be displayed properly for non-US currencies.

Boolean Sections

In the new subscription email, it might be helpful to customize the email depending on the presence of a trial. If the subscription has a trial, the email should read "Your credit card will be charged at XXX." Whereas a subscription without a trial might say, "Your credit card was charged." Here is an example:

  {{#subscription_has_trial?}}
  Your credit card will be billed {{{subscription_total_amount}}}
  when your trial expires on {{subscription_trial_ends_at}}.
  {{/subscription_has_trial?}}
  {{^subscription_has_trial?}}
  Your credit card was charged {{{invoice_total_paid}}}.
  {{/subscription_has_trial?}}

In the above example, the ^ character tests that the variable is false. The second code block is executed if the customer is not in a trial period.

This technique also works for testing if a variable has a value. You might not want to display a Next payment date if there is no next payment. This works as follows:

  {{#subscription_next_payment_date}}
  Next Payment Date: {{subscription_next_payment_date}}
  {{/subscription_next_payment_date}}

Invoice Line Items

The New Subscription, Payment Confirmation, Declined Payment, New Invoice, and Invoice Past Due emails all include invoice information. Each invoice contains a collection of line items. To iterate over a list of line items, use the {{#invoice_line_items}} tag to start and {{/invoice_line_items}} to end the block. The template will repeat the text inside those lines for all the line items on the invoice. Here is an example:

{{#invoice_line_items}}
{{{line_amount}}} -- {{line_description}}
{{{line_date}}}
{{/invoice_line_items}}

Subscription Add-ons

To iterate over a list of add-ons, use the {{#subscription_add_ons}} tag to start and {{/subscription_add_ons}} to end the block. The template will repeat the text inside those lines for all the add-ons in the list. Here is an example:

{{#subscription_add_ons}}
{{add_on_name}}
{{add_on_price}}
{{/subscription_add_ons}}

Coupons and Discounts

If you make use of coupons, you will likely want to display discount information on your invoices and hide it when the discount amount is zero. The code below will only display the discount amount if the invoice has a discount applied:

  {{#invoice_has_discount?}}
    {{#invoice_discounts}}
    Coupon: {{coupon_code}} // Good For {{coupon_lifetime}}
    {{/invoice_discounts}}
    Discount: {{{invoice_discount_amount}}}
  {{/invoice_has_discount?}}

If you would like to display account active coupon redemption information, you can use the account_has_coupon and coupons parameters like this:

    {{#account_has_coupon?}}
     {{#coupons}}Coupon: {{coupon_code}} // Good For {{coupon_lifetime}}{{/coupons}}
    {{/account_has_coupon?}}

Note that Single Use coupons that have already been used will not be returned in this list. You will want to use the invoice_has_discounts example above to show any Single Use coupons used on the invoice.

Images

Images can easily be added into your email templates with just a bit of HTML. To include a company logo, edit your email header file to include code like this:

  <body>
  <div style="border-bottom:1px solid #E8E8E8; margin:0px 14px;">
  <img style="padding:0px 0px 6px 0px;" src="http://mycompanylogo.gif"/>
  </div>

Recurly allows you to fully customize your email templates. You may use the following placeholders in your templates and Recurly will replace them with the appropriate parameters. This allows you to customize the emails based on the message type and recipient.

Testing Emails

Live Email Preview

While you are editing an email template, you can click the Preview button while editing. This view will show you a live view of the edits you have made to the template.

174

Sending Test Emails

In addition to live previewing the look and feel of Recurly emails in your browser, you can send a test version of that email to your email account so that you can view the email the same way that your customer will receive it.

To send a test email, navigate to the email edit page. You will see a "Send Test Email" button next to the "Preview" button.

1248

After clicking this button and confirming you'd like to receive a Test Email, an email will arrive in your inbox. If you do not receive the email in your inbox, try checking your spam folder.

Parameters

Company Fields

  • {{company_name}}
  • {{company_email}}
  • {{company_url}}
  • {{company_hosted_account_management_enabled?}}
  • {{company_hosted_account_management_full_access?}}
  • {{company_hosted_account_management_allow_pay_invoice?}}
  • {{company_address1}}
  • {{company_address2}}
  • {{company_city}}
  • {{company_state}}
  • {{company_zip}}
  • {{company_country}}
  • {{company_full_address}}
  • {{company_phone_number}}
  • {{company_vat_number}}
  • {{company_registration_number}}

Subscription Plan Fields

  • {{plan_name}}
  • {{plan_code}}
  • {{plan_description}}
  • {{plan_per_interval}}
    The plan's billing period interval, e.g. "per month" or "per 2 weeks."
  • {{plan_trial_interval}}
    The plan's trial period, e.g. "1 month" or "2 weeks."

Subscription Shipping Address Fields

  • {{subscription_has_shipping_address?}}
    Returns true is the subscription has a shipping address.
  • {{subscription_shipping_nickname}}
  • {{subscription_shipping_first_name}}
  • {{subscription_shipping_last_name}}
  • {{subscription_shipping_address1}}
  • {{subscription_shipping_address2}}
  • {{subscription_shipping_city}}
  • {{subscription_shipping_state}}
  • {{subscription_shipping_zip}}
  • {{subscription_shipping_country}}
  • {{subscription_shipping_phone}}
  • {{subscription_shipping_email}}
  • {{subscription_shipping_vat_number}}
  • {{subscription_full_shipping_address}}
    The shipping address (street 1, street 2, city, state, postal code, country) in one string, separated by commas.

Subscription Change Fields

When a subscription changes, these fields will reflect the new values on the subscription when used in the Renewal Reminder email template.

  • {{change_at_renewal?}}
    Returns true if the subscription has change timeframe of renewal or term_end, OR when the timeframe is bill_date and the total_billing_cycles on the subscription is one
  • or;
  • {{change_at_bill_date?}}
    Returns true if the subscription has change timeframe of bill_date AND the total_billing_cycles on the subscription is greater than one
  • {{change_plan_name}}
  • {{change_plan_description}}
  • {{change_plan_per_interval}}
  • {{change_subscription_quantity}}
  • {{change_subscription_total_amount}}
  • {{change_subscription_unit_amount}}
  • {{change_subscription_add_ons}}

Account Fields

  • {{account_code}}
  • {{account_username}}
  • {{account_first_name}}
  • {{account_last_name}}
  • {{account_full_name}}
  • {{account_company_name}}
  • {{account_email}}
  • {{account_full_address}}
  • {{account_address1}}
  • {{account_address2}}
  • {{account_city}}
  • {{account_state}}
    State or province.
  • {{account_zip}}
    Zip or postal code.
  • {{account_country}}
  • {{account_hosted_maintenance_url}}
    URL with embedded authorization token to automatically log into your hosted account management page. If hosted account management is set to "Guest View Only", this parameter will return the Guest View Edit Billing Info URL. If hosted account management is disabled, this URL will 404. The conditional parameters {{#company_hosted_account_management_full_access?}} and the closing {{/company_hosted_account_management_full_access?}} will need to be removed from the template in order for the Guest View Edit Billing Info URL to generate properly.
  • {{coupons}}
    Returns coupon information if this account has active coupons.
  • {{account_vat_number}}
    The Account Info VAT Number is relevant for customers being issued a manual invoice or if you have your Tax Settings set to have invoices use the Account Info address on the invoice.

Coupon Fields

  • {{coupon_code}}
  • {{coupon_name}}
  • {{coupon_lifetime}}
    A string of either: Forever, Single use, or #months
  • {{coupon_discount_percent?}}
    Returns true is this coupon is a percent off discount
  • {{coupon_discount_amount?}}
    Returns true is this coupon is an amount off discount
  • {{coupon_discount_percent}}
  • {{coupon_discount_amount}}
  • {{coupon_description}}

Billing Info Fields

  • {{billing_payment_method}}
    e.g. Credit Card, PayPal, Amazon Pay, ACH etc...
  • {{billing_cc_type}}
    Credit card type, e.g. Visa, MasterCard, etc. Will not return anything if payment was made through PayPal.
  • {{billing_last_four}}
    Last 4 digits of the credit card number.
  • {{billing_first_name}}
  • {{billing_last_name}}
  • {{billing_address1}}
  • {{billing_address2}}
  • {{billing_city}}
  • {{billing_state}}
    State or province.
  • {{billing_zip}}
    Zip or postal code.
  • {{billing_country}}
  • {{billing_full_address}}
  • {{billing_ip_address}}
    Account's IP address during the last billing info update.
  • {{billing_vat_applicable?}}
    Returns true if the account charges VAT.
  • {{billing_vat_number}}
    Account's VAT number.

Invoice Fields

  • {{invoice_number}}
  • {{invoice_date}}
    Date the invoice was created. This may be different than the {{transaction_date}} if the initial transaction failed. {{transaction_date}} may be empty if there is no transaction required for the invoice.
  • {{invoice_subtotal}}
    Total amount of the invoice after discounts are applied.
  • {{{invoice_discount_amount}}}
    Requires 3 curly brackets. Dollar amount of discount applied to invoice.
  • {{invoice_total_paid}}
    Total amount of payments applied to the invoice.
  • {{invoice_total_due}}
    Total amount outstanding on the invoice. This will be zero if the invoice is paid.
  • {{#invoice_line_items}}
    Requires leading pound sign. Collection of line items on the invoice.
  • {{invoice_po_number}}
    Indicates invoice PO Number for manual invoicing.
  • {{invoice_net_terms}}
    Indicates invoice net terms for manual invoicing.
  • {{invoice_has_tax?}}
    Returns true if the invoice has taxes applied.
  • {{invoice_tax_amount}}
    Total amount of the taxes applied to the invoice.
  • {{invoice_tax_rate}}
    Percentage tax rate that was applied to the invoice, e.g. "7.25%".
  • {{invoice_tax_region}}
    The region for which the taxes were collected, e.g. "CA" or "DE".
  • {{invoice_customer_notes}}
    Any notes that were in the Customer Notes field on the invoice.
  • {{invoice_terms_and_conditions}}
    Any notes that were in the Terms and Conditions field on the invoice.
  • {{invoice_vat_reverse_charge_notes}}
    Any notes that were in the VAT Reverse Charge Notes field on the invoice. This field is only relevant to EU VAT Reverse Charge scenarios.
  • {{invoice_bill_to_full_name}}
  • {{invoice_bill_to_company}}
  • {{invoice_bill_to_full_address}}
  • {{invoice_bill_to_address1}}
  • {{invoice_bill_to_address2}}
  • {{invoice_bill_to_city}}
  • {{invoice_bill_to_state}}
  • {{invoice_bill_to_zip}}
  • {{invoice_bill_to_country}}
  • {{invoice_bill_to_phone}}
  • {{invoice_ship_to_full_name}}
  • {{invoice_ship_to_company}}
  • {{invoice_ship_to_full_address}}
  • {{invoice_ship_to_address1}}
  • {{invoice_ship_to_address2}}
  • {{invoice_ship_to_city}}
  • {{invoice_ship_to_state}}
  • {{invoice_ship_to_zip}}
  • {{invoice_ship_to_country}}
  • {{invoice_ship_to_phone}}

Line Item Fields

  • {{{line_date}}}
    Line item date or date range. Requires 3 curly braces.
  • {{line_description}}
  • {{{line_amount}}}
    Line item total amount. Requires 3 curly braces
  • {{line_amount_is_zero?}}
    Returns true if the line item has a 0 amount.
  • {{{line_unit_amount}}}
    Line item unit amount. Requires 3 curly braces
  • {{{line_quantity}}}
    Line item quantity. Requires 3 curly braces
  • {{line_quantity_is_one?}}
    Returns true if the line item quantity is 1.
  • {{line_accounting_code}}
    Accounting code of the line item's charge.
  • {{line_discount_amount}}
    Returns the line item's discount amount, if one exists. Otherwise, it returns 0. Purchase discounts will return as a positive value. Refund discounts will return as a negative value. Wrap this parameter in the invoice_has_discount check to only show your display if at least one of the line items has a discount. Note that this email parameter is not included in any of the email templates by default, so you will need to edit the template to include the parameter.
  • {{line_external_sku}}
    Used with Item Catalog only. Displays the External SKU of the item sold.
  • {{line_product_code}}
    Displays the Plan Code, Add-on Code, or Item Code of the line item.

Subscription and Add-on Fields

  • {{subscription_expires_at_with_time}}
    Date and Time (adjusted for timezone) when the subscription expires if the subscription has been canceled.
  • {{subscription_trial_ends_at_with_time}}
    Date and time (adjusted for timezone) when the current subscription trial period ends.
  • {{subscription_active?}}
    Returns true if the subscription is currently active.
  • {{subscription_quantity}}
    Subscription quantity.
  • {{subscription_quantity_is_one?}}
    Returns true if the subscription's quantity is one.
  • {{{subscription_total_amount}}}
    Subscription total renewal amount. Requires 3 curly braces.
  • {{subscription_unit_amount}}
    Subscription per unit amount.
  • {{subscription_has_trial?}}
    Returns true if the subscription has a trial period.
  • {{subscription_has_no_trial?}}
    Returns true if the subscription does not have a trial period.
  • {{subscription_trial_without_billing_info?}}
    Returns true if the billing info is empty and reason is no_billing_info_reason? = plan_free_trial. This is useful for Trial Ending emails for free trial subscriptions that don't require billing information to show special messaging about adding a payment method.
  • {{subscription_expires_at}}
    Date when the subscription expires if the subscription has been canceled.
  • {{subscription_current_period_started_at}}
    Date when the current billing period started.
  • {{subscription_current_period_ends_at}}
    Date when the current subscription billing period ends, including trial periods.
  • {{subscription_current_period_ends_at_with_time}}
    Date and time (UTC) when the current subscription billing period ends, including trial periods.
  • {{subscription_next_payment_date}}
    Date when the next payment will be charged.
  • {{subscription_customer_notes}}
    The customer notes saved on the subscription. Will return the site's default customer notes if none specified on the subscription and the site has default customer notes specified.
  • {{subscription_add_ons}}
    Will list any add-ons in the subscription.
  • {{add_on_name}}
    If included in the subscriptions_add_ons block, it will return the name of the add-on.
  • {{add_on_price}}
    If included in the subscriptions_add_ons block, it will return the price of the add-on. If the add-on is usage-based and the percentage of an amount pricing model, this parameter will return a percentage.
  • {{add_on_usage_based?}}
    Returns true if the add-on is usage-based. If included in the subscriptions_add_ons block, it will allow you to isolate usage-based add-ons in order to provide a different pricing display.
  • {{add_on_percentage?}}
    Returns true if the add-on is usage-based and has the percentage of an amount pricing model. If included in the subscriptions_add_ons block, it will allow you to isolate usage-based add-ons that display a percentage for the {{add_on_price}} parameter.
  • {{add_on_measured_unit_display_name}}
    If included in the subscriptions_add_ons block and the add-on is usage-based, this will return the associated measured unit display name.
  • {{add_on_external_sku}}
    Used with Item Catalog only. Displays the External SKU of the item sold as an add-on.
  • {{total_billing_cycles}}} should be changed to {{subscription_total_billing_cycles}}
    Returns the number of billing periods within the current subscription term
  • {{subscription_current_term_started_at}}
    Date when the current subscription term started. Useful to use in Payment Confirmation email for condition when a subscription is going to billed for another term to display new start date
  • {{subscription_current_term_ends_at}}
    Date when the current subscription term will end. If you are creating subscriptions with more than 1 billing period in a term, this field should be used instead of current_billing_period_ends_at to accurately reflect the date of subscription term renewal in the Renewal Reminder email and the date when a change will apply at-term renewal for Subscription Change email.
  • {{renewal_total_billing_cycles}} should be changed to {{subscription_renewal_billing_cycles}}
    If the subscription is auto-renewing, this is the number of billing periods in the next term.
  • {{subscription_term_auto_renew?}}
    Returns true if the subscription is configured to automatically renew for another term after the current term is completed.
  • {{subscription_term_balance}}
    If the subscription has multiple billing periods, the remaining amount due for the subscription
  • {{subscription_remaining_billing_cycles}}
    The remaining number of billing periods in the subscription term
  • {{subscription_total_term_amount}}
    The total cost for the subscription, excluding any usage charges and setup fees
  • {{subscription_shipping_cost}}
    The amount charged to the customer for shipping their goods.
  • {{subscription_shipping_method}}
    The shipping method used on the charge.

Subscriptions

  • {{subscriptions_list}}
    An array. Lists all subscriptions for a given invoice. Each subscription contains the same properties as subscription and two additional properties. This is useful if you allow customers to purchase more than 1 subscription in your checkout.
    First? - boolean Returns true if the element is first in the list.
    Last? - boolean Returns true if the element is last in the list.
  • {{subscriptions_has_many}}
    Returns true if there are more than one subscriptions in subscriptions_list
  • {{subscriptions_includes_trial}}
    Returns true if there are any trial subscriptions present in subscriptions_list
  • {{subscriptions_includes_active}}
    Returns true if any of the subscriptions in subscriptions_list is active
  • {{subscriptions_empty}}
    Returns true if {{subscriptions_list}} contains no subscriptions

Gift Card Fields

  • {{gift_card_redemption_code}}
    The current redemption code of the gift card.
  • {{gift_card_amount}}
    The amount of the gift card.
  • {{gift_card_currency}}
    The currency of the gift card amount.
  • {{gift_card_delivery_first_name}}
    The first name of the gift recipient.
  • {{gift_card_delivery_last_name}}
    The last name of the gift recipient.
  • {{gift_card_personal_message}}
    The personal message for the gift recipient.
  • {{gift_card_gifter_name}}
    The gifter's name specified for the delivery messaging.
  • {{{gift_card_image}}}
    The current gift card product's image.
  • {{gift_card_delivery_method}}
    Whether the gift card has a delivery method of email or post.
  • {{gift_card_delivery_email_address}}
    The gift card recipient's email address.
  • {{gift_card_delivery_address1}}
    The gift card recipient's address1.
  • {{gift_card_delivery_address2}}
    The gift card recipient's address2.
  • {{gift_card_delivery_city}}
    The gift card recipient's city.
  • {{gift_card_delivery_state}}
    The gift card recipient's state.
  • {{gift_card_delivery_zip}}
    The gift card recipient's zip.
  • {{gift_card_delivery_country}}
    The gift card recipient's country.
  • {{gift_card_delivery_phone}}
    The gift card recipient's phone.
  • {{gift_card_delivery_deliver_at}}
    The future delivery date of the gift card.
  • {{#gift_card_has_personal_message?}}
    If the gift card has a value in the personal message field. Useful for hiding the personal message display if one was not included at purchase.
  • {{#gift_card_has_gifter_name?}}
    If the gift card has a value in the gifter name field. Useful for hiding the gifter name display if one was not included at purchase.
  • {{#gift_card_has_image?}}
    If the gift card product has an image currently uploaded. Useful for hiding the image display if the gift card product does not have an image.
  • {{#gift_card_has_deliver_at?}}
    If the gift card has a future delivery date.
  • {{#gift_card_delivery_city?}}
    If the gift card has a city in the delivery address. Useful for hiding an address comma after the city if there is no city in the address.
  • {{#subscription_is_gift?}}
    If the subscription started with a gift card. Useful with account_has_billing_info? below in subscription emails to show special messaging to gift card customers about adding a payment method.
  • {{^account_has_billing_info?}}
    If the billing information on the account doesn't exist. Useful nested under subscription_is_gift? in subscription emails to show special messaging to gift card customers about adding a payment method.

Transaction Fields

  • {{transaction_id}}
    Transaction's UUID: 32-characters, alphanumeric.
  • {{transaction_amount}}
    Transaction dollar amount.
  • {{transaction_status}}
    Transaction status (success/void/decline).
  • {{transaction_date}}
    Transaction date.
  • {{transaction_date_and_time}}
    Transaction Date and Time (adjusted for timezone)
  • {{transaction_declined?}}
    Show if given transaction was declined.
  • {{transaction_success?}}
    Show if given transaction was successful.
  • {{transaction_voided?}}
    Show if given transaction was voided.
  • {{#transaction_ach?}}
    Returns true if the transaction was paid via ACH.
  • {{transaction_decline_details}}
    A brief explanation of why the transaction was declined and how the customer can resolve it.
  • {{transaction_payment_method}}
    e.g. Credit Card, PayPal, Amazon Pay, ACH etc...
  • {{transaction_cc_type}}
    Credit card type, e.g. Visa, MasterCard, etc. Will not return anything if payment was made through PayPal.
  • {{transaction_cc_last_four}}
    Last 4 digits of the credit card number.

Direct Debit Fields

  • {{direct_debit_mandate_id}}
    Mandate information for direct debit transactions made through GoCardless.
  • {{direct_debit_creditor_identifier}}
    Creditor information for charging your customers in direct debit through GoCardless.

Custom Fields

Recurly supports email parameters for the following custom fields:

  • Custom fields on Accounts
  • Custom fields on Plans
  • Custom fields on Subscriptions
  • Custom fields on Items
  • Custom fields on Charges

Email parameters for custom fields allow a merchant to merge a custom field value into their email templates. This will ensure that a merchant’s customers receive the information required in communications sent via Recurly on behalf of the merchant.

Please note
The custom field NAMES may contain only alphanumeric characters and underscores. If any custom field names contain special characters, the special characters will be converted to underscores ( _ ) in the parameter conversion. Any sequences of underscores will then be reduced to a single underscore.

The formatting pattern for all custom field email parameters is as follows:

  • Value of field: line_custom_field_<name> = <value>
    * Example: {{account_custom_field_has_professional_services_engagement}}
    Merging the value for the custom field on the account object that is called "Has professional services engagement".
  • Boolean value of fields (Yes/No): line_custom_field_<name>_<value>?
    * Example: {{account_custom_field_does_customer_have_professional_services_engagement}}
    Is the custom field "Does customer have professional services engagement?" present/populated? Boolean= true/false or yes/no

Resetting Your Templates

Occasionally, Recurly will update the email templates for all our subscribers. The updates will not affect your templates if you have any customizations. If your templates are not using the latest version of the templates, you may reset your templates back to the Recurly defaults. To reset your emails:

  1. Click the Customize button associated with the appropriate email template
  2. Click the Edit button in the “Plain-text Body” or “HTML Body” section
  3. Scroll to the bottom of the page and look for a Reset Template button in bright red. The button is only visible if you have customized your template.
  4. Click the button and agree to the reset.

Resetting your email template will not affect any customizations you have made to the HTML Enabled flag, TO, BCC, or subject line.

Email Deliverability

Recurly sends emails to your subscribers and it is in ours and your best interest to ensure that these emails are received by their intended recipients. Recurly offers best-in-class email deliverability rates.

SPF and DKIM Email Signing

Recurly offers both SPF and DKIM signing of emails. When you configure your email templates and send from email address, Recurly will sign emails using SPF and DKIM, which provide better email deliverability. These emails will be signed by recurly.com (from production) or recurlysandbox.com (from sandbox sites).

We had previously recommended setup instructions to create an SPF record for Recurly emails. This is no longer required.

DMARC Email Signing

In order for emails from Recurly to be delivered, the DMARC policy of the email domain used for your Recurly email must be set to a policy of “p=none”, not “p=quarantine” or “p=reject”.

If you would like to monitor emails sent through Recurly more closely, we recommend setting up a domain for emails sent through recurly (e.g. recurly.yourdomainname.com) and to use a DMARC policy for monitoring.

Dedicated IP Address

For customers on our Enterprise plan, we offer the ability to send emails on a dedicated IP address, which increases the likelihood that an email will be delivered. Contact us to learn more.