Update Live Rates Action

update_live_rates_action is a CartThrob action endpoint used by live-rates shipping workflows.

It is not intended to be used as a normal output tag in templates. In current usage, get_live_rates_form generates forms that post to this action.

See also:

• get_live_rates_form
• get_shipping_options
• selected_shipping_option
• save_shipping_option
• shipping tag index

Request Inputs

• shipping_plugin
• activate_plugin
• shipping_option
• save_shipping
• language
• REQ

Live-rates plugins may require additional customer/shipping fields (for example zip, country, state, address fields). Those requirements come from the active shipping plugin.

shipping_plugin

Optional shipping plugin to use for the request.

When posted, the action sets that plugin for rate lookup.

activate_plugin

If truthy with shipping_plugin, saves that plugin as active cart shipping plugin config.

shipping_option

Requested option/rate key. If omitted, action requests rates for ALL.

save_shipping

If truthy, action may persist the cheapest returned rate as selected shipping option when current selection is not present.

language

Optional language value used to set runtime language for validation/messages.

REQ

Encoded required-fields rule payload used by form validation flow.

Supports not ... exclusion syntax after decode.

Behavior and Constraints

1. Requires action context (ACT request value).
2. Runs extension hook cartthrob_update_live_rates_start before main processing.
3. Saves customer info and cart before rate lookup.
4. Returns form-builder error if cart is empty.
5. If shippable subtotal is <= 0, action completes without live-rate quote application.
6. Applies language setting from request.
7. Decodes/merges required fields (REQ) with plugin-required fields, then validates.
8. Optionally switches shipping plugin from request (shipping_plugin) and optionally persists it (activate_plugin).
9. Requests live rates from active plugin.
10. If no rates or an error message is returned, action completes with error.
11. If save_shipping is truthy and current selected option is not returned, the action saves the cheapest returned option and price to cart.
12. Completes through form-builder action flow.

Notes:

• This endpoint is shipping-plugin dependent.
• Prefer using get_live_rates_form instead of hand-coding action posts.

Examples

Recommended usage via get_live_rates_form:

{exp:cartthrob:get_live_rates_form return="store/shipping" shipping_plugin="Cartthrob_shipping_ups"}
    {shipping_fields}
    <input type="submit" value="Get Live Rates" />
{/exp:cartthrob:get_live_rates_form}

Enable plugin activation and cheapest-rate save in posted inputs:

{exp:cartthrob:get_live_rates_form return="store/shipping" shipping_plugin="Cartthrob_shipping_ups" activate_plugin="yes"}
    {shipping_fields}
    <input type="hidden" name="save_shipping" value="yes" />
    <input type="submit" value="Apply Live Rates" />
{/exp:cartthrob:get_live_rates_form}