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

- updates the subscriptionUpgrade and subscriptionSubsequentInvoice email templates to handle credit amounts

Closes: FXA-11636

Author: xlisachan

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,
     };
   }

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
         ),

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.

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>

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."
+<% } %>

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,

packages/fxa-auth-server/lib/senders/emails/templates/subscriptionSubsequentInvoice/en.ftl

@@ -6,5 +6,5 @@ subscriptionSubsequentInvoice-title = Thank you for being a subscriber!
 #  $productName (String) - The name of the subscribed product, e.g. Mozilla VPN
 subscriptionSubsequentInvoice-content-received = We received your latest payment for { $productName }.
 # Variables:
-#  $nextInvoiceDateOnly (String) - The date of the next invoice, e.g. 2016/01/20
+#  $nextInvoiceDateOnly (String) - The date of the next invoice, e.g. 5/9/2025 (US), 09/05/2025 (UK)
 subscriptionSubsequentInvoice-content-next-invoice = Next Invoice: { $nextInvoiceDateOnly }

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,

packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/en.ftl

@@ -8,13 +8,40 @@ 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
+## $productPaymentCycleOldPronoun (String) - The pronoun of the old subscription payment cycle, e.g. this
+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 { $productPaymentCycleOldPronoun ->
+    [masculine] this
+    [feminine] this
+    *[other] this
+  } { $productPaymentCycleOld ->
+    [day] day
+    [month] month
+    [6-month] 6-month
+    [year] year
+    *[other] billing period
+  }.
+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 ->
+    [day] day
+    [month] month
+    [6-month] 6-month
+    [year] year
+    *[other] billing period
+  } to { $paymentAmountNew } per { $productPaymentCycleNew ->
+    [day] day
+    [month] month
+    [6-month] 6-month
+    [year] year
+    *[other] billing period
+  }.
 
 # Variables:
 # $productName (String) - The name of the new subscribed product, e.g. Mozilla VPN

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, productPaymentCycleOldPronoun}) %>">You have been charged a one-time fee of <%- paymentProrated %> to reflect your subscription’s higher price for the remainder of <%- productPaymentCycleOldPronoun %> <%- 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">

packages/fxa-auth-server/lib/senders/emails/templates/subscriptionUpgrade/index.stories.ts

@@ -21,9 +21,32 @@ const createStory = subplatStoryWithProps(
     productNameOld: 'Product Name A',
     productPaymentCycleNew: 'year',
     productPaymentCycleOld: 'month',
+    productPaymentCycleOldPronoun: 'this',
     paymentProrated: '$60.00',
     subscriptionSupportUrl: 'http://localhost:3030/support',
   }
 );
 
-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'
+);

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 <%- productPaymentCycleOldPronoun %> <%- 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."
 

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,
           });