Skip to content
Log in

Action - Liquid Tag Reference

On this page

The action simple tag executes built-in server-side operations in a Liquid controller. Use it to modify carts, apply promotions, set pricebooks and shipping, and change the current outlet.

:::note This tag works only inside a Liquid controller template (at controllers/<controller>/<action>.liquid). Actions run in the before, after, or final phases, not in page templates. :::

When action runs

Use action in a Liquid controller to execute server-side operations:

```liquid

{% before %} {% assign product_id = current_request.params.id %} {% assign qty = current_request.params.qty | default: 1 %}

{% action “cart.add”, product_identifier: product_id, quantity: qty %}

{% params product_id: product_id, qty: qty %} {% endbefore %} ```

Actions modify the session state immediately. Errors and warnings are added to the session.

Syntax

```liquid

{% action “action_name”, param1: value1, param2: value2 %} ```

Property Value
Tag Name action
Type Simple tag
Source StoreConnect
Use in phase before, after, final

Parameters

Parameter Description
Action name (string) The built-in action to execute: cart.add, promotion.apply, etc.
Named parameters Key-value pairs passed to the action (vary by action)

What’s available in action

  • current_request.params — from the request
  • Extracted params — values from {% params %} tags
  • All globals — current_store, current_customer, current_cart, etc.

Available actions

Action Purpose Key parameters
cart.select Make an existing resumable cart the current cart cart_identifier
cart.create Create a new empty cart and make it current —
cart.clone Copy an existing cart’s eligible items into a new cart cart_identifier
cart.add Add a product to the current cart product_identifier, quantity, price, override_price
cart.update Change the quantity or price of a cart item cart_item, quantity, price, override_price
cart.remove Remove a cart item cart_item
cart.empty Remove all items from the current cart —
shipping.add Attach a shipment to the current cart method, rate, price, label, provider, provider_rate, group, items
shipping.update Reprice or relabel a shipment the cart already has price, label, group
shipping.remove Take a shipment back off the cart group
shipping.set Deprecated. Use shipping.update name, price, group
outlet.set Set the current outlet (location) for the session outlet_id
pricebook.set Set the active pricebook for the session pricebook_id
pricebook.clear Clear the session pricebook —
promotion.apply Apply a promo code to the current cart code
promotion.remove Remove a specific promo code code
promotion.clear Remove all coupon promotions from the cart —

Common tasks with action

1. Add a product to the cart

```liquid

{% before %} {% assign product_id = current_request.params.product_id %} {% assign quantity = current_request.params.qty | default: 1 | plus: 0 %}

{% action “cart.add”, product_identifier: product_id, quantity: quantity %}

{% params product_id: product_id, quantity: quantity %} {% endbefore %}

{% after %} {% redirect to: current_store.cart_path, notice: “Item added to cart” %} {% endafter %} ```

2. Apply a promotion code

```liquid

{% before %} {% assign code = current_request.params.promo %}

{% if code == blank %} {% respond body: ‘{“error”: “promo code required”}’, layout: false %} {% endif %}

{% action “promotion.apply”, code: code %}

{% params code: code %} {% endbefore %} ```

3. Update cart item quantity

```liquid

{% before %} {% assign cart_item_id = current_request.params.item_id %} {% assign new_quantity = current_request.params.qty | plus: 0 %}

{%- assign item = current_cart.items | where: “id”, cart_item_id | first -%} {% action “cart.update”, cart_item: item, quantity: new_quantity %}

{% params cart_item_id: cart_item_id, new_quantity: new_quantity %} {% endbefore %} ```

Detailed action reference

cart.add

Adds a product to the current cart.

```liquid

{% action “cart.add”, product_identifier: product.sfid, quantity: 2 %} ```

Parameter Required Description
product_identifier Yes The Salesforce ID or SC ID of the product
quantity Yes Number of units to add
price No Override the product’s list price for this item
override_price No Explicit price to charge (requires permission)

:::note cart.add takes no booking dates, so it cannot add a bookable product. The action skips a bookable product and adds no error to the session. To add a bookable product, use the add to cart form with the booking fields. :::

cart.remove

Removes a cart item.

```liquid

{% action “cart.remove”, cart_item: line_item %} ```

Parameter Required Description
cart_item Yes The cart item object to remove

cart.update

Changes the quantity or price of a cart item.

```liquid

{% action “cart.update”, cart_item: line_item, quantity: 5 %} ```

Parameter Required Description
cart_item Yes The cart item object to update
quantity No New quantity
price No Override the item’s price

cart.empty

Removes all items from the current cart.

```liquid

{% action “cart.empty” %} ```

No parameters.

cart.clone

Clones an existing cart’s eligible items into a brand-new cart and makes it the current cart. Useful for re-order flows and quote duplication.

```liquid

{% action “cart.clone”, cart_identifier: order.cart.sfid %} ```

Parameter Required Description
cart_identifier Yes The Salesforce ID or SC ID of the source cart

Requirements: - A logged-in shopper is required - The source cart must belong to the current store

What gets copied: A new cart is created for the logged-in shopper, and each eligible item from the source cart is added. An item is excluded when: - The product is neither purchasable nor quote-requestable - There is not enough inventory to cover the item’s quantity - The product is bookable (appointment, class, etc.) - The item is part of a bundle

