rorans

2P Ads: Taxes Included Implementation Plan

Overview

This document outlines the implementation plan for handling taxesIncluded in the 2p ads network where merchandise comes from both publisher shops and advertiser shops. The solution addresses mixed tax scenarios where some shops include taxes in prices while others don't.

Current State Analysis

Data Flow

• Local merchandise: sellerProposal.merchandise.taxesIncluded → merchandiseLinesForUI() → NegotiatedContext.merchandiseLines.taxesIncluded → useTaxesIncluded() hook

rorans

Merchandise Mock Scenarios Testing Checklist

This guide provides a comprehensive checklist of all available merchandise scenarios, explaining the thinking behind each one and what to verify when testing.

How to Use This Checklist

1. Change CURRENT_MOCK_SCENARIO_NAME in app/mocks/fixtures/merchandise.data.ts
2. Refresh checkout
3. Follow the verification steps for each scenario
4. Check off scenarios as you test them

rorans

• merchandiseLinesForUI accepts violations
• priceMismatch is MERCHANDISE_EXPECTED_PRICE_MISMATCH or sellingPlanMismatch is MERCHANDISE_EXPECTED_SELLING_PLAN_MISMATCH
• for filled vs unfilled we always return priceMismatch or sellingPlanMismatch
• priceMismatch is exclusively consumed in useTaxExemption
• sellingPlanMismatch is used in one place useSellingPlanNotice

rorans

Of course. You have a very clear grasp of the situation. Let's refine your points into a structured and compelling argument. Here is a synopsis you can use.

---

Synopsis: Including Advertiser Merchandise in Persisted State Caching

The Core Challenge

As we integrate a second-party ads network, our checkout must handle carts containing both local (publisher) and remote (advertiser) merchandise. The core challenge is ensuring the integrity and accuracy of our persisted checkout state (persistedNegotiationResult) in this new, distributed context.

Our current persistence strategy is fundamentally dependent on the contents of the cart. To prevent data corruption, we must expand our definition of "the cart" to include advertiser merchandise when generating cache keys for this persisted state.

rorans

Scenario:

• Product Price: $100
• Initial State: User lands on the payment page. Credit Card is the default payment method, and PayPal is also available.
• Action 1: User applies a $20 Gift Card.
• Action 2: User switches the primary payment method from Credit Card to PayPal.
• Action 3: User clicks "Pay Now" to complete the purchase.

---

Step 1: Initial Page Load

rorans

added in this pr: https://github.com/Shopify/checkout-web/pull/6327

What does shippingRatesStatusToken do on the client?

The shippingRatesStatusToken is used for progressive shipping rates loading - a feature that allows Checkout to show approximate shipping rates immediately while more accurate rates are being calculated asynchronously in the background.

How it works

1. Token Generation
   When the server returns shipping rates with intermediateRates: true, it includes a shippingRatesStatusToken that uniquely identifies this shipping rate calculation job.

rorans

Step-by-Step Execution Flow: Stock Quantity Changes

Let me walk through a concrete example of how the code executes when dealing with stock issues.

Scenario: User wants 5 items, only 3 available

Step 1: Initial State (Page Load)

// User has persisted cart with 5 items

rorans

3DS (3D Secure) Flow Analysis - End to End

Table of Contents

1. Overview
2. Key Components
3. Flow Initiation
4. Authentication Process
5. Modal Implementation
6. Message Handling
7. Completion and Error Handling

rorans

Looking at the code, I can create a comprehensive mapping table showing how cart delivery groups and cart merchandise lines are transformed and consumed in the checkout flow. Let me analyze the key functions and create the mapping: Ran tool Based on my analysis of the code, here's a comprehensive mapping table showing how cart delivery groups and cart merchandise lines are transformed and consumed in the checkout flow:

Cart Delivery Groups → Delivery Lines Mapping

Cart Field	Mapped To	UI Responsibility	Data Gaps
CartDeliveryGroup Fields
id	AvailableDeliveryLine.id	Identifies unique delivery lines in split cart scenarios	None

rorans

import {currencyDecimalPlaces} from '@shopify/checkout-i18n';

import type {
  DeliveryMethod,
  Delivery,
  PickupPointLocation,
  PickupInStoreLocation,
  DeliveryNext,
  AvailableDeliveryLine,
  NoDeliveryRequiredLine,