@stigg/react-sdk 4.4.0-beta.2 → 4.4.0-beta.4

package/src/components/checkout/steps/payment/stripe/StripePaymentForm.tsx

@@ -1,22 +1,53 @@
 import React from 'react';
+import { StripeAddressElementChangeEvent } from '@stripe/stripe-js';
 import { Grid } from '@mui/material';
+import { BillingAddress } from '@stigg/js-client-sdk';
 import { AddressElement, PaymentElement } from '@stripe/react-stripe-js';
 import { Typography } from '../../../../common/Typography';
-import { useCheckoutModel } from '../../../hooks';
+import { useCheckoutModel, usePaymentStepModel } from '../../../hooks';
+import { CheckoutContainerProps } from '../../../CheckoutContainer';
 
-export function StripePaymentForm() {
-  const { checkoutState, checkoutLocalization, widgetState } = useCheckoutModel();
+export function StripePaymentForm({ onBillingAddressChange }: Pick<CheckoutContainerProps, 'onBillingAddressChange'>) {
+  const { checkoutState, checkoutLocalization, widgetState, setWidgetReadOnly } = useCheckoutModel();
+  const { setBillingAddress } = usePaymentStepModel();
   const { customer, configuration } = checkoutState || {};
   const { readOnly } = widgetState;
 
+  const handleAddressChange = (args: StripeAddressElementChangeEvent) => {
+    if (!args.complete) {
+      return;
+    }
+
+    const { postal_code: postalCode, ...addressFields } = args.value.address;
+    const billingAddress: BillingAddress = {
+      postalCode,
+      ...addressFields,
+    };
+
+    setWidgetReadOnly(true);
+    setBillingAddress(billingAddress);
+
+    if (onBillingAddressChange) {
+      const callExternalBillingAddressChanged = async () => {
+        await onBillingAddressChange({ billingAddress });
+        setWidgetReadOnly(false);
+      };
+
+      void callExternalBillingAddressChanged();
+    } else {
+      setWidgetReadOnly(false);
+    }
+  };
+
   return (
     <Grid flexDirection="column" container gap={3} padding="16px" sx={{ pointerEvents: readOnly ? 'none' : undefined }}>
       <Grid flexDirection="column" container gap={2}>
         <Typography variant="h6">{checkoutLocalization.newPaymentMethodBillingAddressTitle}</Typography>
         <AddressElement
+          onChange={handleAddressChange}
           options={{
             mode: 'billing',
-            fields: { phone: !!configuration?.content?.collectPhoneNumber ? 'always' : 'auto' },
+            fields: { phone: configuration?.content?.collectPhoneNumber ? 'always' : 'auto' },
             defaultValues: {
               ...(customer?.name && { name: customer.name }),
             },

package/src/components/checkout/steps/payment/stripe/stripe.utils.ts

@@ -8,15 +8,16 @@ type StripeElementsProps = {
 
 export async function handleStripeFormValidations({ elements }: Pick<StripeElementsProps, 'elements'>) {
   if (!elements) {
-    console.error('Stripe elements not initialized');
-    return { success: false };
+    const errorMessage = 'Stripe elements not initialized';
+    console.error(errorMessage);
+    return { success: false, errorMessage };
   }
 
   const { error: elementsError } = await elements.submit();
 
   if (elementsError) {
     console.log(elementsError.message);
-    return { success: false };
+    return { success: false, errorMessage: elementsError.message || '' };
   }
 
   return { success: true };

package/src/components/checkout/steps/payment/stripe/useSubmit.ts

@@ -8,9 +8,9 @@ import { CheckoutContainerProps, CheckoutResult } from '../../../CheckoutContain
 import { handleNewPaymentMethod, handleStripeFormValidations, handleStripeNextAction } from './stripe.utils';
 import { ANIMATION_DURATION } from '../../../summary/CheckoutSuccess';
 
-const delay = (ms: number) => new Promise(res => setTimeout(res, ms));
+const delay = (ms: number) => new Promise((res) => setTimeout(res, ms));
 
-export type HandleSubmitResult = { results?: ApplySubscriptionResults; errorMessage?: string } | undefined;
+export type HandleSubmitResult = { results?: ApplySubscriptionResults; success: boolean; errorMessage?: string };
 
 export type UseSubmitProps = {
   onSuccess?: () => void;
@@ -29,61 +29,69 @@ export function useSubmit({ onCheckout, onCheckoutCompleted, onSuccess }: UseSub
     e.preventDefault();
 
     if (!subscriptionState) {
-      return;
+      return { success: false, errorMessage: 'Unexpected error, please contact support.' };
     }
 
+    let checkoutParams: ApplySubscription = { ...subscriptionState };
     let checkoutResults: ApplySubscriptionResults | undefined;
     let errorMessage: string | undefined;
     let paymentMethodId: string | undefined;
 
-    setWidgetReadOnly(true);
+    const checkoutAction = async (): Promise<CheckoutResult> => {
+      if (useNewPaymentMethod) {
+        const { success, errorMessage: stripeValidationsErrorMessage } = await handleStripeFormValidations({
+          elements,
+        });
+
+        if (!success) {
+          return { success: false, errorMessage: stripeValidationsErrorMessage };
+        }
 
-    if (useNewPaymentMethod) {
-      const { success } = await handleStripeFormValidations({ elements });
-      if (!success) {
-        setWidgetReadOnly(false);
-        return;
+        const paymentMethodResults = await handleNewPaymentMethod({ elements, stripe, setupIntentClientSecret });
+        if (!paymentMethodResults.success) {
+          errorMessage = paymentMethodResults.errorMessage;
+        }
+
+        paymentMethodId = paymentMethodResults.paymentMethodId;
       }
 
-      const paymentMethodResults = await handleNewPaymentMethod({ elements, stripe, setupIntentClientSecret });
-      if (!paymentMethodResults.success) {
-        errorMessage = paymentMethodResults.errorMessage;
+      if (errorMessage) {
+        return { success: false, errorMessage };
       }
 
-      paymentMethodId = paymentMethodResults.paymentMethodId;
-    }
+      checkoutParams = { ...checkoutParams, paymentMethodId };
 
-    if (!errorMessage) {
-      const checkoutParams: ApplySubscription = { ...subscriptionState, paymentMethodId };
-
-      const checkoutAction = async (): Promise<CheckoutResult> => {
-        try {
-          const applySubscriptionResults = await stigg.applySubscription(checkoutParams);
-          const nextActionResults = await handleStripeNextAction({
-            applySubscriptionResults,
-            stripe,
-          });
-
-          checkoutResults = nextActionResults;
-          if (nextActionResults.errorMessage) {
-            errorMessage = nextActionResults.errorMessage;
-          }
-
-          return { success: !nextActionResults.errorMessage, errorMessage: nextActionResults.errorMessage };
-        } catch (e) {
-          console.error(e);
-          errorMessage = (e as any)?.message;
-          return { success: false, errorMessage };
-        }
-      };
+      try {
+        const applySubscriptionResults = await stigg.applySubscription(checkoutParams);
+        const nextActionResults = await handleStripeNextAction({
+          applySubscriptionResults,
+          stripe,
+        });
 
-      if (onCheckout) {
-        const externalCheckoutResults = await onCheckout({ checkoutParams, checkoutAction });
-        if (!externalCheckoutResults.success && externalCheckoutResults.errorMessage) {
-          errorMessage = externalCheckoutResults.errorMessage;
+        checkoutResults = nextActionResults;
+        if (nextActionResults.errorMessage) {
+          errorMessage = nextActionResults.errorMessage;
         }
-      } else {
-        await checkoutAction();
+
+        return { success: !nextActionResults.errorMessage, errorMessage: nextActionResults.errorMessage };
+      } catch (e) {
+        console.error(e);
+        errorMessage = (e as any)?.message;
+        return { success: false, errorMessage };
+      }
+    };
+
+    setWidgetReadOnly(true);
+
+    if (onCheckout) {
+      const externalCheckoutResults = await onCheckout({ checkoutParams, checkoutAction });
+      if (!externalCheckoutResults.success && externalCheckoutResults.errorMessage) {
+        errorMessage = externalCheckoutResults.errorMessage;
+      }
+    } else {
+      const checkoutActionResults = await checkoutAction();
+      if (!checkoutActionResults.success && checkoutActionResults.errorMessage) {
+        errorMessage = checkoutActionResults.errorMessage;
       }
     }
 
@@ -92,12 +100,13 @@ export function useSubmit({ onCheckout, onCheckoutCompleted, onSuccess }: UseSub
     const success = !errorMessage && !!checkoutResults?.subscription;
     if (success && onSuccess) {
       onSuccess();
+
+      await delay(ANIMATION_DURATION); // Wait for animation to finish
     }
 
-    await delay(ANIMATION_DURATION); // Wait for animation to finish
     await onCheckoutCompleted({ success, error: errorMessage });
 
-    return { results: checkoutResults, errorMessage };
+    return { results: checkoutResults, success: !errorMessage, errorMessage };
   };
 
   return { handleSubmit, isLoading: !!widgetState?.readOnly };

package/src/components/checkout/steps/plan/CheckoutChargeList.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useEffect, useState } from 'react';
 
 import styled from '@emotion/styled';
 import { Box } from '@mui/material';
@@ -10,7 +10,7 @@ import { useChargesSort } from '../../../hooks/useChargeSort';
 import { calculateUnitQuantityText } from '../../../paywall/utils/calculateUnitQuantityText';
 import { currencyPriceFormatter } from '../../../utils/currencyUtils';
 import { InputField } from '../../components';
-import { usePlanStepModel } from '../../hooks';
+import { usePlanStepModel, useProgressBarModel } from '../../hooks';
 import { TiersSelectContainer } from '../../../common/TiersSelectContainer';
 import { getPriceFeatureUnit, getTierByQuantity } from '../../../utils/priceTierUtils';
 import { getValidPriceQuantity } from '../../../utils/priceUtils';
@@ -35,23 +35,42 @@ export function PlanCharge({
   charge,
   setBillableFeature,
   billableFeature,
+  onValidationChange,
 }: {
   charge: Price;
   billableFeature?: BillableFeatureInput;
   setBillableFeature: UsePlanStepModel['setBillableFeature'];
+  onValidationChange: ({ featureId, isValid }: { featureId: string; isValid: boolean }) => void;
 }) {
+  const [isValid, setIsValid] = React.useState(true);
   const featureId = charge.feature?.featureId;
   const isBaseCharge = !featureId;
   const isPayAsYouGo = charge.pricingModel === BillingModel.UsageBased;
   const displayName = isBaseCharge ? 'Base charge' : charge.feature?.displayName;
   const hasQuantityRestrictions = !!(charge?.minUnitQuantity || charge?.maxUnitQuantity);
 
+  useEffect(() => {
+    if (!featureId) {
+      return;
+    }
+
+    onValidationChange({ featureId, isValid });
+  }, [featureId, isValid, onValidationChange]);
+
   const handleQuantityChange = (event: React.ChangeEvent<HTMLInputElement>) => {
     if (isBaseCharge || !featureId) return;
 
-    const value = event?.target?.value ? Number(event?.target?.value) : charge.minUnitQuantity || 1;
-    const quantity = getValidPriceQuantity(charge, value || 1);
+    const value = event?.target?.value ? Number(event?.target?.value) : charge.minUnitQuantity;
+    if (!value || value <= 0) {
+      setIsValid(false);
+      // Reset the input value to null
+      // @ts-ignore
+      setBillableFeature(featureId, null);
+      return;
+    }
 
+    setIsValid(true);
+    const quantity = getValidPriceQuantity(charge, value);
     setBillableFeature(featureId, quantity);
   };
 
@@ -77,20 +96,23 @@ export function PlanCharge({
         tierUnits={getPriceFeatureUnit(charge)}
         selectedTier={tier}
         handleTierChange={(tier: PriceTierFragment) => {
-          setBillableFeature(featureId!, tier!.upTo);
+          setBillableFeature(featureId!, tier.upTo);
         }}
       />
     );
   } else {
     chargeRow = (
       <InputField
-        sx={{ width: 120 }}
+        sx={{ width: 145 }}
         id={`${featureId}-input`}
         type="number"
         InputProps={
           hasQuantityRestrictions ? { inputProps: { min: charge.minUnitQuantity, max: charge.maxUnitQuantity } } : {}
         }
-        value={billableFeature?.quantity || charge.minUnitQuantity || 1}
+        error={!isValid}
+        helperText={!isValid ? 'Not a valid value' : ''}
+        FormHelperTextProps={{ sx: { margin: '4px' } }}
+        value={billableFeature?.quantity || charge.minUnitQuantity}
         onChange={handleQuantityChange}
       />
     );
@@ -118,18 +140,28 @@ export function PlanCharge({
 
 export function CheckoutChargeList({ plan, billingPeriod }: CheckoutChargeListProps) {
   const { billableFeatures, setBillableFeature } = usePlanStepModel();
-  const planCharges = useChargesSort(plan?.pricePoints?.filter(p => p.billingPeriod === billingPeriod) || []);
+  const { setIsDisabled } = useProgressBarModel();
+  const planCharges = useChargesSort(plan?.pricePoints?.filter((p) => p.billingPeriod === billingPeriod) || []);
+  const [chargesValidation, setChargesValidation] = useState({});
+
+  useEffect(() => {
+    const isDisabled = Object.values(chargesValidation).some((x) => !x);
+    setIsDisabled(isDisabled);
+  }, [chargesValidation, setIsDisabled]);
 
   return (
     <div>
-      {planCharges?.map(charge => {
-        const billableFeature = billableFeatures.find(x => x.featureId === charge.feature?.featureId);
+      {planCharges?.map((charge) => {
+        const billableFeature = billableFeatures.find((x) => x.featureId === charge.feature?.featureId);
         return (
           <PlanCharge
             key={charge.feature?.featureId || 'base-charge'}
             charge={charge}
             setBillableFeature={setBillableFeature}
             billableFeature={billableFeature}
+            onValidationChange={({ featureId, isValid }: { featureId: string; isValid: boolean }) =>
+              setChargesValidation((prev) => ({ ...prev, [featureId]: isValid }))
+            }
           />
         );
       })}

package/src/components/checkout/summary/CheckoutSuccess.tsx

@@ -24,7 +24,7 @@ const CheckoutSuccessContainer = styled(Box)`
 export function CheckoutSuccess() {
   return (
     <CheckoutSuccessContainer>
-      <Lottie width={350} options={{ loop: false, autoplay: true, animationData }} />
+      <Lottie width={350} isClickToPauseDisabled options={{ loop: false, autoplay: true, animationData }} />
     </CheckoutSuccessContainer>
   );
 }

package/src/components/checkout/summary/CheckoutSummary.tsx

@@ -84,7 +84,12 @@ function resolveCheckoutButtonText({
   return checkoutLocalization.checkoutButton.purchaseText;
 }
 
-export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutContainerProps) => {
+export const CheckoutSummary = ({
+  onCheckout,
+  onCheckoutCompleted,
+  disablePromotionCode,
+  isFreeDowngrade,
+}: CheckoutContainerProps & { isFreeDowngrade: boolean }) => {
   const [isCheckoutCompletedSuccessfully, setIsCheckoutCompletedSuccessfully] = useState(false);
   const { setErrorMessage } = usePaymentStepModel();
   const progressBar = useProgressBarModel();
@@ -96,8 +101,7 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
   );
   const [baseCharges, usageCharges] = partition(planPrices, (price) => price.pricingModel === BillingModel.FlatFee);
   const [baseCharge] = baseCharges || [];
-  const isFirstSubscription = !activeSubscription?.id;
-  const isLastStep = progressBar.isCheckoutComplete && progressBar.isLastStep;
+  const isLastStep = isFreeDowngrade || (progressBar.isCheckoutComplete && progressBar.isLastStep);
 
   const { subscriptionPreview, isFetchingSubscriptionPreview } = usePreviewSubscription();
 
@@ -119,11 +123,9 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
     if (errorMessage) {
       setErrorMessage(errorMessage);
       setIsCheckoutCompletedSuccessfully(false);
-      return;
+    } else {
+      setErrorMessage(undefined);
     }
-
-    setErrorMessage(undefined);
-    setIsCheckoutCompletedSuccessfully(true);
   };
 
   const onCheckoutClick = async (e: any): Promise<void> => {
@@ -211,7 +213,7 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
 
         <StyledDivider className="stigg-checkout-summary-divider" />
 
-        {isFirstSubscription && (
+        {!disablePromotionCode && (
           <>
             <PromotionCodeSection checkoutLocalization={checkoutLocalization} />
 
@@ -219,18 +221,18 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
           </>
         )}
 
-        <AppliedCreditsLineItem
+        <DiscountLineItem
           subscriptionPreview={subscriptionPreview}
           isFetchingSubscriptionPreview={isFetchingSubscriptionPreview}
-          checkoutLocalization={checkoutLocalization}
         />
 
-        <DiscountLineItem
+        <TaxLineItem
           subscriptionPreview={subscriptionPreview}
           isFetchingSubscriptionPreview={isFetchingSubscriptionPreview}
+          checkoutLocalization={checkoutLocalization}
         />
 
-        <TaxLineItem
+        <AppliedCreditsLineItem
           subscriptionPreview={subscriptionPreview}
           isFetchingSubscriptionPreview={isFetchingSubscriptionPreview}
           checkoutLocalization={checkoutLocalization}
@@ -256,10 +258,11 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
         />
 
         <Button
-          disableRipple={isLoading}
-          $isLoading={isLoading}
+          disableRipple={isLoading || progressBar.progressBarState.isDisabled}
+          $isLoading={isLoading || progressBar.progressBarState.isDisabled}
           $success={isCheckoutCompletedSuccessfully}
           $error={isLastStep && subscriptionPreview?.isPlanDowngrade}
+          disabled={isLoading || isFetchingSubscriptionPreview}
           className="stigg-checkout-summary-cta-button"
           sx={{ textTransform: 'none', borderRadius: '10px', marginTop: '24px' }}
           variant="contained"
@@ -269,11 +272,13 @@ export const CheckoutSummary = ({ onCheckout, onCheckoutCompleted }: CheckoutCon
           }}
           fullWidth>
           <Typography className="stigg-checkout-summary-cta-button-text" color="white" style={{ display: 'flex' }}>
-            {isCheckoutCompletedSuccessfully && <Icon icon="Check" style={{ display: 'contents' }} />}
-            {isLoading && <CircularProgress size={20} sx={{ color: 'white' }} />}
-            {!isLoading &&
-              !isCheckoutCompletedSuccessfully &&
-              resolveCheckoutButtonText({ isLastStep, subscriptionPreview, checkoutLocalization })}
+            {isCheckoutCompletedSuccessfully ? (
+              <Icon icon="Check" style={{ display: 'contents' }} />
+            ) : isLoading || isFetchingSubscriptionPreview ? (
+              <CircularProgress size={20} sx={{ color: 'white' }} />
+            ) : (
+              resolveCheckoutButtonText({ isLastStep, subscriptionPreview, checkoutLocalization })
+            )}
           </Typography>
         </Button>
       </SummaryCard>

package/src/components/checkout/summary/components/LineItems.tsx

@@ -21,24 +21,16 @@ export const LineItemRow = styled.div`
   justify-content: space-between;
 `;
 
-export const getPriceString = ({
-  amountPerMonth,
-  price,
-  quantity,
-}: {
-  amountPerMonth: number;
-  price: Price;
-  quantity: number;
-}) => {
+export const getPriceString = ({ amount, price, quantity }: { amount: number; price: Price; quantity: number }) => {
   const { billingPeriod } = price;
   let billingPeriodString = null;
 
   if (billingPeriod === BillingPeriod.Annually) {
-    amountPerMonth /= 12;
+    amount /= 12;
     billingPeriodString = '12 months';
   }
 
-  const addonPriceFormat = currencyPriceFormatter({ amount: amountPerMonth, currency: price.currency });
+  const addonPriceFormat = currencyPriceFormatter({ amount, currency: price.currency });
 
   return `${quantity > 1 ? `${quantity} x ${addonPriceFormat} each` : addonPriceFormat}${
     billingPeriodString ? ` x ${billingPeriodString}` : ''
@@ -48,12 +40,12 @@ export const getPriceString = ({
 export const BilledPriceLineItem = ({ label, quantity, price }: { label: string; quantity: number; price: Price }) => {
   const { billingPeriod } = price;
 
-  let amountPerMonth;
+  let amount;
   if (price.isTieredPrice) {
     const tier = getTierByQuantity(price.tiers!, quantity);
-    amountPerMonth = tier!.unitPrice.amount!;
+    amount = tier!.unitPrice.amount!;
   } else {
-    amountPerMonth = price.amount!;
+    amount = price.amount!;
   }
 
   return (
@@ -65,13 +57,13 @@ export const BilledPriceLineItem = ({ label, quantity, price }: { label: string;
           </Typography>
           {(quantity > 1 || billingPeriod === BillingPeriod.Annually) && (
             <Typography variant="body1" color="secondary">
-              {getPriceString({ amountPerMonth, price, quantity })}
+              {getPriceString({ amount, price, quantity })}
             </Typography>
           )}
         </Grid>
         <Grid item>
           <Typography variant="body1" color="secondary" style={{ wordBreak: 'break-word' }}>
-            {currencyPriceFormatter({ amount: quantity * amountPerMonth, currency: price.currency })}
+            {currencyPriceFormatter({ amount: quantity * amount, currency: price.currency })}
           </Typography>
         </Grid>
       </LineItemRow>

package/src/components/checkout/textOverrides.ts

@@ -1,8 +1,7 @@
-import { BillingPeriod, SubscriptionPreviewTaxDetails } from '@stigg/js-client-sdk';
+import { BillingPeriod, Plan, SubscriptionPreviewTaxDetails } from '@stigg/js-client-sdk';
 import moment from 'moment';
 import merge from 'lodash/merge';
 import { DeepPartial } from '../../types';
-import { formatBillingPeriod } from './formatting';
 
 export type CheckoutLocalization = {
   changePlan: string;
@@ -26,6 +25,7 @@ export type CheckoutLocalization = {
   };
   appliedCreditsTitle: string;
   taxTitle: (params: { taxDetails: SubscriptionPreviewTaxDetails }) => string;
+  downgradeToFreeAlertText: (params: { plan: Plan }) => string;
 };
 
 export function getResolvedCheckoutLocalize(
@@ -38,7 +38,7 @@ export function getResolvedCheckoutLocalize(
     newPaymentMethodText: 'New payment method',
     newPaymentMethodBillingAddressTitle: 'Billing address',
     newPaymentMethodCardTitle: 'Payment method',
-    baseChargeText: ({ billingPeriod }) => `${formatBillingPeriod(billingPeriod)} charge`,
+    baseChargeText: () => 'Base charge',
     totalText: 'Total due today',
     subTotalText: 'Subtotal',
     addCouponCodeText: 'Add coupon code',
@@ -55,7 +55,8 @@ export function getResolvedCheckoutLocalize(
       purchaseText: 'Purchase',
     },
     appliedCreditsTitle: 'Applied credits',
-    taxTitle: ({ taxDetails }) => `${taxDetails.displayName} (${taxDetails?.percentage}%)`,
+    taxTitle: ({ taxDetails }) => `Tax (${taxDetails?.percentage}%)`,
+    downgradeToFreeAlertText: () => `We’re sorry to see you downgrade your plan 😞`,
   };
 
   return merge(checkoutDefaultLocalization, localizeOverride);

package/src/components/checkout/types.ts

@@ -0,0 +1,9 @@
+import { SubscriptionBillingInfo } from '@stigg/js-client-sdk';
+
+export type BillingInformation = {
+  taxDetails?: TaxDetailsInput;
+};
+
+export type TaxDetailsInput = {
+  taxPercentage?: SubscriptionBillingInfo['taxPercentage'];
+};

package/src/components/paywall/PlanPrice.tsx

@@ -28,14 +28,21 @@ type PriceBillingPeriodProps = {
   billingPeriod: BillingPeriod;
   hasMonthlyPrice: boolean;
   hasAnnuallyPrice: boolean;
+  paywallLocale: PaywallLocalization;
 };
 
-function PriceBillingPeriod({ plan, billingPeriod, hasMonthlyPrice, hasAnnuallyPrice }: PriceBillingPeriodProps) {
+function PriceBillingPeriod({
+  plan,
+  billingPeriod,
+  hasMonthlyPrice,
+  hasAnnuallyPrice,
+  paywallLocale,
+}: PriceBillingPeriodProps) {
   const hasPrice = plan.pricePoints.find(pricePoint => pricePoint.billingPeriod === billingPeriod);
 
   let content = EMPTY_CHAR;
   if (hasPrice && hasMonthlyPrice && hasAnnuallyPrice) {
-    content = `, billed ${billingPeriod.toLowerCase()}`;
+    content = paywallLocale.price.billingPeriod?.(billingPeriod) || `, billed ${billingPeriod.toLowerCase()}`;
   }
 
   return (
@@ -133,6 +140,7 @@ export const PlanPrice = ({
               billingPeriod={billingPeriod}
               hasAnnuallyPrice={hasAnnuallyPrice}
               hasMonthlyPrice={hasMonthlyPrice}
+              paywallLocale={paywallLocale}
             />
           </Typography>
         )}

package/src/components/paywall/paywallTextOverrides.ts

@@ -26,6 +26,8 @@ export type PaywallLocalization = {
   };
   price: {
     startingAtCaption: string;
+    billingPeriod?: (billingPeriod: BillingPeriod) => string;
+    pricePeriod: (billingPeriod: BillingPeriod) => string;
     custom: string;
     priceNotSet: string;
     free: PlanPriceText | ((currency?: PaywallCurrency) => PlanPriceText);
@@ -56,6 +58,7 @@ export function getResolvedPaywallLocalize(localizeOverride?: DeepPartial<Paywal
     },
     price: {
       startingAtCaption: 'Starts at',
+      pricePeriod: (billingPeriod: BillingPeriod) => (billingPeriod === BillingPeriod.Monthly ? '/ month' : '/ year'),
       free: currency => ({
         price: `${currency?.symbol}0`,
       }),

package/src/components/utils/getPaidPriceText.ts

@@ -8,6 +8,7 @@ import {
 import { currencyPriceFormatter } from './currencyUtils';
 import { PlanPriceText } from './getPlanPrice';
 import { calculateTierPrice, getPriceFeatureUnit } from './priceTierUtils';
+import { PaywallLocalization } from '../paywall';
 
 type GetPaidPriceTextParams = {
   planPrices: Price[];
@@ -16,6 +17,7 @@ type GetPaidPriceTextParams = {
   locale: string;
   shouldShowMonthlyPriceAmount: boolean;
   selectedTierByFeature: Record<string, PriceTierFragment>;
+  paywallLocale: PaywallLocalization;
 };
 
 export function getPaidPriceText({
@@ -25,6 +27,7 @@ export function getPaidPriceText({
   locale,
   shouldShowMonthlyPriceAmount,
   selectedTierByFeature,
+  paywallLocale,
 }: GetPaidPriceTextParams): PlanPriceText {
   const { amount, currency } = paywallCalculatedPrice || planPrices[0];
   const priceAmount = amount || 0;
@@ -35,7 +38,10 @@ export function getPaidPriceText({
 
   let tiers;
   let tierUnits;
-  let unit = shouldShowMonthlyPriceAmount ? '/ month' : '/ year';
+  const pricePeriod = paywallLocale.price.pricePeriod(
+    shouldShowMonthlyPriceAmount ? BillingPeriod.Monthly : BillingPeriod.Annually,
+  );
+  let unit = pricePeriod;
 
   for (const price of planPrices) {
     if (price.isTieredPrice) {
@@ -56,7 +62,7 @@ export function getPaidPriceText({
     const featureUnit = price.feature?.units || '';
 
     if (price.pricingModel === BillingModel.PerUnit && !price.isTieredPrice) {
-      unit = shouldShowMonthlyPriceAmount ? `per ${featureUnit} / month` : `per ${featureUnit} / year`;
+      unit = shouldShowMonthlyPriceAmount ? `per ${featureUnit} ${pricePeriod}` : `per ${featureUnit} ${pricePeriod}`;
     } else if (price.pricingModel === BillingModel.UsageBased) {
       unit = `per ${featureUnit}`;
     }

package/src/components/utils/getPlanPrice.ts

@@ -50,7 +50,7 @@ export function getPlanPrice(
 
       return paywallLocale.price.paid
         ? paywallLocale.price.paid({ ...paidParams, plan })
-        : getPaidPriceText({ ...paidParams, locale, shouldShowMonthlyPriceAmount });
+        : getPaidPriceText({ ...paidParams, locale, shouldShowMonthlyPriceAmount, paywallLocale });
     }
     default:
       return {