@carlonicora/nextjs-jsonapi 5.5.0 → 5.6.0

package/src/features/billing/stripe-subscription/components/wizards/__tests__/review-card.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { PaymentMethodInterface } from "../../../../stripe-customer/data/payment-method.interface";
+import { reviewCard } from "../review-card";
+
+const card = (id: string, brand: string, last4: string): PaymentMethodInterface => ({
+  id,
+  type: "card",
+  card: { brand, last4, expMonth: 1, expYear: 2030 },
+});
+
+describe("reviewCard", () => {
+  it("returns null when there is no card", () => {
+    expect(reviewCard([], "pm_1")).toBe(null);
+    expect(reviewCard(null, null)).toBe(null);
+    expect(reviewCard(undefined, undefined)).toBe(null);
+  });
+
+  it("returns the customer's default card", () => {
+    expect(reviewCard([card("pm_new", "visa", "4242"), card("pm_old", "mastercard", "0005")], "pm_old")).toEqual({
+      brand: "Mastercard",
+      last4: "0005",
+    });
+  });
+
+  it("falls back to the first card when no default is set or the default is gone", () => {
+    const methods = [card("pm_new", "visa", "4242"), card("pm_old", "mastercard", "0005")];
+    expect(reviewCard(methods, null)).toEqual({ brand: "Visa", last4: "4242" });
+    expect(reviewCard(methods, "pm_detached")).toEqual({ brand: "Visa", last4: "4242" });
+  });
+
+  it("returns null when the card has no last 4 digits", () => {
+    expect(reviewCard([{ id: "pm_1", type: "sepa_debit" }], "pm_1")).toBe(null);
+  });
+});

package/src/features/billing/stripe-subscription/components/wizards/review-card.ts

@@ -0,0 +1,24 @@
+import { PaymentMethodInterface } from "../../../stripe-customer/data/payment-method.interface";
+
+export type ReviewCard = { brand: string; last4: string };
+
+/**
+ * The card the review shows as the one on file: the customer's default, or the
+ * first card listed when no default is set (or the default is no longer listed).
+ * Null when no card with a brand and last 4 digits is known.
+ */
+export function reviewCard(
+  methods: PaymentMethodInterface[] | null | undefined,
+  defaultPaymentMethodId: string | null | undefined,
+): ReviewCard | null {
+  if (!methods || methods.length === 0) return null;
+
+  const method = (defaultPaymentMethodId && methods.find((m) => m.id === defaultPaymentMethodId)) || methods[0];
+  if (!method.card?.last4) return null;
+
+  const brand = method.card.brand
+    ? method.card.brand.charAt(0).toUpperCase() + method.card.brand.slice(1)
+    : method.type.charAt(0).toUpperCase() + method.type.slice(1);
+
+  return { brand, last4: method.card.last4 };
+}

package/src/features/billing/stripe-subscription/data/__tests__/stripe-subscription.discount.spec.ts

@@ -0,0 +1,67 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../../permissions/types";
+import { StripePriceModule } from "../../../stripe-price/stripe-price.module";
+import { StripeSubscription } from "../stripe-subscription";
+
+// rehydrate reads Modules.StripePrice for the price relationship, so the module must be registered.
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("StripePrice", StripePriceModule(moduleFactory));
+});
+
+const subscriptionWith = (attributes: Record<string, unknown>) =>
+  new StripeSubscription().rehydrate({
+    jsonApi: {
+      id: "sub-1",
+      type: "stripe-subscriptions",
+      attributes: {
+        stripeSubscriptionId: "sub_1",
+        status: "active",
+        currentPeriodStart: "2026-10-01T00:00:00.000Z",
+        currentPeriodEnd: "2026-11-01T00:00:00.000Z",
+        ...attributes,
+      },
+    },
+    included: [],
+  });
+
+describe("StripeSubscription discount", () => {
+  it("rehydrates a percentage discount that lasts forever", () => {
+    const subscription = subscriptionWith({ discountPercentOff: 20, discountDuration: "forever" });
+
+    expect(subscription.discount).toEqual({
+      percentOff: 20,
+      amountOff: undefined,
+      currency: undefined,
+      duration: "forever",
+      durationInMonths: undefined,
+      end: undefined,
+    });
+  });
+
+  it("rehydrates a repeating amount discount with its end as a Date", () => {
+    const subscription = subscriptionWith({
+      discountAmountOff: 200,
+      discountCurrency: "eur",
+      discountDuration: "repeating",
+      discountDurationInMonths: 3,
+      discountEnd: "2027-01-01T00:00:00.000Z",
+    });
+
+    expect(subscription.discount?.amountOff).toBe(200);
+    expect(subscription.discount?.currency).toBe("eur");
+    expect(subscription.discount?.durationInMonths).toBe(3);
+    expect(subscription.discount?.end).toEqual(new Date("2027-01-01T00:00:00.000Z"));
+  });
+
+  it("has no discount when the API sends none", () => {
+    expect(subscriptionWith({}).discount).toBeUndefined();
+  });
+
+  it("has no discount when the duration comes without an amount", () => {
+    expect(subscriptionWith({ discountDuration: "forever" }).discount).toBeUndefined();
+  });
+});

