@wix/headless-bookings 1.0.5 → 1.0.6

package/cjs/dist/__mocks__/booking/booking-client-service.js

@@ -29,16 +29,18 @@ function createMockSignalsService() {
     };
 }
 function createMockBookingService(config = {}) {
-    const { serviceSelections = [], location = null, timezone = 'UTC', formSubmission = null, } = config;
+    const { serviceSelections = [], location = null, timezone = 'UTC', formSubmission = null, selectedPaymentOption, } = config;
     const serviceSelectionsSignal = mockSignal(serviceSelections);
     const locationSignal = mockSignal(location);
     const timezoneSignal = mockSignal(timezone);
     const formSubmissionSignal = mockSignal(formSubmission);
+    const selectedPaymentOptionSignal = mockSignal(selectedPaymentOption);
     return {
         serviceSelections: serviceSelectionsSignal,
         location: locationSignal,
         timezone: timezoneSignal,
         formSubmission: formSubmissionSignal,
+        selectedPaymentOption: selectedPaymentOptionSignal,
         actions: {
             updateItem: vitest_1.vi.fn(),
             setItem: vitest_1.vi.fn(),
@@ -53,6 +55,7 @@ function createMockBookingService(config = {}) {
             setTimezone: vitest_1.vi.fn(),
             setFormSubmission: vitest_1.vi.fn(),
             clearFormSubmission: vitest_1.vi.fn(),
+            setSelectedPaymentOption: vitest_1.vi.fn(),
             clearAll: vitest_1.vi.fn(),
             book: vitest_1.vi.fn(),
         },

package/cjs/dist/react/core/booking/Booking.d.ts

@@ -3,7 +3,7 @@
  * Provides low-level access to BookingService via render props and service setup
  */
 import React from 'react';
-import { type BookingServiceConfig, type ServiceSelection, type BookingServiceActions } from '../../../services/booking/booking.js';
+import { type BookingServiceConfig, type ServiceSelection, type BookingServiceActions, type SelectedPaymentOption } from '../../../services/booking/booking.js';
 import type { FormValues } from '@wix/forms/components';
 import type { TimeSlot, Resource } from '@wix/auto_sdk_bookings_availability-time-slots';
 import { type Service, type V2Location as ServiceLocationType } from '@wix/auto_sdk_bookings_services';
@@ -40,6 +40,11 @@ export interface BookingData {
     location: ServiceLocationType | null;
     timezone: string | undefined;
     formSubmission: FormValues | null;
+    /**
+     * Consumer-selected payment option. `undefined` means the service-config
+     * heuristic applies. Set via `actions.setSelectedPaymentOption`.
+     */
+    selectedPaymentOption: SelectedPaymentOption | undefined;
     actions: BookingServiceActions;
 }
 /**

package/cjs/dist/react/core/booking/Booking.js

@@ -117,6 +117,7 @@ function Data(props) {
     const bookingLocation = bookingService.location.get();
     const timezone = bookingService.timezone.get();
     const formSubmission = bookingService.formSubmission.get();
+    const selectedPaymentOption = bookingService.selectedPaymentOption.get();
     const { actions } = bookingService;
     const location = resolveLocation(bookingLocation, serviceSelections);
     return children({
@@ -124,6 +125,7 @@ function Data(props) {
         location,
         timezone,
         formSubmission,
+        selectedPaymentOption,
         actions,
     });
 }

package/cjs/dist/services/booking/book-action/buildBookingRequest.js

@@ -58,8 +58,10 @@ function buildBookingRequest(params) {
     const slotLocation = item.timeSlot.location ?? location;
     return {
         booking: {
-            // Payment option derived from service payment settings
-            selectedPaymentOption: deriveSelectedPaymentOption(item.service),
+            // Payment option: consumer override (if set) wins over the
+            // service-config heuristic.
+            selectedPaymentOption: params.selectedPaymentOption ??
+                deriveSelectedPaymentOption(item.service),
             // Participants
             totalParticipants: item.totalParticipants || 1,
             // Booked entity slot

package/cjs/dist/services/booking/book-action/types.d.ts

@@ -4,6 +4,14 @@
 import type { ServiceSelection } from '../booking.js';
 import type { FormValues } from '@wix/forms/components';
 import type { Location as TimeSlotLocationType } from '@wix/auto_sdk_bookings_availability-time-slots';
+import type { SelectedPaymentOptionWithLiterals } from '@wix/auto_sdk_bookings_bookings';
+/**
+ * Narrowed booking-API `selectedPaymentOption` to the two values a consumer
+ * can pick in the UI. Derived from the SDK enum (`SelectedPaymentOption`) so
+ * the type stays in sync; MEMBERSHIP variants are intentionally excluded
+ * because they require pricing-plan plumbing not exposed here.
+ */
+export type SelectedPaymentOption = Extract<SelectedPaymentOptionWithLiterals, 'ONLINE' | 'OFFLINE'>;
 /**
  * Enum for book result types
  */
@@ -38,6 +46,13 @@ export interface BookActionParams {
     timezone?: string;
     /** Optional app ID override for the catalog reference. Defaults to the bookings app ID. */
     appId?: string;
+    /**
+     * Optional consumer-selected payment option. When provided, overrides the
+     * heuristic derived from `service.payment.options` in `buildBookingRequest`
+     * and matches the line item's `paymentOption` produced by the payment
+     * service. When omitted, the existing service-config heuristic applies.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
 }
 /**
  * Props passed to children of Book component

package/cjs/dist/services/booking/booking.d.ts

@@ -7,7 +7,8 @@ import { type Signal } from '@wix/services-definitions/core-services/signals';
 import type { Service, V2Location as ServiceLocationType } from '@wix/auto_sdk_bookings_services';
 import type { Resource, EventInfo, Location as TimeSlotLocationType } from '@wix/auto_sdk_bookings_availability-time-slots';
 import type { FormValues } from '@wix/forms/components';
-import type { BookResult } from './book-action/types.js';
+import type { BookResult, SelectedPaymentOption } from './book-action/types.js';
+export type { SelectedPaymentOption } from './book-action/types.js';
 /**
  * Extended Resource type with a type field for categorization
  */
@@ -80,6 +81,13 @@ export interface BookingServiceActions {
     setTimezone(timezone: string): void;
     setFormSubmission(values: FormValues | null): void;
     clearFormSubmission(): void;
+    /**
+     * Set (or clear with `null`) the consumer-selected payment option. When set
+     * to `'ONLINE'` or `'OFFLINE'`, this overrides the service-config heuristic
+     * used by `book()` and the payment preview. When set to `null`, the override
+     * is cleared and the heuristic applies again.
+     */
+    setSelectedPaymentOption(value: SelectedPaymentOption | null): void;
     clearAll(): void;
     book(): Promise<BookResult>;
 }
@@ -96,6 +104,12 @@ export interface BookingService {
     timezone: Signal<string | undefined>;
     /** Signal containing the form submission */
     formSubmission: Signal<FormValues | null>;
+    /**
+     * Signal containing the consumer-selected payment option. `undefined` means
+     * "not chosen" — `book()` and the payment preview fall back to the
+     * service-config heuristic. Set to `'ONLINE'` or `'OFFLINE'` to override.
+     */
+    selectedPaymentOption: Signal<SelectedPaymentOption | undefined>;
     /** Actions for modifying booking state */
     actions: BookingServiceActions;
 }
@@ -120,6 +134,11 @@ export interface BookingServiceConfig {
     timezone?: string;
     /** Optional initial form submission */
     formSubmission?: FormValues | null;
+    /**
+     * Optional initial consumer-selected payment option. Omit to use the
+     * service-config heuristic; set to `'ONLINE'` or `'OFFLINE'` to override.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
     /** Optional app ID override for the catalog reference. Defaults to the bookings app ID. */
     appId?: string;
 }

package/cjs/dist/services/booking/booking.js

@@ -73,6 +73,7 @@ exports.BookingService = services_definitions_1.implementService.withConfig()(ex
     const locationSignal = signalsService.signal(config.location || null);
     const timezoneSignal = signalsService.signal(config.timezone ?? getClientTimezone());
     const formSubmissionSignal = signalsService.signal(config.formSubmission || null);
+    const selectedPaymentOptionSignal = signalsService.signal(config.selectedPaymentOption);
     // ========================================================================
     // Helpers
     // ========================================================================
@@ -167,6 +168,10 @@ exports.BookingService = services_definitions_1.implementService.withConfig()(ex
         clearFormSubmission() {
             formSubmissionSignal.set(null);
         },
+        // Payment option action
+        setSelectedPaymentOption(value) {
+            selectedPaymentOptionSignal.set(value ?? undefined);
+        },
         // Clear all
         clearAll() {
             this.clearItems();
@@ -180,6 +185,7 @@ exports.BookingService = services_definitions_1.implementService.withConfig()(ex
             const formSubmission = formSubmissionSignal.get();
             const location = locationSignal.get();
             const timezone = timezoneSignal.get();
+            const selectedPaymentOption = selectedPaymentOptionSignal.get();
             // Validation happens inside executeBookAction
             return (0, bookAction_js_1.executeBookAction)({
                 serviceSelections,
@@ -187,6 +193,7 @@ exports.BookingService = services_definitions_1.implementService.withConfig()(ex
                 location,
                 timezone,
                 appId: config.appId,
+                selectedPaymentOption,
             });
         },
     };
@@ -195,6 +202,7 @@ exports.BookingService = services_definitions_1.implementService.withConfig()(ex
         location: locationSignal,
         timezone: timezoneSignal,
         formSubmission: formSubmissionSignal,
+        selectedPaymentOption: selectedPaymentOptionSignal,
         actions,
     };
 });

package/cjs/dist/services/payment/payment.d.ts

@@ -4,6 +4,7 @@
  * Supports two modes: SSR (config with pre-fetched data) and lazy loading (reactive)
  */
 import { type PaymentServiceConfig, type PaymentServiceInternalConfig, type PricingServiceSelection } from './payment.def.js';
+import type { SelectedPaymentOption } from '../booking/book-action/types.js';
 export { PaymentServiceDefinition, type PaymentServiceConfig, type PaymentDetails, type LineItemAdditionalInfo, type PricingServiceSelection, type ServicePaymentOptions, } from './payment.def.js';
 export type { PaymentServiceAPI, PaymentServiceInternalConfig, } from './payment.def.js';
 export declare const PaymentService: import("@wix/services-definitions").ServiceFactory<string & {
@@ -25,8 +26,11 @@ export type ErrorPaymentConfigResult = {
  *
  * @param params.pricingServiceSelections - Pricing service selections for calculation
  * @param params.totalParticipants - Number of participants (default: 1)
+ * @param params.selectedPaymentOption - Optional consumer-selected payment option;
+ *   overrides the service-config heuristic on each line item's `paymentOption`.
  */
 export declare function loadPaymentConfig(params: {
     pricingServiceSelections: PricingServiceSelection[];
     totalParticipants?: number;
+    selectedPaymentOption?: SelectedPaymentOption;
 }): Promise<SuccessPaymentConfigResult | ErrorPaymentConfigResult>;

package/cjs/dist/services/payment/payment.def.d.ts

@@ -5,6 +5,7 @@
 import type { Signal } from '@wix/services-definitions/core-services/signals';
 import type { CalculateTotalsResponse } from '@wix/auto_sdk_ecom_totals-calculator';
 import type { Service } from '@wix/auto_sdk_bookings_services';
+import type { SelectedPaymentOption } from '../booking/book-action/types.js';
 /**
  * Service payment options derived from service.payment.options.
  * Describes which payment methods the service supports.
@@ -74,6 +75,11 @@ export interface PaymentServiceInternalConfig extends PaymentServiceConfig {
     pricingServiceSelections?: PricingServiceSelection[];
     /** Number of participants for lazy loading (internal use) */
     totalParticipants?: number;
+    /**
+     * Optional consumer-selected payment option used for lazy loading. When
+     * set, overrides the service-config heuristic in line item `paymentOption`.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
 }
 export interface PaymentServiceAPI {
     paymentDetailsSignal: Signal<PaymentDetails | null>;

package/cjs/dist/services/payment/payment.js

@@ -57,7 +57,21 @@ function getAdditionalInfo(service, lineItemId) {
         : undefined;
     return { lineItemId, customPrice };
 }
-function getPaymentOption(service, hasDeposit) {
+/**
+ * Resolves the line item's `paymentOption`.
+ *
+ * Precedence: explicit consumer choice (`selectedPaymentOption`) wins over the
+ * service-config heuristic so the preview always agrees with what `book()`
+ * will send. When unset, the existing heuristic is preserved for backward
+ * compat.
+ */
+function getPaymentOption(service, hasDeposit, selectedPaymentOption) {
+    if (selectedPaymentOption === 'OFFLINE') {
+        return 'FULL_PAYMENT_OFFLINE';
+    }
+    if (selectedPaymentOption === 'ONLINE') {
+        return hasDeposit ? 'DEPOSIT_ONLINE' : 'FULL_PAYMENT_ONLINE';
+    }
     const options = service.payment?.options;
     if (options?.inPerson) {
         return 'FULL_PAYMENT_OFFLINE';
@@ -68,7 +82,7 @@ function getPaymentOption(service, hasDeposit) {
     }
     return 'FULL_PAYMENT_ONLINE';
 }
-function buildLineItem(service, totalParticipants, lineItemId) {
+function buildLineItem(service, totalParticipants, lineItemId, selectedPaymentOption) {
     // Get fixed price from service
     const servicePrice = service.payment?.fixed?.price?.value;
     const price = Number(servicePrice || 0) * totalParticipants;
@@ -79,7 +93,7 @@ function buildLineItem(service, totalParticipants, lineItemId) {
         ? Number(depositValue) * totalParticipants
         : undefined;
     // Get payment option from service configuration (pass hasDeposit for correct API behavior)
-    const paymentOption = getPaymentOption(service, hasDeposit);
+    const paymentOption = getPaymentOption(service, hasDeposit, selectedPaymentOption);
     return {
         _id: lineItemId,
         catalogReference: {
@@ -117,7 +131,7 @@ async function getPreviewedPrice(service, localStartDate, localEndDate, timeZone
         deposit: result.priceInfo?.deposit ?? null,
     };
 }
-async function buildLineItemWithPreview(item, totalParticipants) {
+async function buildLineItemWithPreview(item, totalParticipants, selectedPaymentOption) {
     if (item.localStartDate &&
         item.localEndDate &&
         getDurationRange(item.service)) {
@@ -142,18 +156,18 @@ async function buildLineItemWithPreview(item, totalParticipants) {
                 price: String(previewedPrice.price),
                 ...(deposit ? { depositAmount: String(deposit) } : {}),
                 quantity: 1,
-                paymentOption: getPaymentOption(item.service, hasDeposit),
+                paymentOption: getPaymentOption(item.service, hasDeposit, selectedPaymentOption),
             };
         }
     }
-    return buildLineItem(item.service, totalParticipants, item.lineItemId);
+    return buildLineItem(item.service, totalParticipants, item.lineItemId, selectedPaymentOption);
 }
-async function calculatePaymentDetails(pricingServiceSelections, totalParticipants) {
+async function calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption) {
     const data = pricingServiceSelections.map((selection) => ({
         ...selection,
         lineItemId: selection.lineItemId || (0, guid_js_1.generateLineItemId)(),
     }));
-    const lineItems = await Promise.all(data.map((item) => buildLineItemWithPreview(item, totalParticipants)));
+    const lineItems = await Promise.all(data.map((item) => buildLineItemWithPreview(item, totalParticipants, selectedPaymentOption)));
     const response = await (0, auto_sdk_ecom_totals_calculator_1.calculateTotals)({
         lineItems,
     });
@@ -184,7 +198,7 @@ exports.PaymentService = services_definitions_1.implementService.withConfig()(pa
     const errorSignal = signalsService.signal(null);
     const serviceOptionsSignal = signalsService.signal(config.serviceOptions || DEFAULT_SERVICE_OPTIONS);
     // Internal calculate function
-    const calculate = async (pricingServiceSelections, totalParticipants) => {
+    const calculate = async (pricingServiceSelections, totalParticipants, selectedPaymentOption) => {
         if (!pricingServiceSelections.length) {
             paymentDetailsSignal.set(null);
             return;
@@ -192,7 +206,7 @@ exports.PaymentService = services_definitions_1.implementService.withConfig()(pa
         isLoadingSignal.set(true);
         errorSignal.set(null);
         try {
-            const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants);
+            const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption);
             paymentDetailsSignal.set(paymentDetails);
         }
         catch (error) {
@@ -220,24 +234,30 @@ exports.PaymentService = services_definitions_1.implementService.withConfig()(pa
     // Mode 2: Lazy loading - pricingServiceSelections provided via internal config
     else if (config.pricingServiceSelections?.length) {
         serviceOptionsSignal.set(deriveServiceOptions(config.pricingServiceSelections));
-        void calculate(config.pricingServiceSelections, config.totalParticipants ?? 1);
+        void calculate(config.pricingServiceSelections, config.totalParticipants ?? 1, config.selectedPaymentOption);
     }
     // Mode 3: Reactive - observe BookingService signals (client-side only)
     else if (typeof window !== 'undefined' && bookingService) {
-        // Computed signal that changes when services or selected time slots change (not participants)
+        // Computed signal that changes when services, selected time slots, or
+        // the consumer-selected payment option change (not participants).
         const servicesKey = signalsService.computed(() => {
             const selections = bookingService?.serviceSelections.get() || [];
             const timezone = bookingService?.timezone.get();
+            const selectedPaymentOption = bookingService?.selectedPaymentOption.get();
             return (selections
                 .map((s) => `${s.service._id}:${s.timeSlot?.startDate ?? ''}:${s.timeSlot?.endDate ?? ''}`)
-                .join(',') + `:${timezone ?? ''}`);
+                .join(',') +
+                `:${timezone ?? ''}` +
+                `:${selectedPaymentOption ?? ''}`);
         });
         signalsService.effect(() => {
-            // Subscribe to servicesKey to trigger effect when service or time slot changes
+            // Subscribe to servicesKey to trigger effect when service, time
+            // slot, or selected payment option changes.
             servicesKey.get();
             // Read current selections without subscribing (peek)
             const selections = bookingService?.serviceSelections.peek() || [];
             const timezone = bookingService?.timezone.peek();
+            const selectedPaymentOption = bookingService?.selectedPaymentOption.peek();
             // For single service mode, take the first selection
             const firstSelection = selections[0];
             const numParticipants = firstSelection?.totalParticipants || 1;
@@ -251,7 +271,7 @@ exports.PaymentService = services_definitions_1.implementService.withConfig()(pa
             if (pricingServiceSelections.length) {
                 serviceOptionsSignal.set(deriveServiceOptions(pricingServiceSelections));
             }
-            void calculate(pricingServiceSelections, numParticipants);
+            void calculate(pricingServiceSelections, numParticipants, selectedPaymentOption);
         });
     }
     return {
@@ -267,10 +287,12 @@ exports.PaymentService = services_definitions_1.implementService.withConfig()(pa
  *
  * @param params.pricingServiceSelections - Pricing service selections for calculation
  * @param params.totalParticipants - Number of participants (default: 1)
+ * @param params.selectedPaymentOption - Optional consumer-selected payment option;
+ *   overrides the service-config heuristic on each line item's `paymentOption`.
  */
 async function loadPaymentConfig(params) {
     try {
-        const { pricingServiceSelections, totalParticipants = 1 } = params;
+        const { pricingServiceSelections, totalParticipants = 1, selectedPaymentOption, } = params;
         if (!pricingServiceSelections.length) {
             return {
                 type: 'success',
@@ -280,7 +302,7 @@ async function loadPaymentConfig(params) {
                 },
             };
         }
-        const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants);
+        const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption);
         return {
             type: 'success',
             config: {

package/dist/__mocks__/booking/booking-client-service.js

@@ -24,16 +24,18 @@ export function createMockSignalsService() {
     };
 }
 export function createMockBookingService(config = {}) {
-    const { serviceSelections = [], location = null, timezone = 'UTC', formSubmission = null, } = config;
+    const { serviceSelections = [], location = null, timezone = 'UTC', formSubmission = null, selectedPaymentOption, } = config;
     const serviceSelectionsSignal = mockSignal(serviceSelections);
     const locationSignal = mockSignal(location);
     const timezoneSignal = mockSignal(timezone);
     const formSubmissionSignal = mockSignal(formSubmission);
+    const selectedPaymentOptionSignal = mockSignal(selectedPaymentOption);
     return {
         serviceSelections: serviceSelectionsSignal,
         location: locationSignal,
         timezone: timezoneSignal,
         formSubmission: formSubmissionSignal,
+        selectedPaymentOption: selectedPaymentOptionSignal,
         actions: {
             updateItem: vi.fn(),
             setItem: vi.fn(),
@@ -48,6 +50,7 @@ export function createMockBookingService(config = {}) {
             setTimezone: vi.fn(),
             setFormSubmission: vi.fn(),
             clearFormSubmission: vi.fn(),
+            setSelectedPaymentOption: vi.fn(),
             clearAll: vi.fn(),
             book: vi.fn(),
         },

package/dist/react/core/booking/Booking.d.ts

@@ -3,7 +3,7 @@
  * Provides low-level access to BookingService via render props and service setup
  */
 import React from 'react';
-import { type BookingServiceConfig, type ServiceSelection, type BookingServiceActions } from '../../../services/booking/booking.js';
+import { type BookingServiceConfig, type ServiceSelection, type BookingServiceActions, type SelectedPaymentOption } from '../../../services/booking/booking.js';
 import type { FormValues } from '@wix/forms/components';
 import type { TimeSlot, Resource } from '@wix/auto_sdk_bookings_availability-time-slots';
 import { type Service, type V2Location as ServiceLocationType } from '@wix/auto_sdk_bookings_services';
@@ -40,6 +40,11 @@ export interface BookingData {
     location: ServiceLocationType | null;
     timezone: string | undefined;
     formSubmission: FormValues | null;
+    /**
+     * Consumer-selected payment option. `undefined` means the service-config
+     * heuristic applies. Set via `actions.setSelectedPaymentOption`.
+     */
+    selectedPaymentOption: SelectedPaymentOption | undefined;
     actions: BookingServiceActions;
 }
 /**

package/dist/react/core/booking/Booking.js

@@ -105,6 +105,7 @@ export function Data(props) {
     const bookingLocation = bookingService.location.get();
     const timezone = bookingService.timezone.get();
     const formSubmission = bookingService.formSubmission.get();
+    const selectedPaymentOption = bookingService.selectedPaymentOption.get();
     const { actions } = bookingService;
     const location = resolveLocation(bookingLocation, serviceSelections);
     return children({
@@ -112,6 +113,7 @@ export function Data(props) {
         location,
         timezone,
         formSubmission,
+        selectedPaymentOption,
         actions,
     });
 }

package/dist/services/booking/book-action/buildBookingRequest.js

@@ -55,8 +55,10 @@ export function buildBookingRequest(params) {
     const slotLocation = item.timeSlot.location ?? location;
     return {
         booking: {
-            // Payment option derived from service payment settings
-            selectedPaymentOption: deriveSelectedPaymentOption(item.service),
+            // Payment option: consumer override (if set) wins over the
+            // service-config heuristic.
+            selectedPaymentOption: params.selectedPaymentOption ??
+                deriveSelectedPaymentOption(item.service),
             // Participants
             totalParticipants: item.totalParticipants || 1,
             // Booked entity slot

package/dist/services/booking/book-action/types.d.ts

@@ -4,6 +4,14 @@
 import type { ServiceSelection } from '../booking.js';
 import type { FormValues } from '@wix/forms/components';
 import type { Location as TimeSlotLocationType } from '@wix/auto_sdk_bookings_availability-time-slots';
+import type { SelectedPaymentOptionWithLiterals } from '@wix/auto_sdk_bookings_bookings';
+/**
+ * Narrowed booking-API `selectedPaymentOption` to the two values a consumer
+ * can pick in the UI. Derived from the SDK enum (`SelectedPaymentOption`) so
+ * the type stays in sync; MEMBERSHIP variants are intentionally excluded
+ * because they require pricing-plan plumbing not exposed here.
+ */
+export type SelectedPaymentOption = Extract<SelectedPaymentOptionWithLiterals, 'ONLINE' | 'OFFLINE'>;
 /**
  * Enum for book result types
  */
@@ -38,6 +46,13 @@ export interface BookActionParams {
     timezone?: string;
     /** Optional app ID override for the catalog reference. Defaults to the bookings app ID. */
     appId?: string;
+    /**
+     * Optional consumer-selected payment option. When provided, overrides the
+     * heuristic derived from `service.payment.options` in `buildBookingRequest`
+     * and matches the line item's `paymentOption` produced by the payment
+     * service. When omitted, the existing service-config heuristic applies.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
 }
 /**
  * Props passed to children of Book component

package/dist/services/booking/booking.d.ts

@@ -7,7 +7,8 @@ import { type Signal } from '@wix/services-definitions/core-services/signals';
 import type { Service, V2Location as ServiceLocationType } from '@wix/auto_sdk_bookings_services';
 import type { Resource, EventInfo, Location as TimeSlotLocationType } from '@wix/auto_sdk_bookings_availability-time-slots';
 import type { FormValues } from '@wix/forms/components';
-import type { BookResult } from './book-action/types.js';
+import type { BookResult, SelectedPaymentOption } from './book-action/types.js';
+export type { SelectedPaymentOption } from './book-action/types.js';
 /**
  * Extended Resource type with a type field for categorization
  */
@@ -80,6 +81,13 @@ export interface BookingServiceActions {
     setTimezone(timezone: string): void;
     setFormSubmission(values: FormValues | null): void;
     clearFormSubmission(): void;
+    /**
+     * Set (or clear with `null`) the consumer-selected payment option. When set
+     * to `'ONLINE'` or `'OFFLINE'`, this overrides the service-config heuristic
+     * used by `book()` and the payment preview. When set to `null`, the override
+     * is cleared and the heuristic applies again.
+     */
+    setSelectedPaymentOption(value: SelectedPaymentOption | null): void;
     clearAll(): void;
     book(): Promise<BookResult>;
 }
@@ -96,6 +104,12 @@ export interface BookingService {
     timezone: Signal<string | undefined>;
     /** Signal containing the form submission */
     formSubmission: Signal<FormValues | null>;
+    /**
+     * Signal containing the consumer-selected payment option. `undefined` means
+     * "not chosen" — `book()` and the payment preview fall back to the
+     * service-config heuristic. Set to `'ONLINE'` or `'OFFLINE'` to override.
+     */
+    selectedPaymentOption: Signal<SelectedPaymentOption | undefined>;
     /** Actions for modifying booking state */
     actions: BookingServiceActions;
 }
@@ -120,6 +134,11 @@ export interface BookingServiceConfig {
     timezone?: string;
     /** Optional initial form submission */
     formSubmission?: FormValues | null;
+    /**
+     * Optional initial consumer-selected payment option. Omit to use the
+     * service-config heuristic; set to `'ONLINE'` or `'OFFLINE'` to override.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
     /** Optional app ID override for the catalog reference. Defaults to the bookings app ID. */
     appId?: string;
 }

package/dist/services/booking/booking.js

@@ -70,6 +70,7 @@ export const BookingService = implementService.withConfig()(BookingServiceDefini
     const locationSignal = signalsService.signal(config.location || null);
     const timezoneSignal = signalsService.signal(config.timezone ?? getClientTimezone());
     const formSubmissionSignal = signalsService.signal(config.formSubmission || null);
+    const selectedPaymentOptionSignal = signalsService.signal(config.selectedPaymentOption);
     // ========================================================================
     // Helpers
     // ========================================================================
@@ -164,6 +165,10 @@ export const BookingService = implementService.withConfig()(BookingServiceDefini
         clearFormSubmission() {
             formSubmissionSignal.set(null);
         },
+        // Payment option action
+        setSelectedPaymentOption(value) {
+            selectedPaymentOptionSignal.set(value ?? undefined);
+        },
         // Clear all
         clearAll() {
             this.clearItems();
@@ -177,6 +182,7 @@ export const BookingService = implementService.withConfig()(BookingServiceDefini
             const formSubmission = formSubmissionSignal.get();
             const location = locationSignal.get();
             const timezone = timezoneSignal.get();
+            const selectedPaymentOption = selectedPaymentOptionSignal.get();
             // Validation happens inside executeBookAction
             return executeBookAction({
                 serviceSelections,
@@ -184,6 +190,7 @@ export const BookingService = implementService.withConfig()(BookingServiceDefini
                 location,
                 timezone,
                 appId: config.appId,
+                selectedPaymentOption,
             });
         },
     };
@@ -192,6 +199,7 @@ export const BookingService = implementService.withConfig()(BookingServiceDefini
         location: locationSignal,
         timezone: timezoneSignal,
         formSubmission: formSubmissionSignal,
+        selectedPaymentOption: selectedPaymentOptionSignal,
         actions,
     };
 });

package/dist/services/payment/payment.d.ts

@@ -4,6 +4,7 @@
  * Supports two modes: SSR (config with pre-fetched data) and lazy loading (reactive)
  */
 import { type PaymentServiceConfig, type PaymentServiceInternalConfig, type PricingServiceSelection } from './payment.def.js';
+import type { SelectedPaymentOption } from '../booking/book-action/types.js';
 export { PaymentServiceDefinition, type PaymentServiceConfig, type PaymentDetails, type LineItemAdditionalInfo, type PricingServiceSelection, type ServicePaymentOptions, } from './payment.def.js';
 export type { PaymentServiceAPI, PaymentServiceInternalConfig, } from './payment.def.js';
 export declare const PaymentService: import("@wix/services-definitions").ServiceFactory<string & {
@@ -25,8 +26,11 @@ export type ErrorPaymentConfigResult = {
  *
  * @param params.pricingServiceSelections - Pricing service selections for calculation
  * @param params.totalParticipants - Number of participants (default: 1)
+ * @param params.selectedPaymentOption - Optional consumer-selected payment option;
+ *   overrides the service-config heuristic on each line item's `paymentOption`.
  */
 export declare function loadPaymentConfig(params: {
     pricingServiceSelections: PricingServiceSelection[];
     totalParticipants?: number;
+    selectedPaymentOption?: SelectedPaymentOption;
 }): Promise<SuccessPaymentConfigResult | ErrorPaymentConfigResult>;

package/dist/services/payment/payment.def.d.ts

@@ -5,6 +5,7 @@
 import type { Signal } from '@wix/services-definitions/core-services/signals';
 import type { CalculateTotalsResponse } from '@wix/auto_sdk_ecom_totals-calculator';
 import type { Service } from '@wix/auto_sdk_bookings_services';
+import type { SelectedPaymentOption } from '../booking/book-action/types.js';
 /**
  * Service payment options derived from service.payment.options.
  * Describes which payment methods the service supports.
@@ -74,6 +75,11 @@ export interface PaymentServiceInternalConfig extends PaymentServiceConfig {
     pricingServiceSelections?: PricingServiceSelection[];
     /** Number of participants for lazy loading (internal use) */
     totalParticipants?: number;
+    /**
+     * Optional consumer-selected payment option used for lazy loading. When
+     * set, overrides the service-config heuristic in line item `paymentOption`.
+     */
+    selectedPaymentOption?: SelectedPaymentOption;
 }
 export interface PaymentServiceAPI {
     paymentDetailsSignal: Signal<PaymentDetails | null>;

package/dist/services/payment/payment.js

@@ -52,7 +52,21 @@ function getAdditionalInfo(service, lineItemId) {
         : undefined;
     return { lineItemId, customPrice };
 }
-function getPaymentOption(service, hasDeposit) {
+/**
+ * Resolves the line item's `paymentOption`.
+ *
+ * Precedence: explicit consumer choice (`selectedPaymentOption`) wins over the
+ * service-config heuristic so the preview always agrees with what `book()`
+ * will send. When unset, the existing heuristic is preserved for backward
+ * compat.
+ */
+function getPaymentOption(service, hasDeposit, selectedPaymentOption) {
+    if (selectedPaymentOption === 'OFFLINE') {
+        return 'FULL_PAYMENT_OFFLINE';
+    }
+    if (selectedPaymentOption === 'ONLINE') {
+        return hasDeposit ? 'DEPOSIT_ONLINE' : 'FULL_PAYMENT_ONLINE';
+    }
     const options = service.payment?.options;
     if (options?.inPerson) {
         return 'FULL_PAYMENT_OFFLINE';
@@ -63,7 +77,7 @@ function getPaymentOption(service, hasDeposit) {
     }
     return 'FULL_PAYMENT_ONLINE';
 }
-function buildLineItem(service, totalParticipants, lineItemId) {
+function buildLineItem(service, totalParticipants, lineItemId, selectedPaymentOption) {
     // Get fixed price from service
     const servicePrice = service.payment?.fixed?.price?.value;
     const price = Number(servicePrice || 0) * totalParticipants;
@@ -74,7 +88,7 @@ function buildLineItem(service, totalParticipants, lineItemId) {
         ? Number(depositValue) * totalParticipants
         : undefined;
     // Get payment option from service configuration (pass hasDeposit for correct API behavior)
-    const paymentOption = getPaymentOption(service, hasDeposit);
+    const paymentOption = getPaymentOption(service, hasDeposit, selectedPaymentOption);
     return {
         _id: lineItemId,
         catalogReference: {
@@ -112,7 +126,7 @@ async function getPreviewedPrice(service, localStartDate, localEndDate, timeZone
         deposit: result.priceInfo?.deposit ?? null,
     };
 }
-async function buildLineItemWithPreview(item, totalParticipants) {
+async function buildLineItemWithPreview(item, totalParticipants, selectedPaymentOption) {
     if (item.localStartDate &&
         item.localEndDate &&
         getDurationRange(item.service)) {
@@ -137,18 +151,18 @@ async function buildLineItemWithPreview(item, totalParticipants) {
                 price: String(previewedPrice.price),
                 ...(deposit ? { depositAmount: String(deposit) } : {}),
                 quantity: 1,
-                paymentOption: getPaymentOption(item.service, hasDeposit),
+                paymentOption: getPaymentOption(item.service, hasDeposit, selectedPaymentOption),
             };
         }
     }
-    return buildLineItem(item.service, totalParticipants, item.lineItemId);
+    return buildLineItem(item.service, totalParticipants, item.lineItemId, selectedPaymentOption);
 }
-async function calculatePaymentDetails(pricingServiceSelections, totalParticipants) {
+async function calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption) {
     const data = pricingServiceSelections.map((selection) => ({
         ...selection,
         lineItemId: selection.lineItemId || generateLineItemId(),
     }));
-    const lineItems = await Promise.all(data.map((item) => buildLineItemWithPreview(item, totalParticipants)));
+    const lineItems = await Promise.all(data.map((item) => buildLineItemWithPreview(item, totalParticipants, selectedPaymentOption)));
     const response = await calculateTotals({
         lineItems,
     });
@@ -179,7 +193,7 @@ export const PaymentService = implementService.withConfig()(PaymentServiceDefini
     const errorSignal = signalsService.signal(null);
     const serviceOptionsSignal = signalsService.signal(config.serviceOptions || DEFAULT_SERVICE_OPTIONS);
     // Internal calculate function
-    const calculate = async (pricingServiceSelections, totalParticipants) => {
+    const calculate = async (pricingServiceSelections, totalParticipants, selectedPaymentOption) => {
         if (!pricingServiceSelections.length) {
             paymentDetailsSignal.set(null);
             return;
@@ -187,7 +201,7 @@ export const PaymentService = implementService.withConfig()(PaymentServiceDefini
         isLoadingSignal.set(true);
         errorSignal.set(null);
         try {
-            const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants);
+            const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption);
             paymentDetailsSignal.set(paymentDetails);
         }
         catch (error) {
@@ -215,24 +229,30 @@ export const PaymentService = implementService.withConfig()(PaymentServiceDefini
     // Mode 2: Lazy loading - pricingServiceSelections provided via internal config
     else if (config.pricingServiceSelections?.length) {
         serviceOptionsSignal.set(deriveServiceOptions(config.pricingServiceSelections));
-        void calculate(config.pricingServiceSelections, config.totalParticipants ?? 1);
+        void calculate(config.pricingServiceSelections, config.totalParticipants ?? 1, config.selectedPaymentOption);
     }
     // Mode 3: Reactive - observe BookingService signals (client-side only)
     else if (typeof window !== 'undefined' && bookingService) {
-        // Computed signal that changes when services or selected time slots change (not participants)
+        // Computed signal that changes when services, selected time slots, or
+        // the consumer-selected payment option change (not participants).
         const servicesKey = signalsService.computed(() => {
             const selections = bookingService?.serviceSelections.get() || [];
             const timezone = bookingService?.timezone.get();
+            const selectedPaymentOption = bookingService?.selectedPaymentOption.get();
             return (selections
                 .map((s) => `${s.service._id}:${s.timeSlot?.startDate ?? ''}:${s.timeSlot?.endDate ?? ''}`)
-                .join(',') + `:${timezone ?? ''}`);
+                .join(',') +
+                `:${timezone ?? ''}` +
+                `:${selectedPaymentOption ?? ''}`);
         });
         signalsService.effect(() => {
-            // Subscribe to servicesKey to trigger effect when service or time slot changes
+            // Subscribe to servicesKey to trigger effect when service, time
+            // slot, or selected payment option changes.
             servicesKey.get();
             // Read current selections without subscribing (peek)
             const selections = bookingService?.serviceSelections.peek() || [];
             const timezone = bookingService?.timezone.peek();
+            const selectedPaymentOption = bookingService?.selectedPaymentOption.peek();
             // For single service mode, take the first selection
             const firstSelection = selections[0];
             const numParticipants = firstSelection?.totalParticipants || 1;
@@ -246,7 +266,7 @@ export const PaymentService = implementService.withConfig()(PaymentServiceDefini
             if (pricingServiceSelections.length) {
                 serviceOptionsSignal.set(deriveServiceOptions(pricingServiceSelections));
             }
-            void calculate(pricingServiceSelections, numParticipants);
+            void calculate(pricingServiceSelections, numParticipants, selectedPaymentOption);
         });
     }
     return {
@@ -262,10 +282,12 @@ export const PaymentService = implementService.withConfig()(PaymentServiceDefini
  *
  * @param params.pricingServiceSelections - Pricing service selections for calculation
  * @param params.totalParticipants - Number of participants (default: 1)
+ * @param params.selectedPaymentOption - Optional consumer-selected payment option;
+ *   overrides the service-config heuristic on each line item's `paymentOption`.
  */
 export async function loadPaymentConfig(params) {
     try {
-        const { pricingServiceSelections, totalParticipants = 1 } = params;
+        const { pricingServiceSelections, totalParticipants = 1, selectedPaymentOption, } = params;
         if (!pricingServiceSelections.length) {
             return {
                 type: 'success',
@@ -275,7 +297,7 @@ export async function loadPaymentConfig(params) {
                 },
             };
         }
-        const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants);
+        const paymentDetails = await calculatePaymentDetails(pricingServiceSelections, totalParticipants, selectedPaymentOption);
         return {
             type: 'success',
             config: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-bookings",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "license": "MIT",
   "scripts": {
@@ -75,5 +75,5 @@
       "groupId": "com.wixpress.headless-components"
     }
   },
-  "falconPackageHash": "874dff357223e1f787076e35a7a2f3268eeb3e12e98104b2a779ebf8"
+  "falconPackageHash": "de3338c8d4e43446a69ef7116ba391beea6642f2f39551d997fe0ca1"
 }