@wix/auto_sdk_bookings_bookings 1.0.55 → 1.0.57

package/build/es/index.typings.d.mts

@@ -2553,15 +2553,21 @@ interface MarkBookingAsPendingRequest {
 }
 interface MarkBookingAsPendingFlowControlSettings {
     /**
-     * Whether to check for double bookings before updating the booking as pending.
+     * Whether to check for double booking conflicts when updating the status.
      *
-     * When passing `false`, a booking is only updated with status `PENDING`.
-     * Default: `false`.
+     * - `true`: Checks for availability conflicts and sets `doubleBooked` to `true`
+     * if conflicts exist.
+     * The booking is still marked as `PENDING` for the business to resolve manually.
+     * - `false`: No availability checking is performed.
+     *
+     * Default: `false`
      */
     checkAvailabilityValidation?: boolean;
     /**
-     * Whether to validate that the booking to be marked as pending has a `booking.slot.serviceId`
-     * of a pending approval service.
+     * Whether to allow marking any booking as pending, even if the service doesn't require manual approval.
+     *
+     * - `true`: Bypasses the validation that checks if the service has `service.onlineBooking.requireManualApproval` set to `true`.
+     * - `false`: Only services that require manual approval can have their bookings marked as pending.
      *
      * Default: `false`.
      */
@@ -4505,7 +4511,69 @@ interface UpdateNumberOfParticipantsOptionsParticipantsInfoOneOf {
      */
     participantsChoices?: ParticipantChoices;
 }
-/** @param bookingId - ID of the booking to mark as `PENDING`.
+/**
+ * Updates the booking status to `PENDING`.
+ *
+ *
+ * ## Service requirement
+ *
+ * By default, this method only works for services ([SDK](https://dev.wix.com/docs/sdk/backend-modules/bookings/services/introduction) | [REST](https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction)) with `service.onlineBooking.requireManualApproval` set to `true`.
+ * If you attempt to mark a booking as pending for a service that doesn't require approval, the call fails unless you use the `skipPendingApprovalServiceValidation` admin overwrite.
+ *
+ * ## Status requirements
+ *
+ * - __Original status__: Booking must have `CREATED` status.
+ * - __Target status__: Booking moves to `PENDING`.
+ *
+ * ## Checkout restrictions
+ *
+ * Only call this method if the customer paid via a custom checkout. For Wix eCommerce checkouts ([SDK](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) | [REST](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/checkout/introduction)), Wix Bookings automatically manages the bookings' statuses based on payment processing.
+ *
+ * When using custom checkouts, you can also update the booking's `paymentStatus` by specifying a new payment status.
+ *
+ * ## Business workflow
+ *
+ * After marking a booking as `PENDING`, the business must manually approve or reject it. You can call these methods:
+ * - Confirm Booking ([SDK](https://dev.wix.com/docs/sdk/backend-modules/bookings/bookings/confirm-booking) | [REST](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking)).
+ * - Decline Booking ([SDK](https://dev.wix.com/docs/sdk/backend-modules/bookings/bookings/decline-booking) | [REST](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/decline-booking)).
+ *
+ * ## Resource availability and scheduling
+ *
+ * Marking a booking as `PENDING` immediately affects resource availability:
+ *
+ * - **Calendar impact**: The booking appears on the business calendar.
+ * - **Availability**: The time slot becomes unavailable for other bookings, even while pending approval.
+ * - **Resource assignment**: Available resources ([SDK](https://dev.wix.com/docs/sdk/backend-modules/bookings/resources/introduction) | [REST](https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction)) are automatically assigned if none were explicitly selected during booking creation.
+ *
+ * ## Double bookings
+ *
+ * By default, the method doesn't check for availability conflicts. To detect and handle double bookings, use the `checkAvailabilityValidation: true` admin overwrite.
+ *
+ * ## Notify customers
+ *
+ * You can specify a `participantNotification.message` for the customer.
+ * To send the message, you must also specify `participantNotification.notifyParticipants` as `true`.
+ *
+ * ## Admin overwrites
+ *
+ * There are small but important differences when you specify special
+ * `flowControlSettings`:
+ *
+ * - `{"checkAvailabilityValidation": true}`: Checks for double booking conflicts before updating the status.
+ * When conflicts exist, the booking is still marked as `PENDING` and `doubleBooked` is set to `true` for the business to resolve manually.
+ * - `{"skipPendingApprovalServiceValidation": true}`: Allows marking any booking as pending, even if the service doesn't require manual approval.
+ *
+ * When using special `flowControlSettings`, ensure you have sufficient permissions.
+ * If you encounter failed calls due to insufficient permissions, consider the following options:
+ *
+ * - __App developers__ can use a higher
+ * [permission](https://dev.wix.com/docs/build-apps/develop-your-app/access/authorization/about-permissions), such as `MANAGE BOOKINGS - ALL PERMISSIONS`.
+ * - __Site developers__ can utilize
+ * [elevation](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/authorization/elevation).
+ *
+ * Granting additional permissions and using elevation permits method calls that would typically fail due to authorization checks.
+ * Therefore, you should use them intentionally and securely.
+ * @param bookingId - ID of the booking to mark as `PENDING`.
  * @param revision - Revision number, which increments by 1 each time the booking is updated.
  *
  * To prevent conflicting changes, the current revision must be specified when