Introduction

Description

The EcomTrolleyService acts as the central service layer for all cart-related (aka "trolley") operations within a Nuxt-based e-commerce application. It encapsulates the logic required to create, manipulate, query, and finalize shopping trolleys, supporting both guest and authenticated customer journeys.

Purpose

• The primary role of EcomTrolleyService is to interface cleanly with the backend E-Commerce (ECOM) APIs, providing a strongly-typed, modular, and reusable abstraction layer that powers:
  • Cart Initialization – Enables the creation of a shopping trolley (cart) for users, whether logged in or browsing as a guest.
  • Cart Interaction – Allows adding/removing/updating items in the trolley using minimal boilerplate, while ensuring the correct authorization headers are included.
  • Promo and Discount Integration – Manages promotional codes, discount validations, and error handling for applied promos.
  • Checkout Preparation – Fetches delivery methods, calculates order totals, and updates delivery selections necessary before order placement.
  • Session Management – Maintains session continuity across devices and user states by supporting session tokens and customer IDs.
  • Conversion Flow – Seamlessly converts guest trolleys into persistent customer trolleys upon authentication, preserving cart state.
  • Cart Sharing & Collaboration – Supports shareable trolley codes and emailing carts for collaborative purchasing.

Architectural Role

• It serves as the service layer abstraction, decoupling UI components from raw API interaction.
• It ensures type safety and API consistency by using imported TypeScript interfaces (TrolleyResponse, TrolleyLineRequest, etc.).
• It handles all HTTP logic centrally via useAjaxEcom, simplifying error handling, authorization headers, and request options.
• Promotes DRY principles by consolidating repetitive trolley-related endpoint logic into centralized, reusable utility methods.

Functional Coverage

// Note : We're creating a trolley which will return new trolley_id and session_token
if (authStore.user) {
      trolleyHeaders["X-Toolstation-Customer-Id"] = (
        authStore.user as any
      ).token;
    }

Significance

• User Experience: It ensures a seamless, uninterrupted cart experience for users regardless of their login state or device.
• Maintainability: A single point of logic makes cart-related functionality easier to debug, extend, or refactor.
• Scalability: Easily integrates with additional features like gift wrapping, third-party logistics, or loyalty points without polluting UI layers.
• Security & Compliance: Manages proper header passing and user/session tracking required for GDPR-compliant commerce.