Modes

This page explains what widget modes are and how they work for the Regular Quote Widget

Widget modes are managed in hte Widget mode section in the edit widget modal. The general mode can be selected via the Widget mode dropdown.

Quote mode

In Quote mode, the widget leads the user to request a quote for their configured models. This enables the organization to verify and confirm the details of all models before moving onto creating an order. The quote mode offers two additional toggles for:

• Collect Shipping Details: When enabled, the widget will collect shipping details from the user before submitting a quote request. This is useful for organizations that need to know where the models will be shipped before providing a quote.
• Manual Quoting Mode: When enabled, the widget will not provide estimates for any uploaded models. Instead, the user will be prompted to request a quote for their configured models. This is useful for organizations that want to provide quotes manually rather than automatically.

Order mode

In Order mode, the widget leads the user to creating and paying for an order with the automatically generated prices for each model. This enables the organization to provide a seamless experience for users who want to quickly purchase their configured models without needing to wait for a quote. This is also useful when having dedicated quote widgets for regular clients. In order for this mode to be enabled you must configure payment providers and shipping rates.

Integration mode

In Integration mode, the widget allows users to add estimated models from the Regular Quote Widget to a cart managed by the host page. This mode is intended for websites that already have their own cart or checkout flow and need the widget to hand off a quote reference after the widget has created the add-to-cart record.

The integration add-to-cart flow is only used when all uploaded models can be estimated automatically. If any model requires manual estimation, any uploaded item is a custom file, the widget cannot build the estimation payload, or the backend add-to-cart request fails, the user is routed to the quote flow instead.

When the user clicks Add to cart, the widget:

1. Builds the current model estimations.
2. Sends those estimations to the widget backend.
3. Receives a quoteId and quoteNumber from the backend.
4. Starts listening for a host-page response.
5. Sends an add-to-cart message to the host page with window.postMessage.

The host page receives only the quote reference, not the full estimations array:

{
  source: 'regular-widget',
  type: 'add-to-cart',
  widgetKey: string,
  payload: {
    quoteId: string,
    quoteNumber: string
  }
}

The host page should use the payload to add the quote to its own cart. It can fetch more details about the quote via the api (api docs) using the quote id or the quote number. After processing the add to cart event, post a result message back to the widget. The response must include the same widgetKey that was sent by the widget.

For a successful add-to-cart operation, respond with:

{
  source: 'host-page',
  widgetKey: '<same widget key>',
  type: 'add-to-cart-success'
}

For a failed add-to-cart operation, respond with:

{
  source: 'host-page',
  widgetKey: '<same widget key>',
  type: 'add-to-cart-error'
}

The widget ignores messages with a different source, type, or widgetKey. If the host page sends add-to-cart-success, the widget shows the cart success screen and resets the quote flow. If the host page sends add-to-cart-error, the widget falls back to the quote flow and asks the user to request a quote instead.

The widget waits up to 15 seconds for a valid host-page response. If no valid response is received in that time, the timeout is handled the same way as a host error: the user is sent to the quote flow and can continue by submitting a quote request.

The widget starts listening for the host-page response before it posts the add-to-cart message, so immediate host responses are supported. In the normal embed scenario, the message is posted to window.location.origin, which is the host page origin because the widget script runs in the host page context.