package/src/features/billing/stripe-subscription/data/stripe-subscription.interface.ts

@@ -19,6 +19,19 @@ export enum SubscriptionStatus {
 // Subscription Interfaces
 // ============================================================================
 
+/**
+ * The discount Stripe applies to the subscription (read-only, synced from Stripe).
+ * Exactly one of percentOff / amountOff is set.
+ */
+export type StripeSubscriptionDiscount = {
+  percentOff?: number;
+  amountOff?: number; // minor units, in currency
+  currency?: string;
+  duration: "forever" | "once" | "repeating";
+  durationInMonths?: number;
+  end?: Date; // when a repeating discount stops
+};
+
 export interface StripeSubscriptionInterface extends ApiDataInterface {
   get stripeSubscriptionId(): string;
   get status(): SubscriptionStatus;
@@ -29,6 +42,7 @@ export interface StripeSubscriptionInterface extends ApiDataInterface {
   get trialStart(): Date | undefined;
   get trialEnd(): Date | undefined;
   get price(): StripePriceInterface | undefined;
+  get discount(): StripeSubscriptionDiscount | undefined;
 }
 
 // ============================================================================

package/src/features/billing/stripe-subscription/data/stripe-subscription.service.ts

@@ -65,6 +65,8 @@ export class StripeSubscriptionService extends AbstractService {
       method: HttpMethod.POST,
       endpoint: endpoint.generate(),
       input: params,
+      // The wizard reads 410 / 409 / 402 / 422 itself; a global handler must not swallow them
+      suppressGlobalError: true,
     });
 
     return {
@@ -92,9 +94,44 @@ export class StripeSubscriptionService extends AbstractService {
       method: HttpMethod.POST,
       endpoint: endpoint.generate(),
       input: params,
+      // The wizard reads 410 / 409 / 402 / 422 itself; a global handler must not swallow them
+      suppressGlobalError: true,
     });
   }
 
+  /**
+   * Change the plan of an existing subscription, with the payment meta.
+   *
+   * A trial upgrade charges at once; when the card asks for 3D Secure the API
+   * answers with `meta.requiresAction` and the `clientSecret` to confirm in the
+   * browser. Without that meta the change needs nothing more.
+   */
+  static async changePlanWithMeta(params: StripeSubscriptionInput): Promise<StripeSubscriptionCreateResponse> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.StripeSubscription,
+      id: params.id,
+      childEndpoint: "change-plan",
+    });
+
+    const result = await this.callApiWithMeta<StripeSubscriptionInterface>({
+      type: Modules.StripeSubscription,
+      method: HttpMethod.POST,
+      endpoint: endpoint.generate(),
+      input: params,
+      // The wizard reads 410 / 409 / 402 / 422 itself; a global handler must not swallow them
+      suppressGlobalError: true,
+    });
+
+    return {
+      subscription: result.data,
+      meta: (result.meta as StripeSubscriptionCreateMeta) ?? {
+        clientSecret: null,
+        paymentIntentId: null,
+        requiresAction: false,
+      },
+    };
+  }
+
   /**
    * Get a proration preview for a plan change
    */
