fix(auth): Update SubscriptionUpgrade and SubscriptionSubsequentInvoice emails to handle credits

xlisachan · xlisachan · commit 2fc84405bd04 · 2025-05-13T16:41:26.000-04:00
- updates the subscriptionUpgrade and subscriptionSubsequentInvoice email templates to handle credit amounts Closes: FXA-11636
diff --git a/packages/fxa-auth-server/lib/payments/stripe.ts b/packages/fxa-auth-server/lib/payments/stripe.ts
@@ -3303,7 +3303,7 @@ export class StripeHelper extends StripeHelperBase {
       id: invoiceId,
       number: invoiceNumber,
       currency: paymentProratedCurrency,
-      amount_due: invoiceAmountDue,
+      total: invoiceTotal,
     } = invoice;
 
     // https://github.com/mozilla/subhub/blob/e224feddcdcbafaf0f3cd7d52691d29d94157de5/src/hub/vendor/customer.py#L643
@@ -3344,7 +3344,7 @@ export class StripeHelper extends StripeHelperBase {
       paymentAmountNewCurrency: nextInvoiceCurrency,
       invoiceNumber,
       invoiceId,
-      paymentProratedInCents: invoiceAmountDue,
+      paymentProratedInCents: invoiceTotal,
       paymentProratedCurrency,
     };
   }
diff --git a/packages/fxa-auth-server/lib/senders/email.js b/packages/fxa-auth-server/lib/senders/email.js
@@ -2147,10 +2147,11 @@ module.exports = function (log, config, bounces, statsd) {
           message.acceptLanguage
         ),
         paymentProrated: this._getLocalizedCurrencyString(
-          paymentProratedInCents,
+          Math.abs(paymentProratedInCents),
           paymentProratedCurrency,
           message.acceptLanguage
         ),
+        paymentProratedInCents,
         productPaymentCycleNew,
         productPaymentCycleOld,
         icon: productIconURLNew,
@@ -2717,8 +2718,9 @@ module.exports = function (log, config, bounces, statsd) {
         invoiceLink,
         invoiceNumber,
         invoiceDate,
+        invoiceTotalInCents,
         invoiceTotal: this._getLocalizedCurrencyString(
-          invoiceTotalInCents,
+          Math.abs(invoiceTotalInCents),
           invoiceTotalCurrency,
           message.acceptLanguage
         ),
diff --git a/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/en.ftl b/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/en.ftl
@@ -23,7 +23,8 @@ subscriptionFirstInvoiceDiscount-content-discount-repeating = { $discountDuratio
 # Variables:
 #  $invoiceTaxAmount (String) - The amount of the tax of the subscription invoice, including currency, e.g. $2.00
 subscriptionCharges-content-tax = Taxes & fees: { $invoiceTaxAmount }
-# Variables:
-#  $invoiceDateOnly (String) - The date of the next invoice, e.g. 01/20/2016
-#  $invoiceTotal (String) - The amount, after discount, of the subscription invoice, including currency, e.g. $8.00
+## Variables:
+##  $invoiceDateOnly (String) - The date of the next invoice, e.g. 01/20/2016
+##  $invoiceTotal (String) - The amount, after discount, of the subscription invoice, including currency, e.g. $8.00
 subscriptionFirstInvoice-content-charge = Charged { $invoiceTotal } on { $invoiceDateOnly }
+subscriptionFirstInvoice-content-credit = You have received an account credit of { $invoiceTotal }, which will be applied to your future invoices.
diff --git a/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/index.mjml b/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/index.mjml
@@ -55,7 +55,13 @@
 <% } %>
 
 <mj-text css-class="text-body-no-bottom-margin">
-  <span data-l10n-id="subscriptionFirstInvoice-content-charge" data-l10n-args="<%= JSON.stringify({invoiceDateOnly, invoiceTotal}) %>">
-    Charged <%- invoiceTotal %> on <%- invoiceDateOnly %>
-  </span>
+  <% if (locals.invoiceTotalInCents >= 0 ) { %>
+    <span data-l10n-id="subscriptionFirstInvoice-content-charge" data-l10n-args="<%= JSON.stringify({invoiceDateOnly, invoiceTotal}) %>">
+      Charged <%- invoiceTotal %> on <%- invoiceDateOnly %>
+    </span>
+  <% } else { %>
+    <span data-l10n-id="subscriptionFirstInvoice-content-credit" data-l10n-args="<%= JSON.stringify({invoiceTotal}) %>">
+      You have received an account credit of <%- invoiceTotal %>, which will be applied to your future invoices.
+    </span>
+  <% } %>
 </mj-text>
diff --git a/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/index.txt b/packages/fxa-auth-server/lib/senders/emails/partials/subscriptionCharges/index.txt
@@ -19,4 +19,8 @@ subscriptionFirstInvoice-content-invoice-number-plaintext = "Invoice Number: <%-
   subscriptionFirstInvoiceDiscount-content-discount = "Discount: -<%- invoiceDiscountAmount %>"
 <% } %>
 <% } %>