Result: - Some or all items copied — the new cart becomes current; excluded items are omitted silently - No items could be copied — the action fails, an error is added to the session, original cart unchanged

:::warning When only some items are excluded, the clone succeeds and excluded items are omitted silently, so the shopper is not automatically shown which items were dropped. If you need to inform the shopper, compare the source and new carts and render your own message. :::

cart.select

Makes an existing resumable cart the current cart.

```liquid

{% action “cart.select”, cart_identifier: previous_cart.sfid %} ```

Parameter Required Description
cart_identifier Yes The Salesforce ID or SC ID of the cart to select

cart.create

Creates a new empty cart and makes it the current cart.

```liquid

{% action “cart.create” %} ```

No parameters.

promotion.apply

Applies a promotion code to the current cart.

```liquid

{% action “promotion.apply”, code: “SAVE10” %} ```

Parameter Required Description
code Yes The promotion code to apply

promotion.remove

Removes a specific promotion code from the cart.

```liquid

{% action “promotion.remove”, code: “SAVE10” %} ```

Parameter Required Description
code Yes The promotion code to remove

promotion.clear

Removes all coupon promotions from the cart.

```liquid

{% action “promotion.clear” %} ```

No parameters.

shipping.add

Attaches a shipment to the current cart, writing the method, charge and label exactly as submitting the checkout shipping step would. The cart reaches payment already costed, without the customer choosing a delivery method.

```liquid

{% action “shipping.add”, method: “regular_post”, price: 9.95, label: “Standard delivery” %} ```

Parameter Required Description
method Yes The shipping method, for example regular_post or express_post. Every product in scope must list it
rate No A custom shipping rate’s id. The charge becomes that rate’s calculated cost for the items in scope
price No The shipping charge. Used as given when there is no rate, and overrides the rate’s calculated cost when there is. Defaults to 0
label No The shipping line’s name on the cart, summary and order. Without it the label falls back to what the checkout step would generate
provider No The shipping provider name, for example Australia Post or Shippit
provider_rate No The provider’s service name, for example EXPRESS POST + SIGNATURE. Requires provider
group No Multi-shipping only. The delivery this shipment belongs to
items No Multi-shipping only. The cart items this shipment covers. See DeliveryGroup - Liquid Object Reference

rate and provider are mutually exclusive: a shipment is either a custom rate or a provider rate, as at checkout.

shipping.update

Reprices or relabels the shipment a cart already has, whether the customer chose it at checkout or shipping.add attached it. Supply at least one of price or label.

```liquid

{% action “shipping.update”, price: 12.91, label: “Express delivery” %} ```

Parameter Required Description
price No The new shipping charge, charged as given
label No The new customer-facing shipping label
group No Multi-shipping only. The delivery to update, and required once the cart has more than one

method, rate, provider, provider_rate and items are rejected here. Those decide what may ship and what the carrier is asked to do, so changing them needs the cart revalidated against a different method. Call shipping.add again instead, which replaces the shipment outright.

shipping.remove

Takes the cart’s shipping back off, leaving it as though no delivery method had been chosen.

```liquid

{% action “shipping.remove” %} ```

Parameter Required Description
group No Multi-shipping only. The single delivery to remove. Omit it to remove every delivery

A delivery that shipping.add assigned is deleted outright, so the items in it return to automatic grouping. An automatically grouped delivery keeps the items and loses only the selected method.

shipping.set

:::warning Deprecated. Use shipping.update instead. shipping.set passes through to shipping.update and will be removed in a future release. Each call logs a deprecation warning in the web console. :::

To migrate, rename the action and rename name: to label:. Every other parameter is the same.

```liquid

{% comment %} before {% endcomment %} {% action “shipping.set”, name: “Standard Shipping”, price: 10.00 %}

{% comment %} after {% endcomment %} {% action “shipping.update”, label: “Standard Shipping”, price: 10.00 %} ```

Parameter Required Description
name No The shipping label. Called label on shipping.update
price No The shipping charge
group No Multi-shipping only. The delivery to update, as on shipping.update

At least one of price or name must be supplied.

pricebook.set

Sets the active pricebook for the session.

```liquid

{% action “pricebook.set”, pricebook_id: pricebook.sfid %} ```

Parameter Required Description
pricebook_id Yes The Salesforce ID of the pricebook to activate

pricebook.clear

Clears the session pricebook, returning to the default pricebook.

```liquid

{% action “pricebook.clear” %} ```

No parameters.

outlet.set

Sets the current outlet (location) for the session.

```liquid

{% action “outlet.set”, outlet_id: outlet.id %} ```

Parameter Required Description
outlet_id Yes The Salesforce ID of the outlet to activate

Key behaviors

  • Actions run synchronously — the action completes before the next Liquid statement
  • Errors are captured — errors and warnings are added to the session; check session errors if needed
  • State is updated immediately — after a cart.add, current_cart reflects the new item
  • No return value — actions do not return data; they modify session state
  • Use in before for initialization — set up pricebooks, outlets, and promotions in before
  • Use in after for post-render logic — for conditional actions based on what rendered
  • Form vs. action — use {% form %} for customer-initiated commerce; use {% action %} for server-driven logic
  • {% before %} — primary phase for actions; set up the session before rendering
  • {% after %} — use actions after rendering to perform post-render operations
  • {% final %} — actions run asynchronously; fire-and-forget work

Was this article helpful?

Was this article helpful?