Action - Liquid Tag Reference

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.set	Set the shipping name and price on the current cart	name, price
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”}’, status: 400, 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)

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.set

Sets the shipping method name and price on the current cart.

```liquid

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

Parameter	Required	Description
name	Yes	The shipping method name
price	Yes	The shipping cost

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.sfid %} ```

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

Related phases

• {% 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