Core Service Functions

1. createTrolley(trolleyRequest?)

• Purpose: Initializes a new trolley instance for a guest or authenticated user.
• Parameters:
  • trolleyRequest (optional): Contains attributes like sales channel or campaign code.
• Returns: TrolleyResponse with newly created trolley ID and session token.
• Usage:
  • When the user starts adding items without an existing trolley.
  • Typically the first API call in the cart lifecycle.
• Significance:
  • Kickstarts the shopping journey.
  • Handles both guest and logged-in users by setting the right headers.

2. convertToCustomer(trolleyId, trolleySessionToken?)

• Purpose: Converts a guest trolley to a customer trolley upon login or signup.
• Parameters:
  • trolleyId: Current trolley ID.
  • trolleySessionToken: Guest session identifier.
• Returns: TrolleyResponse with converted cart data.
• Usage:
  • When a guest logs in or registers during checkout.
• Significance:
  • Preserves the cart content and promotions for seamless transition from guest to logged-in state.

3. addToTrolley(trolleyId, addToTrolleyReq, trolleySessionToken?)

• Purpose: Adds a product line item to an existing trolley.
• Parameters:
  • trolleyId: Trolley to which the item is being added.
  • addToTrolleyReq: Contains product code, quantity, and possibly delivery/channel info.
  • trolleySessionToken: For guest user identification.
• Returns: Updated TrolleyResponse.
• Usage:
  • Triggered from product pages or quick-add components.
• Significance:
  • Core interaction for building the cart content.

4. fetchOrderTotals(trolleyId, trolleySessionToken?, trolleyRequest?)

• Purpose: Retrieves comprehensive order summary including subtotals, discounts, and taxes.
• Parameters:
  • trolleyId: ID of the trolley.
  • trolleySessionToken: Guest session token.
  • trolleyRequest: Filters like channel, promo codes, etc.
• Returns: OrderTotalResponse with pricing breakdown.
• Usage:
  • During cart review, checkout summary, or discount validation.
• Significance:
  • Essential for user visibility into financial details before confirming the purchase.

5. deleteTrolleyLine(lineId, trolleySessionToken?)

• Purpose: Removes a single product line from the trolley.
• Parameters:
  • lineId: Line item ID.
  • trolleySessionToken: (Optional) for guest carts.
• Returns: Updated TrolleyResponse.
• Usage:
  • Triggered when user removes an item from cart UI.
• Significance:
  • Ensures dynamic cart management and flexibility.

6. updateTrolleyItem(lineId, requestBody, trolleySessionToken?)

• Purpose: Updates a single attribute of a trolley item (quantity, delivery method, or channel).
• Parameters:
  • lineId: ID of the cart line.
  • requestBody: Must contain only one of: { quantity | delivery_method_code | channel }.
  • trolleySessionToken: Guest session token.
• Returns: Updated TrolleyResponse.
• Validation: Throws error if more than one field is provided.
• Usage:
  • When user changes quantity or selects a different delivery method on cart page.
• Significance:
  • Ensures controlled, atomic updates for cart stability.

7. updateExistingTrolleyItem(lineId, requestBody, trolleySessionToken?)

• Purpose: Updates one or more attributes of a trolley line using a PATCH operation.
• Parameters: Same as above, but supports multiple fields.
• Returns: Updated TrolleyResponse.
• Usage:
  • When a bulk change to the trolley line is required.
• Significance:
  • More flexible than updateTrolleyItem; useful for more complex UIs.

8. getTrolleyDetails(trolleyId, trolleySessionToken?)

• Purpose: Fetches the full state of the trolley (lines, attributes, statuses).
• Parameters:
  • trolleyId, trolleySessionToken.
• Returns: TrolleyResponse.
• Usage:
  • On cart page load or when resuming a session.
• Significance:
  • Ensures accurate cart rendering on front-end.

9. getTrolleyDiscounts(trolleyId, trolleySessionToken?)

• Purpose: Validates available discounts or promotions.
• Returns: TrolleyDiscountResponse or error object.
• Usage:
  • Pre-checkout validation or when applying promo codes.
• Significance:
  • Enhances savings awareness and discount transparency.

10. applyPromoCode(trolleyId, code, trolleySessionToken?)

• Purpose: Applies a user-provided promo code to the cart.
• Returns: Updated TrolleyResponse.
• Usage:
  • On promo code submission by the user.
• Significance:
  • Drives user engagement through discounts and incentives.

11. removeAppliedPromoCode(promoCodeId, trolleySessionToken?)

• Purpose: Deletes a previously applied promotional code.
• Returns: Updated TrolleyResponse.
• Usage:
  • When user changes their mind or applies a different code.
• Significance:
  • Offers flexibility and control over applied benefits.

12. updateTrolleyStatus(trolleyId, { status }, trolleySessionToken?)

• Purpose: Transitions trolley to a new status (e.g., from 'in_progress' to 'checked_out').
• Returns: void.
• Usage:
  • Triggered post-payment or when closing the order.
• Significance:
  • Critical for order state tracking and backend sync.

13. getTrolleyShareCode(trolleyId, trolleySessionToken?)

• Purpose: Creates a shareable code from the trolley content.
• Returns: TrolleyShareCodeCreateResponse.
• Usage:
  • When saving carts or sharing shopping lists.
• Significance:
  • Facilitates multi-device usage, collaborations, or repeat purchases.

14. sendTrolleyShareCodeByEmail(trolleyId, { recipient_email }, trolleySessionToken?)

• Purpose: Emails a shared trolley to another person.
• Usage:
  • Corporate buyers or team-based orders.
• Significance:
  • Increases UX engagement by adding social/functional sharing features.

15. getProductDeliveryDetails(productCode, branchId?)

• Purpose: Fetches delivery availability and details for a specific product.
• Returns: any.
• Usage:
  • On PDP or variant selection to show dynamic delivery options.
• Significance:
  • Enhances delivery transparency, boosting conversions.

16. getCheckoutDeliveryMethods(...)

• Purpose: Retrieves available delivery methods based on address data.
• Usage:
  • During checkout step.
• Significance:
  • Ensures delivery options are accurate and personalized.

17. updateTrolleyLineDeliveryMethod(...)

• Purpose: Updates delivery method at line-item level.
• Significance:
  • Supports mixed-mode deliveries (e.g., pickup + shipping in one order).

18. checkoutPostNL(...)

• Purpose: Checkout endpoint for Dutch PostNL delivery integration.
• Usage:
  • Final step for Dutch customers using PostNL.
• Significance:
  • Regional support for country-specific logistics.

19. deleteTrolley(trolleyId, trolleySessionToken?)

• Purpose: Deletes the entire trolley.
• Usage:
  • On user request or cart abandonment.
• Significance:
  • Clean-up operation to manage stale or abandoned carts.