@@ -188,6 +225,8 @@ export class StripeSubscriptionService extends AbstractService {
       type: Modules.StripeSubscription,
       method: HttpMethod.POST,
       endpoint: endpoint.generate(),
+      // The wizard logs a failed sync and carries on (the webhook catches up): no global error after a paid subscription
+      suppressGlobalError: true,
     });
   }
 }

package/src/features/billing/stripe-subscription/data/stripe-subscription.ts

@@ -1,6 +1,7 @@
 import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../../core";
 import { StripePriceInterface } from "../../stripe-price";
 import {
+  StripeSubscriptionDiscount,
   StripeSubscriptionInput,
   StripeSubscriptionInterface,
   SubscriptionStatus,
@@ -16,6 +17,7 @@ export class StripeSubscription extends AbstractApiData implements StripeSubscri
   private _trialStart?: Date;
   private _trialEnd?: Date;
   private _price?: StripePriceInterface;
+  private _discount?: StripeSubscriptionDiscount;
 
   get stripeSubscriptionId(): string {
     if (!this._stripeSubscriptionId) throw new Error("stripeSubscriptionId is not defined");
@@ -57,6 +59,10 @@ export class StripeSubscription extends AbstractApiData implements StripeSubscri
     return this._price;
   }
 
+  get discount(): StripeSubscriptionDiscount | undefined {
+    return this._discount;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
 
@@ -76,6 +82,21 @@ export class StripeSubscription extends AbstractApiData implements StripeSubscri
     this._trialStart = data.jsonApi.attributes.trialStart ? new Date(data.jsonApi.attributes.trialStart) : undefined;
     this._trialEnd = data.jsonApi.attributes.trialEnd ? new Date(data.jsonApi.attributes.trialEnd) : undefined;
 
+    const attributes = data.jsonApi.attributes;
+    const percentOff = attributes.discountPercentOff ?? undefined;
+    const amountOff = attributes.discountAmountOff ?? undefined;
+    this._discount =
+      attributes.discountDuration && (percentOff !== undefined || amountOff !== undefined)
+        ? {
+            percentOff,
+            amountOff,
+            currency: attributes.discountCurrency ?? undefined,
+            duration: attributes.discountDuration,
+            durationInMonths: attributes.discountDurationInMonths ?? undefined,
+            end: attributes.discountEnd ? new Date(attributes.discountEnd) : undefined,
+          }
+        : undefined;
+
     // Hydrate price relationship
     this._price = this._readIncluded(data, "price", Modules.StripePrice) as StripePriceInterface;
 

package/src/features/billing/stripe-subscription/hooks/__tests__/wizard-payment.spec.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { clientSecretToConfirm, subscriptionIdToSync } from "../wizard-payment";
+
+describe("clientSecretToConfirm", () => {
+  it("returns the client secret when the payment waits on the browser", () => {
+    expect(clientSecretToConfirm({ requiresAction: true, clientSecret: "pi_1_secret", paymentIntentId: "pi_1" })).toBe(
+      "pi_1_secret",
+    );
+  });
+
+  it("returns null when no action is required (trial, already paid)", () => {
+    expect(clientSecretToConfirm({ requiresAction: false, clientSecret: "pi_1_secret", paymentIntentId: "pi_1" })).toBe(
+      null,
+    );
+  });
+
+  it("returns null when action is required but there is no client secret", () => {
+    expect(clientSecretToConfirm({ requiresAction: true, clientSecret: null, paymentIntentId: null })).toBe(null);
+    expect(clientSecretToConfirm({ requiresAction: true, clientSecret: "" })).toBe(null);
+  });
+
+  it("returns null when the answer carries no meta (plan change with nothing to confirm)", () => {
+    expect(clientSecretToConfirm(undefined)).toBe(null);
+    expect(clientSecretToConfirm(null)).toBe(null);
+    expect(clientSecretToConfirm({})).toBe(null);
+  });
+});
+
+describe("subscriptionIdToSync", () => {
+  it("syncs the subscription the API just created", () => {
+    expect(subscriptionIdToSync({ id: "sub_new" }, undefined)).toBe("sub_new");
+  });
+
+  it("prefers the answered subscription over the one the wizard was opened on", () => {
+    expect(subscriptionIdToSync({ id: "sub_answered" }, { id: "sub_opened" })).toBe("sub_answered");
+  });
+
+  it("falls back to the subscription the wizard was opened on (trial upgrade)", () => {
+    expect(subscriptionIdToSync(undefined, { id: "sub_trial" })).toBe("sub_trial");
+    expect(subscriptionIdToSync({}, { id: "sub_trial" })).toBe("sub_trial");
+  });
+
+  it("returns null when there is no subscription id", () => {
+    expect(subscriptionIdToSync(undefined, undefined)).toBe(null);
+    expect(subscriptionIdToSync(null, null)).toBe(null);
+    expect(subscriptionIdToSync({ id: "" }, {})).toBe(null);
+  });
+});

package/src/features/billing/stripe-subscription/hooks/__tests__/wizard-promotion.spec.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+import { PromotionCodeValidationResult } from "../../../stripe-promotion-code/data/stripe-promotion-code.interface";
+import {
+  isDiscountSoldOut,
+  isDiscountUnavailable,
+  promotionCodeToSend,
+  shouldLookUpAutomatic,
+} from "../wizard-promotion";
+
+const typed = { valid: true, promotionCodeId: "promo_typed", code: "SPRING" } as PromotionCodeValidationResult;
+const automatic = {
+  valid: true,
+  promotionCodeId: "promo_auto",
+  code: "FOUNDING",
+  automatic: true,
+} as PromotionCodeValidationResult;
+
+/**
+ * The error `AbstractService.callApi` throws for a non-ok response: `status` is the
+ * HTTP status and `body` the JSON:API error document the API's HttpExceptionFilter sends.
+ */
+function apiError(status: number, code?: string): any {
+  const error = new Error(`${status}:boom`) as any;
+  error.status = status;
+  error.digest = `HTTP_${status}`;
+  error.body = {
+    message: "boom",
+    errors: [
+      {
+        status: String(status),
+        ...(code ? { code } : {}),
+        title: "Error",
+        detail: "boom",
+        source: { pointer: "/stripe-subscriptions" },
+        meta: { timestamp: "2026-10-24T00:00:00.000Z", ...(code ? { context: { code } } : {}) },
+      },
+    ],
+  };
+  return error;
+}
+
+describe("promotionCodeToSend", () => {
+  it("sends nothing when there is no code", () => {
+    expect(promotionCodeToSend(null)).toBeUndefined();
+  });
+
+  it("sends the promotion code id of an automatic code", () => {
+    expect(promotionCodeToSend(automatic)).toBe("promo_auto");
+  });
+
+  it("sends the promotion code id of a typed code", () => {
+    expect(promotionCodeToSend(typed)).toBe("promo_typed");
+  });
+});
+
+describe("shouldLookUpAutomatic", () => {
+  it("looks up when there is no code", () => {
+    expect(shouldLookUpAutomatic(null)).toBe(true);
+  });
+
+  it("looks up again when the current code is automatic", () => {
+    expect(shouldLookUpAutomatic(automatic)).toBe(true);
+  });
+
+  it("does not look up when the GM typed a code", () => {
+    expect(shouldLookUpAutomatic(typed)).toBe(false);
+  });
+});
+
+describe("isDiscountSoldOut", () => {
+  it("is true for a 410 carrying the discount_sold_out code", () => {
+    expect(isDiscountSoldOut(apiError(410, "discount_sold_out"))).toBe(true);
+  });
+
+  it("reads the code from meta.context when the top-level code is missing", () => {
+    const error = apiError(410, "discount_sold_out");
+    delete error.body.errors[0].code;
+    expect(isDiscountSoldOut(error)).toBe(true);
+  });
+
+  it("accepts the status on error.response", () => {
+    const error = apiError(410, "discount_sold_out");
+    delete error.status;
+    error.response = { status: 410 };
+    expect(isDiscountSoldOut(error)).toBe(true);
+  });
+
+  it("is false for a 410 without the code", () => {
+    expect(isDiscountSoldOut(apiError(410))).toBe(false);
+    expect(isDiscountSoldOut({ status: 410 })).toBe(false);
+  });
+
+  it("is false for the code on another status", () => {
+    expect(isDiscountSoldOut(apiError(422, "discount_sold_out"))).toBe(false);
+  });
+
+  it("is false for other errors", () => {
+    expect(isDiscountSoldOut(apiError(409))).toBe(false);
+    expect(isDiscountSoldOut(apiError(402))).toBe(false);
+    expect(isDiscountSoldOut(apiError(422, "discount_unavailable"))).toBe(false);
+    expect(isDiscountSoldOut(new Error("boom"))).toBe(false);
+    expect(isDiscountSoldOut(undefined)).toBe(false);
+  });
+});
+
+describe("isDiscountUnavailable", () => {
+  it("is true for a 422 carrying the discount_unavailable code", () => {
+    expect(isDiscountUnavailable(apiError(422, "discount_unavailable"))).toBe(true);
+  });
+
+  it("reads the code from meta.context when the top-level code is missing", () => {
+    const error = apiError(422, "discount_unavailable");
+    delete error.body.errors[0].code;
+    expect(isDiscountUnavailable(error)).toBe(true);
+  });
+
+  it("is false for a 422 without the code (a typed code's own rejection)", () => {
+    expect(isDiscountUnavailable(apiError(422))).toBe(false);
+    expect(isDiscountUnavailable({ status: 422 })).toBe(false);
+  });
+
+  it("is false for the code on another status", () => {
+    expect(isDiscountUnavailable(apiError(410, "discount_unavailable"))).toBe(false);
+  });
+
+  it("is false for other errors", () => {
+    expect(isDiscountUnavailable(apiError(410, "discount_sold_out"))).toBe(false);
+    expect(isDiscountUnavailable(apiError(409))).toBe(false);
+    expect(isDiscountUnavailable(new Error("boom"))).toBe(false);
+    expect(isDiscountUnavailable(undefined)).toBe(false);
+  });
+});

package/src/features/billing/stripe-subscription/hooks/useSubscriptionWizard.ts

@@ -7,9 +7,24 @@ import { useI18nLocale } from "../../../../i18n";
 import { StripeCustomerService } from "../../stripe-customer/data/stripe-customer.service";
 import { ProrationPreviewInterface } from "../../stripe-invoice/data/stripe-invoice.interface";
 import { StripePriceInterface } from "../../stripe-price/data/stripe-price.interface";
+import { StripeCouponCodeService } from "../../stripe-coupon/data/stripe-coupon-code.service";
+import { toPromotionCodeResult } from "../../stripe-coupon/utils/to-promotion-code-result";
 import { PromotionCodeValidationResult, StripePromotionCodeService } from "../../stripe-promotion-code";
 import { BillingInterval } from "../components/widgets/IntervalToggle";
-import { StripeSubscriptionInterface, StripeSubscriptionService, SubscriptionStatus } from "../data";
+import {
+  StripeSubscriptionCreateResponse,
+  StripeSubscriptionInterface,
+  StripeSubscriptionService,
+  SubscriptionStatus,
+} from "../data";
+import {
+  isDiscountSoldOut,
+  isDiscountUnavailable,
+  promotionCodeToSend,
+  shouldLookUpAutomatic,
+} from "./wizard-promotion";
+import { useConfirmSubscriptionPayment } from "./useConfirmSubscriptionPayment";
+import { clientSecretToConfirm, subscriptionIdToSync } from "./wizard-payment";
 
 export type WizardStep = "plan-selection" | "review" | "payment-method";
 
@@ -97,6 +112,7 @@ export type UseSubscriptionWizardOptions = {
 export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseSubscriptionWizardOptions) {
   const t = useTranslations();
   const locale = useI18nLocale();
+  const { confirmPayment } = useConfirmSubscriptionPayment();
   const [state, dispatch] = useReducer(wizardReducer, {
     ...initialState,
     selectedPrice: subscription?.price || null,
@@ -130,6 +146,42 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
     dispatch({ type: "SET_STEP", step });
   }, []);
 
+  /**
+   * Puts the automatic code for this price (or none) in the wizard state, so the
+   * review shows what the server would really charge. Returns false when the
+   * lookup itself failed: the caller must then not show a price as the truth.
+   */
+  const lookUpAutomaticCode = useCallback(async (priceId: string): Promise<boolean> => {
+    try {
+      const automaticCode = await StripeCouponCodeService.findAutomatic({ priceId });
+      dispatch({
+        type: "SET_PROMOTION_CODE",
+        code: automaticCode ? toPromotionCodeResult(automaticCode) : null,
+      });
+      return true;
+    } catch (error) {
+      console.error("[useSubscriptionWizard] Failed to look up the automatic promotion code:", error);
+      dispatch({ type: "SET_PROMOTION_CODE", code: null });
+      return false;
+    }
+  }, []);
+
+  /**
+   * Re-reads the automatic code after the review's code changed. When the lookup
+   * fails, the review price cannot be trusted: back to plan selection.
+   */
+  const refreshAutomaticCodeOrLeaveReview = useCallback(
+    async (priceId: string): Promise<void> => {
+      const found = await lookUpAutomaticCode(priceId);
+      if (!found) {
+        // SET_STEP clears the error, so the error goes second
+        dispatch({ type: "SET_STEP", step: "plan-selection" });
+        dispatch({ type: "SET_ERROR", error: t("billing.ui.wizard.errors.prepare_review") });
+      }
+    },
+    [lookUpAutomaticCode, t],
+  );
+
   const goToReview = useCallback(async () => {
     if (!state.selectedPrice) return;
 
@@ -156,6 +208,16 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
         }
       }
 
+      // Fill the automatic code for this price, unless the GM typed one
+      // A failed lookup never shows full price as if nothing applied: stay off the review
+      if (shouldLookUpAutomatic(state.promotionCode)) {
+        const found = await lookUpAutomaticCode(state.selectedPrice.id);
+        if (!found) {
+          dispatch({ type: "SET_ERROR", error: t("billing.ui.wizard.errors.prepare_review") });
+          return;
+        }
+      }
+
       // If editing subscription, get proration preview
       if (subscription && state.selectedPrice.id !== subscription.price?.id) {
         const preview = await StripeSubscriptionService.getProrationPreview({
@@ -172,7 +234,15 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
     } finally {
       dispatch({ type: "SET_PROCESSING", isProcessing: false });
     }
-  }, [state.selectedPrice, state.hasPaymentMethod, subscription, checkPaymentMethod, t]);
+  }, [
+    state.selectedPrice,
+    state.hasPaymentMethod,
+    state.promotionCode,
+    subscription,
+    checkPaymentMethod,
+    lookUpAutomaticCode,
+    t,
+  ]);
 
   const confirmSubscription = useCallback(async () => {
     if (!state.selectedPrice) return;
@@ -181,27 +251,71 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
     dispatch({ type: "SET_ERROR", error: null });
 
     try {
+      let result: StripeSubscriptionCreateResponse;
       if (subscription) {
         // Change existing subscription
         const changePlanParams = {
           id: subscription.id,
           newPriceId: state.selectedPrice.id,
-          promotionCode: state.promotionCode?.promotionCodeId,
+          promotionCode: promotionCodeToSend(state.promotionCode),
         };
-        await StripeSubscriptionService.changePlan(changePlanParams);
+        result = await StripeSubscriptionService.changePlanWithMeta(changePlanParams);
       } else {
         // Create new subscription
         const createParams = {
           id: v4(),
           priceId: state.selectedPrice.id,
-          promotionCode: state.promotionCode?.promotionCodeId,
+          promotionCode: promotionCodeToSend(state.promotionCode),
         };
-        await StripeSubscriptionService.createSubscription(createParams);
+        result = await StripeSubscriptionService.createSubscription(createParams);
+      }
+
+      // The first payment waits on the browser (confirmation, 3D Secure): until it
+      // is confirmed nothing is paid, so the wizard stays open on a failure
+      const clientSecret = clientSecretToConfirm(result.meta);
+      if (clientSecret) {
+        const confirmation = await confirmPayment(clientSecret);
+        if (!confirmation.success) {
+          console.error("[useSubscriptionWizard] Payment not confirmed:", confirmation.error);
+          dispatch({
+            type: "SET_ERROR",
+            error: t("billing.ui.wizard.errors.payment_not_confirmed", { reason: confirmation.error ?? "" }),
+          });
+          return;
+        }
+
+        // Our copy is still incomplete until the webhooks land: store what Stripe has now,
+        // so the billing page shows the plan at once. A failed sync never blocks success.
+        const subscriptionId = subscriptionIdToSync(result.subscription, subscription);
+        if (subscriptionId) {
+          try {
+            await StripeSubscriptionService.syncSubscription({ subscriptionId });
+          } catch (syncError) {
+            console.error("[useSubscriptionWizard] Subscription sync after payment failed:", syncError);
+          }
+        }
       }
 
       onSuccessRef.current();
       onCloseRef.current();
     } catch (error: any) {
+      // 410 discount_sold_out (the automatic discount's last place has just gone) or
+      // 422 discount_unavailable (the automatic code shown is no longer valid): nothing
+      // was charged. Never retry: drop the code and re-read the automatic one, so the
+      // review shows the price that would really be charged now.
+      const soldOut = isDiscountSoldOut(error);
+      if (soldOut || isDiscountUnavailable(error)) {
+        dispatch({
+          type: "SET_ERROR",
+          error: soldOut
+            ? t("billing.ui.wizard.errors.discount_sold_out")
+            : t("billing.ui.wizard.errors.discount_unavailable"),
+        });
+        dispatch({ type: "SET_PROMOTION_CODE", code: null });
+        await refreshAutomaticCodeOrLeaveReview(state.selectedPrice.id);
+        return;
+      }
+
       // Handle 409 Conflict - duplicate recurring subscription
       if (error?.status === 409 || error?.response?.status === 409) {
         dispatch({
@@ -222,13 +336,14 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
     } finally {
       dispatch({ type: "SET_PROCESSING", isProcessing: false });
     }
-  }, [state.selectedPrice, state.promotionCode, subscription, t]);
+  }, [state.selectedPrice, state.promotionCode, subscription, refreshAutomaticCodeOrLeaveReview, confirmPayment, t]);
 
   const handlePaymentMethodSuccess = useCallback(async () => {
     dispatch({ type: "SET_HAS_PAYMENT_METHOD", hasMethod: true });
-    // Go back to review to confirm subscription
-    dispatch({ type: "SET_STEP", step: "review" });
-  }, []);
+    // Prepare the review exactly as "Next: Review" does: the trial path sent the GM
+    // here before the automatic-code lookup and the proration preview had run
+    await goToReview();
+  }, [goToReview]);
 
   const reset = useCallback(() => {
     dispatch({ type: "RESET" });
@@ -267,11 +382,22 @@ export function useSubscriptionWizard({ subscription, onSuccess, onClose }: UseS
     [state.selectedPrice?.id, t, locale],
   );
 
-  const clearPromoCode = useCallback(() => {
+  const clearPromoCode = useCallback(async () => {
     dispatch({ type: "SET_PROMOTION_CODE", code: null });
     dispatch({ type: "SET_PROMO_CODE_ERROR", error: null });
     dispatch({ type: "SET_ERROR", error: null });
-  }, []);
+
+    if (!state.selectedPrice) return;
+
+    // Removing a typed code: the server attaches the automatic code again, so the
+    // review must show it again
+    dispatch({ type: "SET_PROCESSING", isProcessing: true });
+    try {
+      await refreshAutomaticCodeOrLeaveReview(state.selectedPrice.id);
+    } finally {
+      dispatch({ type: "SET_PROCESSING", isProcessing: false });
+    }
+  }, [state.selectedPrice, refreshAutomaticCodeOrLeaveReview]);
 
   const actions = useMemo(
     () => ({