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.

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
• Shared action settings
• Assign actions
• Review and completion pages