@shipengine/elements 0.36.0 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipengine/elements",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "peerDependencies": {
     "@packlink/giger": "*",
     "react-i18next": "*",

package/src/components/field/rate-card/rate-card.d.ts

@@ -2,10 +2,12 @@ import { WithCommonProps } from "@packlink/giger";
 import { RateOption } from "../../../hooks";
 export type RateCardProps = Partial<RateOption> & WithCommonProps<{
     isAcknowledged?: boolean;
+    isPreferredRate?: boolean;
     onClick?: (rateId: string) => void;
     onClickAcknowledgement?: (isAcknowledged: boolean) => void;
     selected?: boolean;
+    selectedRateCost?: number;
     voided?: boolean;
     voidedAt?: string;
 }>;
-export declare const RateCard: ({ carrierCode, carrierFriendlyName, carrierNickname, children, className, confirmationAmount, deliveryDays, insuranceAmount, isAcknowledged, messages, onClick, onClickAcknowledgement, otherAmount, rateId, requiresAcknowledgement, selected, serviceCode, packageType, serviceType, shippingAmount, taxAmount, voided, voidedAt, }: RateCardProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const RateCard: ({ carrierCode, carrierFriendlyName, carrierNickname, children, className, confirmationAmount, deliveryDays, insuranceAmount, isAcknowledged, messages, onClick, onClickAcknowledgement, otherAmount, rateId, requiresAcknowledgement, rateAcknowledgementMessage, selected, serviceCode, packageType, serviceType, shippingAmount, taxAmount, voided, voidedAt, isPreferredRate, selectedRateCost, }: RateCardProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/field/rate-card/rate-card.styles.d.ts

@@ -7,6 +7,8 @@ export declare const getArticleSelectedStyles: (theme: Theme) => SerializedStyle
 export declare const getArticleVoidedStyles: () => SerializedStyles;
 export declare const getSectionStyles: (theme: Theme) => SerializedStyles;
 export declare const getRateImageStyles: (theme: Theme) => SerializedStyles;
+export declare const getRateSavingsSectionStyles: () => SerializedStyles;
+export declare const getRateSavingsStyles: (theme: Theme) => SerializedStyles;
 export declare const getRateInfoStyles: (theme: Theme) => SerializedStyles;
 export declare const getServiceTypeStyles: (theme: Theme) => SerializedStyles;
 export declare const getCarrierNameStyles: (theme: Theme) => SerializedStyles;

package/src/components/field/rate-select/rate-select.d.ts

@@ -1,8 +1,10 @@
 import { RateOption } from "../../../hooks";
+import { RateFormProps } from "../../templates";
 import { ControlledField } from "../create-field-controller";
 type RateSelectProps = {
     nicknameFeature?: boolean;
     options: RateOption[];
+    preferredServiceCodes?: RateFormProps["preferredServiceCodes"];
 };
 type RateSelectOptions = {
     onClick?: (rateId: string) => void;

package/src/components/fund-and-purchase/fund-and-purchase.d.ts

@@ -14,6 +14,7 @@ export type FundAndPurchaseProps = {
     disabled?: boolean;
     isFundingEnabled?: boolean;
     isFundingRequired: boolean;
+    isPreferredRate?: boolean;
     onPurchase: () => void;
     onSave: () => Promise<void>;
     purchaseAmount: number;
@@ -29,4 +30,4 @@ export type FundAndPurchaseProps = {
  *
  * @see {@link FundAndPurchaseProps | The props that are passed into the `<FundAndPurchase />` component}
  */
-export declare const FundAndPurchase: ({ balance: uspsBalance, carrierId, className, control, disabled, isFundingEnabled, isFundingRequired, onSave, purchaseAmount, onPurchase, }: FundAndPurchaseProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const FundAndPurchase: ({ balance: uspsBalance, carrierId, className, control, disabled, isFundingEnabled, isFundingRequired, isPreferredRate, onSave, purchaseAmount, onPurchase, }: FundAndPurchaseProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/templates/rate-form/rate-form.d.ts

@@ -1,5 +1,5 @@
 import { SE } from "@shipengine/alchemy";
-import { ConfigureShipmentFeatures } from "../../../elements/configure-shipment";
+import { ConfigureShipmentFeatures, PreferredRatesResponse } from "../../../elements/configure-shipment";
 export type RateFormProps = {
     carriers?: SE.Carrier[];
     disabled?: boolean;
@@ -15,7 +15,9 @@ export type RateFormProps = {
     onSelectRate?: (rateId: string) => void;
     onSubmit?: (rateId: string) => Promise<void> | void;
     outOfBandDisplayableErrors?: string[];
+    preferredRates?: PreferredRatesResponse;
+    preferredServiceCodes?: string[];
     rates?: SE.Rate[];
     shipment?: SE.SalesOrderShipment;
 };
-export declare const RateForm: ({ carriers, disabled, errors, displayableRateErrors, displayableLabelErrors, features, labelErrors, labels, labelsLoading, isLoading, onSave, onSelectRate, onSubmit, rates, shipment, outOfBandDisplayableErrors, }: RateFormProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const RateForm: ({ carriers, disabled, errors, displayableRateErrors, displayableLabelErrors, features, labelErrors, labels, labelsLoading, isLoading, onSave, onSelectRate, onSubmit, rates, preferredRates, shipment, outOfBandDisplayableErrors, preferredServiceCodes, }: RateFormProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/templates/shipment-form/shipment-form.d.ts

@@ -8,6 +8,13 @@ export type OnChangeAddressOptions = {
     shouldValidate?: boolean;
 };
 export type ShipmentFormMode = "browse_rates" | "select_service";
+export type ShipmentFormFeatures = {
+    browseRates?: boolean;
+    includeShipsuranceInsurance?: boolean;
+    includeThirdPartyInsurance?: boolean;
+    selectService?: boolean;
+    shippingPresets?: boolean;
+};
 export type ShipmentFormProps = {
     accountSettings?: SE.AccountSettings;
     addressLoading: boolean;
@@ -45,11 +52,4 @@ export type CharsetWarning = {
     message: string;
     title?: string;
 };
-export type ShipmentFormFeatures = {
-    browseRates?: boolean;
-    includeShipsuranceInsurance?: boolean;
-    includeThirdPartyInsurance?: boolean;
-    selectService?: boolean;
-    shippingPresets?: boolean;
-};
 export declare const ShipmentForm: ({ accountSettings, addressLoading, addressPreference, charsetWarning, carriers, customPackageTypes, errors, features, hydrateRef, insuranceAccount, isLoading, onApplyPreset, onChangeAddress, onChangeMode, onDirty, onSubmit, onSubmitParseShipTo, onToggleAddressPreferenceDisclosure, onUpdateCustoms, parseAddressErrors, resetParseAddress, salesOrder, shipment, shippingPresets, warehouseId, warehouses, }: ShipmentFormProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/elements/account-settings/account-settings.d.ts

@@ -323,8 +323,15 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    rateSavings: string;
+                    upsGroundSaverTermsAcknowledgement: string;
                     dhlExpressTermsAcknowledgement: string;
                 };
+                requirements: {
+                    noWarehouse: string;
+                    noCarrier: string;
+                    noWarehouseOrCarrier: string;
+                };
                 shipToAddressFormFields: string;
                 sections: {
                     customsForm: string;
@@ -616,7 +623,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 errorMessages: {
                     invalidNameOrCompany: string;
                     parsingFailure: string;
-                    noWarehouses: string;
+                    incompleteLabelPurchaseRequirements: string;
                     unableToLoad: {
                         accountSettings: string;
                         autoFundingSettings: string;

package/src/elements/configure-shipment/configure-shipment.d.ts

@@ -2,6 +2,18 @@ import { SE } from "@shipengine/alchemy";
 import { Templates } from "../../components";
 import { UseShippingPresetsOptionsProps } from "../../hooks";
 import { UseRatesFormProps, UseShipmentFormProps } from "./hooks";
+export type PreferredRateAcknowledgementMessage = {
+    link?: {
+        text: string;
+        url: string;
+    };
+    primaryMessage: string;
+    secondaryMessage?: string;
+};
+export type PreferredRatesResponse = Array<{
+    rate: SE.Rate;
+    rateAcknowledgementMessage?: PreferredRateAcknowledgementMessage;
+}>;
 export type ShipmentFormMode = "browse_rates" | "select_service";
 export type RateFormFeatures = {
     enableFunding?: boolean;
@@ -13,6 +25,9 @@ export type RateFormFeatures = {
 };
 export type ConfigureShipmentFeatures = {
     compatibleCountryCodes?: UseShipmentFormProps["compatibleCountryCodes"];
+    partnerMessages?: {
+        incompleteLabelPurchaseRequirements?: string;
+    };
     presentation?: {
         poweredByShipEngine?: boolean;
     };
@@ -22,10 +37,12 @@ export type ConfigureShipmentFeatures = {
 export type ConfigureShipmentProps = {
     errors?: Templates.ShipmentFormProps["errors"];
     features?: ConfigureShipmentFeatures;
+    getPreferredRates?: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<PreferredRatesResponse | undefined>;
     isLoading?: Templates.ShipmentFormProps["isLoading"];
     onAddressValidation?: UseShipmentFormProps["onAddressValidation"];
     onApplyPreset?: UseShipmentFormProps["onApplyPreset"];
     onBeforeLabelCreate?: UseRatesFormProps["onBeforeLabelCreate"];
+    onBeforeRateSaved?: UseRatesFormProps["onBeforeRateSaved"];
     onChangeAddress?: UseShipmentFormProps["onChangeAddress"];
     onChangeShipmentFormMode?: Templates.ShipmentFormProps["onChangeMode"];
     onLabelCreateFailure?: UseRatesFormProps["onLabelCreateFailure"];
@@ -34,10 +51,11 @@ export type ConfigureShipmentProps = {
     onRatesCalculated?: UseRatesFormProps["onRatesCalculated"];
     onShipmentUpdated: UseShipmentFormProps["onShipmentUpdated"];
     onToggleAddressPreferenceDisclosure?: Templates.ShipmentFormProps["onToggleAddressPreferenceDisclosure"];
+    preferredServiceCodes?: Templates.RateFormProps["preferredServiceCodes"];
     printLabelLayout?: UseRatesFormProps["printLabelLayout"];
     salesOrder?: SE.SalesOrder;
     shipment?: SE.SalesOrderShipment;
     shippingPresets?: UseShippingPresetsOptionsProps;
     warehouseId?: string;
 };
-export declare const ConfigureShipment: ({ features, onAddressValidation, onApplyPreset, onBeforeLabelCreate, onChangeAddress, onLabelCreateFailure, onLabelCreateSuccess, onRateSaved, onRatesCalculated, onShipmentUpdated, printLabelLayout, salesOrder, shipment, ...props }: ConfigureShipmentProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const ConfigureShipment: ({ features, getPreferredRates, onAddressValidation, onApplyPreset, onBeforeLabelCreate, onChangeAddress, onLabelCreateFailure, onLabelCreateSuccess, onRateSaved, onRatesCalculated, onShipmentUpdated, printLabelLayout, preferredServiceCodes, salesOrder, shipment, onBeforeRateSaved, ...props }: ConfigureShipmentProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/elements/configure-shipment/hooks/index.d.ts

@@ -4,3 +4,5 @@ export * from "./use-presets";
 export * from "./use-rates-form";
 export * from "./use-shipment-form";
 export * from "./use-rates-with-cache";
+export * from "./use-request-rates";
+export * from "./use-request-preferred-rates";

package/src/elements/configure-shipment/hooks/use-rates-form.d.ts

@@ -1,7 +1,18 @@
 import { SE } from "@shipengine/alchemy";
 import { UseRatesWithCacheProps } from "./use-rates-with-cache";
 export type UseRatesFormProps = {
-    onBeforeLabelCreate?: (rate: SE.Rate, shipment: SE.SalesOrderShipment) => Promise<void> | void;
+    getPreferredRates?: UseRatesWithCacheProps["getPreferredRates"];
+    onBeforeLabelCreate?: (rate: SE.Rate, shipment: SE.SalesOrderShipment) => Promise<void> | Promise<{
+        error?: SE.CodedError;
+        rate?: SE.Rate;
+    }> | void;
+    onBeforeRateSaved?: (carrierId: string, serviceCode: string) => Promise<void> | Promise<{
+        data?: {
+            carrierId: string;
+            serviceCode: string;
+        };
+        error?: SE.CodedError;
+    }> | void;
     onLabelCreateFailure?: (rate: SE.Rate, shipment: SE.SalesOrderShipment) => Promise<void> | void;
     onLabelCreateSuccess?: (label: SE.Label, shipment: SE.SalesOrderShipment) => Promise<void> | void;
     onRateSaved?: (shipment: SE.SalesOrderShipment) => Promise<void> | void;
@@ -10,7 +21,7 @@ export type UseRatesFormProps = {
     printLabelLayout?: SE.LabelLayout;
     shipment?: SE.SalesOrderShipment;
 };
-export declare const useRatesForm: ({ onBeforeLabelCreate, onLabelCreateFailure, onLabelCreateSuccess, onRateSaved, onRatesCalculated, onShipmentUpdated, printLabelLayout, shipment, }: UseRatesFormProps) => {
+export declare const useRatesForm: ({ getPreferredRates, onBeforeRateSaved, onBeforeLabelCreate, onLabelCreateFailure, onLabelCreateSuccess, onRateSaved, onRatesCalculated, onShipmentUpdated, printLabelLayout, shipment, }: UseRatesFormProps) => {
     carriers: SE.Carrier[] | undefined;
     displayableLabelErrors: string[] | undefined;
     displayableRateErrors: string[] | undefined;
@@ -21,6 +32,7 @@ export declare const useRatesForm: ({ onBeforeLabelCreate, onLabelCreateFailure,
     labelsLoading: boolean;
     onSave: ({ carrierId, serviceCode }: Pick<SE.Rate, "carrierId" | "serviceCode">) => Promise<void>;
     onSubmit: (rateId: string) => Promise<void>;
+    preferredRates: import("..").PreferredRatesResponse | undefined;
     rates: SE.Rate[] | undefined;
     requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;
     resetLabel: () => void;

package/src/elements/configure-shipment/hooks/use-rates-with-cache.d.ts

@@ -1,6 +1,7 @@
 import { SE } from "@shipengine/alchemy";
 import { UseRequestRatesProps } from "./use-request-rates";
 export type UseRatesWithCacheProps = {
+    getPreferredRates?: UseRequestRatesProps["getPreferredRates"];
     onRatesCalculated: UseRequestRatesProps["onRatesCalculated"];
     shipment?: SE.SalesOrderShipment;
 };
@@ -13,10 +14,11 @@ export type UseRatesWithCacheProps = {
  * It also intercepts the resetRates function from useRequestRates to set a flag to ignore this caching.
  * (this transparently returns the behaviors to the default useRequestRates behavior)
  */
-export declare const useRatesWithCache: ({ shipment, onRatesCalculated }: UseRatesWithCacheProps) => {
+export declare const useRatesWithCache: ({ shipment, onRatesCalculated, getPreferredRates, }: UseRatesWithCacheProps) => {
+    preferredRatesResponse: import("..").PreferredRatesResponse | undefined;
     ratesCalculating: boolean;
     ratesErrors: SE.CodedError[] | null;
-    ratesResponse: SE.RateResponse | {
+    ratesResponse: {
         created_at: string;
         errors: SE.CodedError[];
         invalidRates: SE.Rate[];
@@ -24,7 +26,7 @@ export declare const useRatesWithCache: ({ shipment, onRatesCalculated }: UseRat
         rates: SE.Rate[];
         shipment_id: string;
         status: "error" | "working" | "completed" | "partial";
-    } | undefined;
+    } | SE.RateResponse | undefined;
     requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;
     resetRates: () => void;
 };

package/src/elements/configure-shipment/hooks/use-request-preferred-rates.d.ts

@@ -0,0 +1,7 @@
+import { SE } from "@shipengine/alchemy";
+import { UseRequestRatesProps } from "./use-request-rates";
+export type RequestPreferredRatesProps = {
+    getPreferredRates?: UseRequestRatesProps["getPreferredRates"];
+};
+export type CalculatePreferredRatesData = Parameters<Required<UseRequestRatesProps>["getPreferredRates"]>;
+export declare const useRequestPreferredRates: ({ getPreferredRates }: RequestPreferredRatesProps) => import("react-query").UseMutationResult<import("..").PreferredRatesResponse | undefined, SE.CodedError[], [shipment: SE.SalesOrderShipment, isInternational: boolean], unknown>;

package/src/elements/configure-shipment/hooks/use-request-rates.d.ts

@@ -1,9 +1,12 @@
 import { SE } from "@shipengine/alchemy";
+import { ConfigureShipmentProps, PreferredRatesResponse } from "../configure-shipment";
 export type UseRequestRatesProps = {
+    getPreferredRates?: ConfigureShipmentProps["getPreferredRates"];
     onRatesCalculated?: (rates: SE.Rate[], shipment: SE.SalesOrderShipment) => Promise<void> | void;
 };
-export declare const useRequestRates: ({ onRatesCalculated }: UseRequestRatesProps) => {
-    ratesCalculating: boolean;
+export declare const useRequestRates: ({ onRatesCalculated, getPreferredRates }: UseRequestRatesProps) => {
+    isCalculating: boolean;
+    preferredRatesResponse: PreferredRatesResponse | undefined;
     ratesErrors: SE.CodedError[] | null;
     ratesResponse: SE.RateResponse | undefined;
     requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;

package/src/elements/onboarding/onboarding.d.ts

@@ -290,8 +290,15 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    rateSavings: string;
+                    upsGroundSaverTermsAcknowledgement: string;
                     dhlExpressTermsAcknowledgement: string;
                 };
+                requirements: {
+                    noWarehouse: string;
+                    noCarrier: string;
+                    noWarehouseOrCarrier: string;
+                };
                 shipToAddressFormFields: string;
                 sections: {
                     customsForm: string;
@@ -578,7 +585,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 errorMessages: {
                     invalidNameOrCompany: string;
                     parsingFailure: string;
-                    noWarehouses: string;
+                    incompleteLabelPurchaseRequirements: string;
                     unableToLoad: {
                         accountSettings: string;
                         autoFundingSettings: string;

package/src/elements/purchase-label/purchase-label.d.ts

@@ -17,6 +17,15 @@ export type PurchaseLabelCommonProps = {
      * `features` is a set of feature flags you would like to enable or disable in this component.
      */
     features?: ConfigureShipmentProps["features"];
+    /**
+     *`getPreferredRates is an async/sync optional callback function that will be invoked each time rates are caculated.
+     * This is an optional callback function that returns an array of ShipEngine rates. The rates from this response will
+     * be spliced into the normal get rates response the Elements makes internally. If a service code matches a service
+     * code on a rate returned from getPreferredRates, the rate returned from getPreferredRates will not be shown in the
+     * rate form. These preferred rates will be displayed with a set of UI enhancements that incude a dynamic cost savings
+     * flag and green checkmark when the rate is selected.
+     */
+    getPreferredRates?: ConfigureShipmentProps["getPreferredRates"];
     /**
      * `onAddressValidation` is an async/sync callback function that will be invoked on each Address
      * validation request. For example, whenever you update the `Ship To Address` or
@@ -33,6 +42,11 @@ export type PurchaseLabelCommonProps = {
      * label purchase.
      */
     onBeforeLabelCreate?: ConfigureShipmentProps["onBeforeLabelCreate"];
+    /**
+     * `onBeforeRateSave` is an async/sync callback function that will be invoked before each time a user
+     * saves a rate.
+     */
+    onBeforeRateSaved?: ConfigureShipmentProps["onBeforeRateSaved"];
     /**
      * `onChangeAddress` is an async/sync callback function that will be invoked each time a
      * `Ship To Address` or `Ship From Address` has been updated.
@@ -80,6 +94,11 @@ export type PurchaseLabelCommonProps = {
      * the formatted address that we return after validation.
      */
     onToggleAddressPreferenceDisclosure?: ConfigureShipmentProps["onToggleAddressPreferenceDisclosure"];
+    /**
+     * `preferredServiceCodes` is an array of service codes you would like to be marked as preferred. The services
+     * codes corresponding rate will get the same UI enhancements as the rates received from getPreferredRates.
+     */
+    preferredServiceCodes?: ConfigureShipmentProps["preferredServiceCodes"];
     /**
      * `printLabelLayout` is a string that represents the label layout you would like to use when
      * purchasing a label. e.g. `4x6`
@@ -130,7 +149,7 @@ export type ElementProps = PurchaseLabelByShipmentProps | PurchaseLabelSalesOrde
  *
  * @see {@link PurchaseLabel.Element | The **Element** created to render `<PurchaseLabel />`}
  */
-export declare const Component: ({ ...props }: ElementProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Component: ({ features, ...props }: ElementProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 /**
  * # Registered Purchase Label Element
  *
@@ -235,7 +254,14 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                 highVolumeForms: string;
                 multipleShippingServices: string;
                 sections: {
-                    labels: string;
+                    labels: string; /**
+                     *`getPreferredRates is an async/sync optional callback function that will be invoked each time rates are caculated.
+                     * This is an optional callback function that returns an array of ShipEngine rates. The rates from this response will
+                     * be spliced into the normal get rates response the Elements makes internally. If a service code matches a service
+                     * code on a rate returned from getPreferredRates, the rate returned from getPreferredRates will not be shown in the
+                     * rate form. These preferred rates will be displayed with a set of UI enhancements that incude a dynamic cost savings
+                     * flag and green checkmark when the rate is selected.
+                     */
                 };
                 noLabels: string;
             };
@@ -309,22 +335,12 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                     currentBalance: string;
                     insufficientBalanceCTA: string;
                 };
-                /**
-                 * # Purchase Label Component Props
-                 *
-                 * These are the shared props that will be passed into the `<PurchaseLabel.Element />`, and work
-                 * for either shipment-based or sales order-based label purchasing.
-                 *
-                 * @see {@link PurchaseLabel.Element | This prop types usage in `<PurchaseLabel.Element />`}
-                 */
                 cta: {
                     addPackageDetails: string;
                 };
                 errorMessages: {
                     customsItemsRequired: string;
-                    invalidAddress: string; /**
-                     * `features` is a set of feature flags you would like to enable or disable in this component.
-                     */
+                    invalidAddress: string;
                     noRates: string;
                     salesOrderNotLoaded: string;
                     unsupportedAddress: string;
@@ -367,6 +383,10 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                     today: string;
                 };
                 hints: {
+                    /**
+                     * `onBeforeRateSave` is an async/sync callback function that will be invoked before each time a user
+                     * saves a rate.
+                     */
                     contentDescription: string;
                 };
                 loading: {
@@ -385,8 +405,18 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    rateSavings: string; /**
+                     * `onLabelCreateSuccess` is an async/sync callback provided by the client that is invoked if the
+                     * label is successfully created/purchased.
+                     */
+                    upsGroundSaverTermsAcknowledgement: string;
                     dhlExpressTermsAcknowledgement: string;
                 };
+                requirements: {
+                    noWarehouse: string;
+                    noCarrier: string;
+                    noWarehouseOrCarrier: string;
+                };
                 shipToAddressFormFields: string;
                 sections: {
                     customsForm: string;
@@ -423,6 +453,9 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                     inlineMessage: string;
                 };
                 success: {
+                    /**
+                     * `features` is a set of feature flags you would like to enable or disable in this component.
+                     */
                     title: string;
                     subtitle: string;
                     action: string;
@@ -447,14 +480,6 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                 status: {
                     saving: string;
                     saved: string;
-                    /**
-                     * # Purchase Label Component Props
-                     *
-                     * These are the shared props that will be passed into the `<PurchaseLabel.Element />`, and work
-                     * for either shipment-based or sales order-based label purchasing.
-                     *
-                     * @see {@link PurchaseLabel.Element | This prop types usage in `<PurchaseLabel.Element />`}
-                     */
                     savingFailed: string;
                 };
                 units: {
@@ -468,9 +493,7 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                         title: string;
                         standard: string;
                         g: string;
-                        kg: string; /**
-                         * `features` is a set of feature flags you would like to enable or disable in this component.
-                         */
+                        kg: string;
                     };
                 };
             };
@@ -663,12 +686,7 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                     fields: {
                         contentsType: string;
                         countryOfOrigin: string;
-                        description: string; /**
-                         * `onToggleAddressPreferenceDisclosure` is an async/sync callback function that will be invoked
-                         * each time the user toggles the `Address Preference` disclosure. This disclosure component
-                         * allows the user to select whether they would like to use the address they entered, or
-                         * the formatted address that we return after validation.
-                         */
+                        description: string;
                         harmonizedTariffCode: string;
                         ifDeliveryFails: string;
                         quantity: string;
@@ -685,16 +703,19 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                 };
                 errorMessages: {
                     invalidNameOrCompany: string;
-                    parsingFailure: string; /**
-                     * `shippingPresets` is an object that contains configured shipment details/specs
-                     * (dimensions, shipping service, etc) that can be applied to a shipment when purchasing a label.
-                     */
-                    noWarehouses: string;
+                    parsingFailure: string;
+                    incompleteLabelPurchaseRequirements: string;
                     unableToLoad: {
                         accountSettings: string;
                         autoFundingSettings: string;
                         carrier: string;
                         carriers: string;
+                        /**
+                         * `onToggleAddressPreferenceDisclosure` is an async/sync callback function that will be invoked
+                         * each time the user toggles the `Address Preference` disclosure. This disclosure component
+                         * allows the user to select whether they would like to use the address they entered, or
+                         * the formatted address that we return after validation.
+                         */
                         label: string;
                         salesOrder: string;
                         shipment: string;
@@ -727,7 +748,10 @@ export declare const Element: ({ resources, ...props }: ElementProps & {
                     connectingCarriers: string;
                     data: string;
                     importingSalesOrder: string;
-                    label: string;
+                    label: string; /**
+                     * `warehouseId` is a string that represents a previously configured warehouse you would
+                     * like to use as the `Ship From Address` when purchasing a label.
+                     */
                     onboarding: string;
                     salesOrder: string;
                     shipment: string;

package/src/elements/view-shipment/view-shipment.d.ts

@@ -295,8 +295,15 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    rateSavings: string;
+                    upsGroundSaverTermsAcknowledgement: string;
                     dhlExpressTermsAcknowledgement: string;
                 };
+                requirements: {
+                    noWarehouse: string;
+                    noCarrier: string;
+                    noWarehouseOrCarrier: string;
+                };
                 shipToAddressFormFields: string;
                 sections: {
                     customsForm: string;
@@ -613,7 +620,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 errorMessages: {
                     invalidNameOrCompany: string;
                     parsingFailure: string;
-                    noWarehouses: string;
+                    incompleteLabelPurchaseRequirements: string;
                     unableToLoad: {
                         accountSettings: string;
                         autoFundingSettings: string;

package/src/elements/void-label/void-label.d.ts

@@ -303,8 +303,15 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    rateSavings: string;
+                    upsGroundSaverTermsAcknowledgement: string;
                     dhlExpressTermsAcknowledgement: string;
                 };
+                requirements: {
+                    noWarehouse: string;
+                    noCarrier: string;
+                    noWarehouseOrCarrier: string;
+                };
                 shipToAddressFormFields: string;
                 sections: {
                     customsForm: string;
@@ -616,7 +623,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 errorMessages: {
                     invalidNameOrCompany: string;
                     parsingFailure: string;
-                    noWarehouses: string;
+                    incompleteLabelPurchaseRequirements: string;
                     unableToLoad: {
                         accountSettings: string;
                         autoFundingSettings: string;

package/src/hooks/options/use-rate-options.d.ts

@@ -1,4 +1,5 @@
 import { SE } from "@shipengine/alchemy";
+import { PreferredRateAcknowledgementMessage, PreferredRatesResponse } from "../../elements/configure-shipment";
 /**
  * @internal
  *
@@ -7,6 +8,7 @@ import { SE } from "@shipengine/alchemy";
 export type RateOption = Omit<SE.Rate, "warningMessages"> & {
     balance?: number;
     messages: string[];
+    rateAcknowledgementMessage?: PreferredRateAcknowledgementMessage;
     requiresAcknowledgement?: boolean;
     requiresFundedAmount?: boolean;
 };
@@ -15,4 +17,4 @@ export type RateOption = Omit<SE.Rate, "warningMessages"> & {
  *
  * # Rate Options Hook
  */
-export declare const useRateOptions: (rates?: SE.Rate[], carriers?: SE.Carrier[], shipment?: SE.SalesOrderShipment, enableGlobalPostFiltering?: boolean, requireDhlTermsAcknowledgement?: boolean) => RateOption[];
+export declare const useRateOptions: (rates?: SE.Rate[], preferredRates?: PreferredRatesResponse, carriers?: SE.Carrier[], shipment?: SE.SalesOrderShipment, enableGlobalPostFiltering?: boolean, requireDhlTermsAcknowledgement?: boolean) => RateOption[];

package/src/locales/en/index.d.ts

@@ -202,8 +202,15 @@ declare const _default: {
         rates: {
             uspsMediaMailAcknowledgement: string;
             uspsFirstClassMailAcknowledgement_leof: string;
+            rateSavings: string;
+            upsGroundSaverTermsAcknowledgement: string;
             dhlExpressTermsAcknowledgement: string;
         };
+        requirements: {
+            noWarehouse: string;
+            noCarrier: string;
+            noWarehouseOrCarrier: string;
+        };
         shipToAddressFormFields: string;
         sections: {
             customsForm: string;
@@ -488,7 +495,7 @@ declare const _default: {
         errorMessages: {
             invalidNameOrCompany: string;
             parsingFailure: string;
-            noWarehouses: string;
+            incompleteLabelPurchaseRequirements: string;
             unableToLoad: {
                 accountSettings: string;
                 autoFundingSettings: string;

package/src/utilities/feature-flags.d.ts

@@ -51,6 +51,14 @@ export declare const featureFlags: {
          * Elements.
          */
         readonly compatibleCountryCodes: readonly ["AU", "CA", "FR", "DE", "GB", "IL", "IT", "NO", "ES", "SE", "US"];
+        /**
+         * @internal
+         *
+         * `partnerMessages` enables the partner consuming elements to specify override messages in specific cases.
+         */
+        readonly partnerMessages: {
+            readonly incompleteLabelPurchaseRequirements: undefined;
+        };
         /**
          *  `rateForm` all scoped feature flags for the `rate form` section of the `<PurchaseLabel />`
          *  element.
@@ -73,6 +81,9 @@ export declare const featureFlags: {
              * `nicknameRate` enables showing the `carrier nickname` when rates are fetched.
              */
             readonly nicknameRate: true;
+            /**
+             * `requireDhlTermsAcknowledgement` enables the `DHL terms acknowledgement` when rates are fetched.
+             */
             readonly requireDhlTermsAcknowledgement: false;
             /**
              * `saveRate` enables the `save rate` button in the rate form. This allows users to save a