+<% if (invoiceTotalInCents >= 0 ) { %>
 subscriptionFirstInvoice-content-charge = "Charged <%- invoiceTotal %> on <%- invoiceDateOnly %>"
+<% } else { %>
+subscriptionFirstInvoice-content-credit = "You have received an account credit of <%- invoiceTotal %>, which will be applied to your future invoices."
+<% } %>
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/_versions.json b/packages/fxa-auth-server/lib/senders/emails/templates/_versions.json
@@ -2,7 +2,7 @@
   "subscriptionAccountFinishSetup": 2,
   "subscriptionReactivation": 2,
   "subscriptionRenewalReminder": 2,
-  "subscriptionUpgrade": 4,
+  "subscriptionUpgrade": 5,
   "subscriptionDowngrade": 2,
   "subscriptionPaymentExpired": 3,
   "subscriptionsPaymentExpired": 3,
@@ -13,7 +13,7 @@
   "subscriptionCancellation": 3,
   "subscriptionFailedPaymentsCancellation": 2,
   "subscriptionReplaced": 1,
-  "subscriptionSubsequentInvoice": 3,
+  "subscriptionSubsequentInvoice": 4,
   "subscriptionFirstInvoice": 3,
   "downloadSubscription": 2,
   "fraudulentAccountDeletion": 1,
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionFirstInvoice/index.stories.ts b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionFirstInvoice/index.stories.ts
@@ -20,6 +20,7 @@ const createStory = subplatStoryWithProps(
       'https://pay.stripe.com/invoice/acct_1GCAr3BVqmGyQTMa/invst_GyHjTyIXBg8jj5yjt7Z0T4CCG3hfGtp',
     invoiceNumber: '8675309',
     invoiceTotal: '$20.00',
+    invoiceTotalInCents: 2000,
     invoiceSubtotal: null,
     invoiceTaxAmount: null,
     invoiceDiscountAmount: null,
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionSubsequentInvoice/index.stories.ts b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionSubsequentInvoice/index.stories.ts
@@ -16,6 +16,7 @@ const createStory = subplatStoryWithProps(
     productName: 'Firefox Fortress',
     invoiceDateOnly: '12/14/2021',
     invoiceNumber: '8675309',
+    invoiceTotalInCents: 2000,
     invoiceTotal: '$20.00',
     invoiceSubtotal: null,
     invoiceTaxAmount: null,
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/en.ftl b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/en.ftl
@@ -8,13 +8,15 @@ subscriptionUpgrade-title = Thank you for upgrading!
 # $productName (String) - The name of the new subscribed product, e.g. Mozilla VPN
 subscriptionUpgrade-upgrade-info-2 = You have successfully upgraded to { $productName }.
 
-# Variables:
-# $paymentAmountOld (String) - The amount of the previous subscription payment, including currency, e.g. $10.00
-# $paymentAmountNew (String) - The amount of the new subscription payment, including currency, e.g. $10.00
-# $productPaymentCycleNew (String) - The interval of time from the end of one payment statement date to the next payment statement date of the new subscription, e.g. month
-# $productPaymentCycleOld (String) - The interval of time from the end of one payment statement date to the next payment statement date of the old subscription, e.g. month
-# $paymentProrated (String) - The one time fee to reflect the higher charge for the remainder of the payment cycle, including currency, e.g. $10.00
-subscriptionUpgrade-content-charge-info-different-cycle-2 = You have been charged a one-time fee of { $paymentProrated } to reflect your subscription’s higher price for the remainder of this { $productPaymentCycleOld }. Starting with your next bill, your charge will change from { $paymentAmountOld } per { $productPaymentCycleOld } to { $paymentAmountNew } per { $productPaymentCycleNew }.
+## Variables:
+## $paymentAmountOld (String) - The amount of the previous subscription payment, including currency, e.g. $10.00
+## $paymentAmountNew (String) - The amount of the new subscription payment, including currency, e.g. $10.00
+## $productPaymentCycleNew (String) - The interval of time from the end of one payment statement date to the next payment statement date of the new subscription, e.g. month
+## $productPaymentCycleOld (String) - The interval of time from the end of one payment statement date to the next payment statement date of the old subscription, e.g. month
+## $paymentProrated (String) - The one time fee to reflect the higher charge for the remainder of the payment cycle, including currency, e.g. $10.00
+subscriptionUpgrade-content-charge-prorated = You have been charged a one-time fee of { $paymentProrated } to reflect your subscription’s higher price for the remainder of this billing period ({ $productPaymentCycleOld }).
+subscriptionUpgrade-content-charge-credit = You have received an account credit in the amount of { $paymentProrated }.
+subscriptionUpgrade-content-starting = Starting with your next bill, your charge will change from { $paymentAmountOld } per { $productPaymentCycleOld } to { $paymentAmountNew } per { $productPaymentCycleNew }.
 
 # Variables:
 # $productName (String) - The name of the new subscribed product, e.g. Mozilla VPN
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.mjml b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.mjml
@@ -15,7 +15,12 @@
     </mj-text>
 
     <mj-text css-class="text-body">
-      <span data-l10n-id="subscriptionUpgrade-content-charge-info-different-cycle-2" data-l10n-args="<%= JSON.stringify({paymentAmountNew, paymentAmountOld, paymentProrated, productPaymentCycleNew, productPaymentCycleOld}) %>">You have been charged a one-time fee of <%- paymentProrated %> to reflect your subscription’s higher price for the remainder of this <%- productPaymentCycleOld %>. Starting with your next bill, your charge will change from <%- paymentAmountOld %> per <%- productPaymentCycleOld %> to <%- paymentAmountNew %> per <%- productPaymentCycleNew %>.</span>
+      <% if (locals.paymentProratedInCents < 0) { %>
+        <span data-l10n-id="subscriptionUpgrade-content-charge-credit" data-l10n-args="<%= JSON.stringify({paymentProrated}) %>">You have received an account credit in the amount of <%- paymentProrated %>.</span>
+      <% } else if (locals.paymentProratedInCents > 0) { %>
+        <span data-l10n-id="subscriptionUpgrade-content-charge-prorated" data-l10n-args="<%= JSON.stringify({paymentProrated, productPaymentCycleOld}) %>">You have been charged a one-time fee of <%- paymentProrated %> to reflect your subscription’s higher price for the remainder of this billing period (<%- productPaymentCycleOld %>).</span>
+      <% } %>
+      <span data-l10n-id="subscriptionUpgrade-content-starting" data-l10n-args="<%= JSON.stringify({paymentAmountNew, paymentAmountOld, productPaymentCycleNew, productPaymentCycleOld}) %>">Starting with your next bill, your charge will change from <%- paymentAmountOld %> per <%- productPaymentCycleOld %> to <%- paymentAmountNew %> per <%- productPaymentCycleNew %>.</span>
     </mj-text>
 
     <mj-text css-class="text-body">
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.stories.ts b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.stories.ts
@@ -26,4 +26,26 @@ const createStory = subplatStoryWithProps(
   }
 );
 
-export const Default = createStory();
+export const PositiveProrated = createStory(
+  {
+    paymentProrated: '$60.00',
+    paymentProratedInCents: 6000,
+  },
+  'Charge - Prorated amount is positive'
+);
+
+export const NegativeProrated = createStory(
+  {
+    paymentProrated: '$60.00',
+    paymentProratedInCents: -6000,
+  },
+  'Credit - Prorated amount is negative'
+);
+
+export const NoProrated = createStory(
+  {
+    paymentProrated: '$0.00',
+    paymentProratedInCents: 0,
+  },
+  'Prorated amount is zero'
+);
diff --git a/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.txt b/packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.txt
@@ -4,7 +4,14 @@ subscriptionUpgrade-title = "Thank you for upgrading!"
 
 subscriptionUpgrade-upgrade-info-2 = "You have successfully upgraded to <%- productName %>."
 
-subscriptionUpgrade-content-charge-info-different-cycle-2 = "You have been charged a one-time fee of <%- paymentProrated %> to reflect your subscription’s higher price for the remainder of this <%- productPaymentCycleOld %>. Starting with your next bill, your charge will change from <%- paymentAmountOld %> per <%- productPaymentCycleOld %> to <%- paymentAmountNew %> per <%- productPaymentCycleNew %>."
+<% if (locals.paymentProratedInCents < 0) { %>
+subscriptionUpgrade-content-charge-credit = "You have received an account credit in the amount of <%- paymentProrated %>."
+<% } else if (locals.paymentProratedInCents > 0) { %>
+subscriptionUpgrade-content-charge-prorated = "You have been charged a one-time fee of <%- paymentProrated %> to reflect your subscription’s higher price for the remainder of this billing period (<%- productPaymentCycleOld %>)."
+<% } %>
+
+subscriptionUpgrade-content-starting = "Starting with your next bill, your charge will change from <%- paymentAmountOld %> per <%- productPaymentCycleOld %> to <%- paymentAmountNew %> per <%- productPaymentCycleNew %>."
+
 
 subscriptionUpgrade-existing = "If any of your existing subscriptions overlap with this upgrade, we’ll handle them and send you a separate email with the details. If your new plan includes products that require installation, we’ll send you a separate email with setup instructions."
 
diff --git a/packages/fxa-auth-server/test/local/payments/stripe.js b/packages/fxa-auth-server/test/local/payments/stripe.js
@@ -6333,7 +6333,7 @@ describe('#integration - StripeHelper', () => {
             paymentAmountNewCurrency: upcomingInvoice.currency,
             paymentAmountNewInCents: upcomingInvoice.total,
             paymentProratedCurrency: mockInvoice.currency,
-            paymentProratedInCents: mockInvoice.amount_due,
+            paymentProratedInCents: mockInvoice.total,
             invoiceNumber: mockInvoice.number,
             invoiceId: mockInvoice.id,
           });
diff --git a/packages/fxa-auth-server/test/local/senders/emails.ts b/packages/fxa-auth-server/test/local/senders/emails.ts
