Behavior

Deep dive into how the checkout gift extension evaluates rules, manages the cart queue, and handles different product scenarios.

Rule Evaluation Pipeline

When the extension activates, it follows this pipeline for each automation:

For each automation:
  1. Check schedule (startDate / endDate)
  2. Filter by slider mode (if singleRule = "slider")
  3. Adjust customer tags (if rule uses custom tags)
  4. Adjust line attributes (if parameterized)
  5. Remove ignored products from input
  6. Wait for customer tag loading
  7. Evaluate rule conditions
  8. If TRUE → Process matched rule
  9. If FALSE + keep=false → Remove autocart products

Input Object

The rule evaluation uses a comprehensive input object built from the checkout state:

{
  cart: {
    lines: [...],           // All cart line items
    cost: {
      totalAmount: { amount, currencyCode },
      subtotalAmount: { amount, currencyCode },
    },
    buyerIdentity: {
      customer: {
        id, email, hasTags: [{ tag, hasTag }]
      },
      purchasingCompany: { ... } | null,
    },
    attribute: { value },   // Custom attribute (when pA parameter is set)
    attributes: [...],      // All cart attributes
    deliveryGroups: [...],  // Shipping delivery groups
  },
  discountCodes: [...],     // Applied discount codes
  payment_type: [...],      // Selected payment options
  localization: {
    country: { isoCode },
    language: { isoCode },
    currency: { isoCode },
  },
}

Processing Matched Rules

When a rule evaluates to true, the extension determines the action based on the rule's configuration:

Auto-Remove Mode

If a rule is configured for checkout removal, the extension removes the specified products from the cart:

Rule matched + scope includes "checkout-remove"
  → For each product in entries:
    → Find matching cart line (in customer-added lines, not autocart lines)
    → Queue removal

When customers need to choose from available products:

Product picker:

Calculates remaining quantity (total allowed minus already in cart)
Shows a modal with product cards and variant selection
Supports the "decline" option via cart attributes

Collection picker:

Shows products from the specified collection(s)
Tracks added quantity across all collection products
Excludes already-added products

Automatic (No Interaction)

Products are added to the cart automatically without customer input:

Free gift (100% discount):

Added immediately to the cart queue
Includes internal attributes for discount processing

Non-free products:

Added to the confirmation queue
Shown in a confirmation overlay before adding

Discount Handling

Automatic Discounts

When a rule has an automatic discount:

The discount data is attached as a line attribute on the cart item
The Discount Function reads this attribute server-side and applies the discount

Code Discounts

When a rule has a code discount:

The extension checks if the code is already applied
If not, queues the discount code application automatically

Auto-Clean Logic

The auto-clean system removes products from the cart when their associated rules are no longer valid:

For each autocart item in cart:
  1. Read the rule title from the item's attributes
  2. Skip if doNotEvaluateStorefront is enabled and the rule is storefront-only
  3. If the rule no longer exists → Queue removal
  4. If the rule still exists:
     a. Check schedule end date
     b. If end date has passed → Queue removal
     c. If no end date or not passed → Keep

Additionally, when automations are loaded:

Products whose variant IDs don't match the current rule's entries are removed
Collection-type rules are handled separately in the modal

Cart Mutation Queue

All cart mutations are processed sequentially through a queue system to prevent race conditions:

Queue: [mutation1, mutation2, mutation3, ...]
  │
  ▼ Process one at a time
  mutation1() → await → dequeue
  mutation2() → await → dequeue
  mutation3() → await → dequeue
  │
  ▼ All done
  Loading complete

The queue is critical for stability. Cart mutations must be sequential because Shopify's checkout API doesn't handle concurrent mutations well. Processing multiple mutations in parallel can cause race conditions and lost updates.

`doNotEvaluateStorefrontRule` Setting

This setting deserves special attention because it solves a common problem:

Problem: Some rules use conditions that only exist on the storefront (e.g., "customer is on the product page"). At checkout, these conditions can't be evaluated, so the rule fails — causing the product to be removed.

Solution: When doNotEvaluateStorefrontRule is enabled:

The extension identifies storefront-only rules
Their titles are tracked internally
During auto-clean and rule evaluation, products with matching titles are skipped entirely
This preserves the storefront's decision without re-evaluating conditions that don't apply at checkout

Country/Region Restrictions

The extension tracks excluded variants that fail due to country/region restrictions:

When a product add fails (variant unavailable in the current shipping country), the variant ID is stored in the excluded list
On subsequent evaluations, excluded variants are skipped
This prevents infinite retry loops for region-restricted products

When a product add fails (e.g., sold out, region-restricted), the extension displays a dismissible banner informing the customer that the item is unavailable.