# Add to cart actions

Source: https://govform.com/resources/documentation/article/25-17-action-add-to-cart
Topic: Action Settings

Use an Add to cart action to store one or more related items in a named cart while a person completes a service. It can support a basket-style journey, a collection of selected products, or a structured set of choices that later actions need to process together.

Treat a cart as journey data, not as a payment or stock-management system. If the service has financial, inventory or legal consequences, connect it to the appropriate controlled downstream process.

## Design the cart structure first

Decide the cart’s purpose, the stable name for it, the stable identifier for each item, and the data each item needs to retain. A clear structure prevents one page from accidentally replacing information added by another.

```
flowchart LR
  A[Person selects or configures an item] --> B[Add to cart action]
  B --> C[Named cart]
  C --> D[Review cart content]
  D --> E[Submit, process or amend]
```

Use one cart per distinct collection. For example, keep `selected_services` separate from `supporting_documents`. Do not reuse a cart ID for unrelated data just because the items are added on the same page.

## Configure an Add to cart action

1.  Add an **Add to cart** action from **Page actions**.
2.  Give the action a stable ID and name that describe what it adds.
3.  Set the **Cart ID** to the stable collection name.
4.  Set the **Cart item ID** to a stable key for the selected item or items.
5.  Use **Cart item value** to store the information later steps need.
6.  Turn on **Merge with existing** only when a later page intentionally contributes extra properties to the same item.
7.  Choose a trigger after the relevant answers have validated, then test adding, changing and revisiting items.

Cart IDs, item IDs and values support Liquid. Use a clear preceding Assign action if an item needs a complex calculated value; this makes the cart action easier to read and maintain.

## Use stable item IDs and useful values

The **Cart item ID** is the key used to identify an item within its cart. It can represent a single item or a collection of items. Make it stable and meaningful, such as `standard_subscription` or a controlled catalogue identifier. Do not use a label that may change for editorial reasons.

The **Cart item value** holds the data for the item. It can be a simple value or a structured object. Store only the values that later pages or actions need, and avoid duplicating sensitive fields that already exist elsewhere in the journey.

| Element | Good practice |
| --- | --- |
| Cart ID | a stable collection name, for example `selected_products` |
| Item ID | a unique business identifier, not display text |
| Item value | concise, predictable data needed by review or processing |
| Action name | describes the business event, for example “Add selected product” |

## Understand merge behaviour

With **Merge with existing** turned off, adding the same item ID replaces the existing item value. With merge turned on, the new object’s top-level properties are combined with the existing item instead.

Use merge only when multiple, controlled steps contribute different parts of the same item. It is a shallow merge: do not assume it will intelligently combine deeply nested data. Test the resulting value when properties overlap, when one page omits an optional property and when a person returns to edit an earlier page.

## Prevent duplicates and stale selections

An action may run again when people revisit a page, resume a draft or retry a route. Design the item ID and trigger so that repeated execution does not create accidental duplicates or silently overwrite important data. Use a Remove from cart action when an item should disappear after a person changes their selection.

Make the cart visible in a review or summary step where appropriate. A person should be able to understand what they have selected and amend it before the service commits a consequential outcome.

## Test checklist

-   The cart ID represents one clear collection.
-   Every item ID is stable and unique within the cart.
-   Values contain only the information later steps need.
-   Replace and merge behaviour matches the intended route.
-   Revisiting or resuming a page does not create duplicate or stale items.
-   Changing a selection removes or updates the earlier item deliberately.
-   The review or processing step uses the expected final cart content.

## Related guidance

-   [Remove from cart actions](<https://govform.com/resources/documentation/article/25-18-action-remove-from-cart>)
-   [Shared action settings](<https://govform.com/resources/documentation/article/25-00-action-shared-settings>)
-   [Assign actions](<https://govform.com/resources/documentation/article/25-02-action-assign>)
-   [Review and completion pages](<https://govform.com/resources/documentation/article/22-03-page-actions-review-and-completion>)