DEV Community: yuntongsoft

The Dual-Plane Problem: Syncing Discount Data Across Shopify's Two Isolated Worlds

yuntongsoft — Sun, 11 Oct 2026 03:41:35 +0000

Shopify apps that offer both checkout-time discounts and storefront widgets face an architectural problem that is rarely discussed systematically: the Function runtime and the Theme Extension runtime live in two isolated data planes that can't directly talk to each other. Your discount rules exist in one world, your storefront widgets live in the other, and keeping them consistent is a surprisingly hard engineering problem.

We built Markdo with 18 Liquid template widgets that display discount information on storefronts — tier tables, flash sale countdowns, cart goals, spin-to-win wheels, and more. This post covers the data sync architecture, the i18n bridge pattern for Liquid-to-JavaScript translation, the XSS hardening journey, and the production incidents that shaped the design.

The Two Isolated Planes

Shopify Functions (WASM modules that run at checkout) read their configuration from $app: namespace metafields — a private namespace scoped to the app itself, invisible to any other app or to the storefront. Theme Extensions (Liquid templates that render on storefronts) can only read from the app namespace, which is the public metafield namespace exposed to the storefront context — specifically app.metafields.app_config.*.

This creates a fundamental problem:

Plane 1 (Checkout): The Discount Function reads rules from $app:markdo.discount_rules — a JSON metafield containing all rule configurations. This drives what discount actually applies at checkout.
Plane 2 (Storefront): The 18 Liquid widgets read from app.metafields.app_config.widget_bindings — a completely separate JSON metafield that contains widget configuration and display data.

If a merchant creates a "20% off orders over $100" rule and enables the Smart Discount Banner widget, the Function needs the rule in Plane 1 to apply the discount, and the widget needs the rule data in Plane 2 to display "20% OFF orders $100+". If Plane 2 is stale or missing, the widget shows nothing — or worse, shows wrong information.

The solution is a sync system that runs on every rule change: the backend reads the canonical rules from Plane 1, builds display-optimized snapshots, and writes them into Plane 2.

The RuleSnapshot Bridge

Every time a merchant creates, edits, or toggles a rule, the sync service runs syncRuleSnapshotsToWidgets(). This function reads all widget bindings from the app_config metafield, finds the matching rule for each binding, and generates a RuleDisplaySnapshot:

function buildRuleSnapshot(rule: ShopifyRuleConfig): RuleDisplaySnapshot {
  const snapshot: RuleDisplaySnapshot = {
    discountType: rule.discountType,
    discountValue: rule.discountValue,
    ruleName: rule.name,
    ruleActive: rule.isActive,
    ruleVersion: rule.revision,
  };

  switch (rule.discountType) {
    case "volume":
      if (rule.discountTiers?.length) {
        snapshot.tiers = rule.discountTiers.map(t => ({
          min: t.minQty, value: t.discount
        }));
        snapshot.minQuantity = rule.discountTiers[0].minQty;
      }
      break;
    case "spend_save":
      if (rule.spendTiers?.length) {
        snapshot.tiers = rule.spendTiers.map(t => ({
          min: t.minAmount, value: t.discount
        }));
        snapshot.minPurchase = rule.spendTiers[0].minAmount;
      }
      break;
    case "mix_match":
      snapshot.mixMatchConfig = {
        minItems: rule.mixMatchConfig.minItems,
        discountType: rule.mixMatchConfig.discountType,
        discountValue: rule.mixMatchConfig.discountValue,
      };
      break;
    case "bogo":
    case "advanced_bogo":
      snapshot.bogoConfig = {
        buyQty: rule.bogoBuyQty,
        getQty: rule.bogoGetQty,
        getDiscount: rule.bogoGetDiscount,
      };
      break;
  }
  return snapshot;
}

The snapshot is a flattened, display-optimized projection of the rule. It doesn't contain the full rule configuration — just what the storefront needs to render. This matters because metafield values have size limits — most types are capped at 64KB, and JSON metafields at 128KB — and with 18 widgets each potentially bound to a rule, the data needs to be compact.

The Liquid template reads the snapshot through the binding:

{% assign bindings = app.metafields.app_config.widget_bindings.value %}
{% assign binding = bindings['smart-discount-banner'] %}
{% if binding and binding.enabled == true %}
  {% assign snap = binding.ruleSnapshot %}
  {% assign discount = snap.discountValue | default: 0 %}
  {% assign min_purchase = snap.minPurchase | default: 0 %}
  <div class="mk-banner" data-discount="{{ discount | escape }}" data-min="{{ min_purchase | escape }}">
    {{ 'smart_discount_banner.qualify_pct' | t: value: discount | escape }}
  </div>
{% endif %}

Three Metafield Channels

The widget system actually uses three separate metafield channels, each serving a different purpose:

widget_bindings — The primary channel. A JSON object keyed by widget handle (e.g., "spin-to-win", "tier-table"). Each entry contains enabled, settings (visual config like colors), ruleId, ruleActive, ruleVersion, and ruleSnapshot. Every widget reads from this.
widget_tier_rules — A JSON array of full tier rule data for product-page widgets (tier-table, quantity-discount-badge). These widgets need the complete tier structure with product conditions, not just a snapshot.
widget_mix_match — A JSON array of mix-and-match rule configs with eligible collection and product type data. The mix-match-picker widget needs this to filter which products qualify.

Why three channels instead of one? Size limits and access patterns. The bindings metafield is read on every page load by every widget — it needs to be small. The tier rules and mix-match configs are only read by specific widgets on specific pages, so they can afford to be larger.

One prerequisite worth mentioning: for Theme Extensions to read these metafields, the app must define them with storefront access set to PUBLIC_READ in the metafield definition (via the Admin API's MetafieldDefinition input). Without this, the app.metafields.app_config.* namespace is invisible to the storefront context even if the metafield exists.

The i18n Bridge: Liquid to JavaScript

All 18 widgets support 6 languages (English, German, French, Spanish, Japanese, Chinese). Shopify's | t filter handles Liquid-side translation, but JavaScript running in the browser can't call | t. The solution is an "i18n bridge" pattern that serializes all translated strings into a JSON data attribute at render time:

{%- assign t_spin_wheel = 'spin_to_win.spin_wheel' | t -%}
{%- assign t_spin_now = 'spin_to_win.spin_now' | t -%}
{%- assign t_spinning = 'spin_to_win.spinning' | t -%}
{%- assign t_try_again = 'spin_to_win.try_again' | t -%}
{%- assign t_you_won = 'spin_to_win.you_won' | t -%}

{%- assign j_spin_wheel = t_spin_wheel | json -%}
{%- assign j_spin_now = t_spin_now | json -%}
{%- assign j_spinning = t_spinning | json -%}
{%- assign j_try_again = t_try_again | json -%}
{%- assign j_you_won = t_you_won | json -%}

{%- assign i18n_json = '{"spinWheel":' | append: j_spin_wheel | append: ',"spinNow":' | append: j_spin_now | append: ',"spinning":' | append: j_spinning | append: ',"tryAgain":' | append: j_try_again | append: ',"youWon":' | append: j_you_won | append: '}' -%}

<div class="mk-spin-fab"
     data-i18n="{{ i18n_json | escape }}">

The key detail is the two-phase approach. Phase 1 applies | json to each translation string individually via intermediate {% assign %} variables. This is critical because in Liquid's pipe chain, | json operates on the accumulated result — writing append: t_spin_wheel | json would JSON-encode the entire concatenated string {"spinWheel":<translation>, not just the translation. Phase 2 assembles the pre-encoded fragments into a valid JSON string, then applies | escape once to HTML-entity-encode the whole thing for safe embedding in an HTML attribute.

Then in JavaScript:

var fab = document.querySelector('.mk-spin-fab');
var t = JSON.parse(fab.dataset.i18n || '{}');
// Later:
button.textContent = t.spinning;
resultEl.textContent = t.youWon;

The | json filter is critical here — it properly escapes strings for JSON embedding, handling quotes, unicode characters, and newlines. But it must be applied to each value before assembly, not during the append chain. The final | escape filter HTML-entity-encodes the complete JSON string, so a French translation containing an apostrophe ("l'offre") or double quotes won't break the attribute boundary. The browser decodes HTML entities before JavaScript reads dataset.i18n, so JSON.parse() receives clean JSON.

This pattern means zero server round-trips for translations. The Liquid template renders once with the customer's locale, bakes all translated strings into the DOM, and JavaScript reads them instantly.

The Currency Symbol Problem

Every widget that displays monetary amounts needs the currency symbol. Shopify does provide {{ localization.currency.symbol }} — the localization object is populated in multi-currency stores based on the buyer's selected currency, but in single-currency stores, or in some App Block rendering contexts, it may be unavailable or return an empty currency. You also can't use it in external JavaScript files where Liquid isn't evaluated.

We maintain a shared snippet (_currency-symbol.liquid) that maps 20 supported currencies as a reliable fallback. It reads localization.currency.iso_code when available, falling back to shop.currency (the store's default):

{% assign active_currency = localization.currency.iso_code | default: shop.currency %}
{% case active_currency %}
  {% when 'USD' %}{% assign currency_symbol = '$' %}
  {% when 'EUR' %}{% assign currency_symbol = '€' %}
  {% when 'GBP' %}{% assign currency_symbol = '£' %}
  {% when 'JPY' %}{% assign currency_symbol = '¥' %}
  {% comment %} ... 16 more currencies ... {% endcomment %}
{% endcase %}

When localization is unavailable (single-currency store, or certain App Block rendering contexts), the | default: shop.currency fallback ensures we always resolve to something. If localization itself doesn't exist in the rendering context, Liquid treats localization.currency.iso_code as nil and the default filter kicks in — no error, just a silent fallback to shop.currency. The map then gives us a consistent symbol regardless of context.

Widgets originally attempted {% render '_currency-symbol' %} — but {% render %} runs in an isolated scope, so {% assign currency_symbol %} inside the snippet never reaches the parent template. The parent sees currency_symbol as nil. To make a shared snippet work, you'd need a return-style pattern where the snippet outputs the value and the parent captures it:

{% comment %} _currency-symbol.liquid — return-style {% endcomment %}
{% assign active_currency = localization.currency.iso_code | default: shop.currency %}
{% case active_currency %}
  {% when 'USD' %}{% assign currency_symbol = '$' %}
  {% when 'EUR' %}{% assign currency_symbol = '€' %}
  {% when 'GBP' %}{% assign currency_symbol = '£' %}
  {% when 'JPY' %}{% assign currency_symbol = '¥' %}
  {% comment %} ... 16 more currencies ... {% endcomment %}
{% endcase %}
{{- currency_symbol -}}

The parent template wraps the render in {% capture %} and strips whitespace:

{% capture currency_symbol %}{% render '_currency-symbol' %}{% endcapture %}
{% assign currency_symbol = currency_symbol | strip %}

This works, but adds verbosity and the {% render %} output still introduces newlines that can break inline <script> blocks. Most of our widgets that need the symbol in Liquid templates use the {% capture %} pattern. The exit-intent.liquid widget ended up inlining the entire currency map to sidestep both problems:

{% comment %} Inline currency symbol — avoids whitespace from {% render %} breaking inline JS {% endcomment %}
{% assign active_currency = localization.currency.iso_code | default: shop.currency %}
{% case active_currency %}{% when 'EUR' %}{% assign curr_sym = '€' %}...{% endcase %}

For widgets that use currency in external JavaScript files, the Liquid-side map can't help — the JS needs its own copy. We pass the active currency code via a data-currency attribute (rendered inside the {% if widget_visible %} block, so it only exists when the widget actually renders) so the JS knows which entry to look up:

<div class="mk-widget" data-currency="{{ active_currency | escape }}">

var _cm = {USD:'$',EUR:'€',GBP:'£',JPY:'¥',CNY:'¥',KRW:'₩',INR:'₹',BRL:'R$',
           CAD:'C$',AUD:'A$',CHF:'Fr.',SEK:'kr',NOK:'kr',DKK:'kr',PLN:'zł',
           MXN:'$',NZD:'NZ$',SGD:'S$',HKD:'HK$',TWD:'NT$'};
var el = document.querySelector('.mk-widget');
var sym = _cm[el.dataset.currency] || '$';

Three parallel implementations of the same currency map — return-style Liquid snippet (via {% capture %}), inline Liquid, and JavaScript — all manually kept in sync. It's not elegant, but it works across all three rendering contexts (Liquid template, inline script, external JS file).

XSS Hardening: 18 Templates, 6 Vulnerabilities

Our security audit found XSS vulnerabilities in 6 of the 18 Liquid templates. The pattern was consistent: user-controlled content (merchant-entered text in block settings) was being injected into the DOM via innerHTML without escaping.

The FOMO notification widget was the most severe case. It displayed customizable notification messages like "John from London just purchased!" — the Liquid template used {{ block.settings.message_text }} for the initial render, and JavaScript for dynamic updates:

<!-- Liquid output without explicit | escape filter -->
<div class="fomo-text">{{ block.settings.message_text }}</div>

// BEFORE (vulnerable)
txEl.innerHTML = d.text; // d.text from merchant config

Shopify's fork of Liquid includes built-in HTML auto-escaping at the template compilation level, so {{ block.settings.message_text }} does get escaped by default. But relying on implicit auto-escaping is fragile — content can be marked safe through various code paths, and the protection isn't always obvious to audit. The safer practice is to always apply an explicit | escape filter as defense-in-depth. The more immediate vulnerability in our case, though, was the JavaScript side: innerHTML interprets any HTML in the string, so a merchant config value containing <img src=x onerror=...> would execute regardless of what Liquid does server-side.

The fix was switching to textContent for all dynamic text updates:

// AFTER (safe)
txEl.textContent = d.text;

The exit-intent widget had a similar issue — it built HTML strings from merchant-configured discount codes and inserted them via innerHTML. The fix was to use DOM APIs (createElement, textContent) instead of string concatenation.

The tier-table widget builds HTML table rows from tier rule data. Since the data comes from parsed JSON (numeric minQty and discount values), the risk is lower — but we still switched to textContent for cell content and only use innerHTML for the static table structure.

The audit also led to extracting all inline JavaScript from Liquid templates into external .js asset files. This serves two purposes: it satisfies Content Security Policy (CSP) requirements that prohibit inline scripts, and it separates concerns — Liquid handles data binding, JavaScript handles interactivity.

Three widgets got their JS extracted: mix-match-picker.liquid, spin-to-win.liquid, and exit-intent.liquid. The pattern is consistent: Liquid renders the DOM structure with data-* attributes containing all necessary data, and the external JS file reads those attributes to initialize behavior.

The Binding Bootstrap: A Three-State Gate

Every one of the 18 widgets starts with an identical "binding bootstrap" — a Liquid preamble that reads the widget's configuration from the shared metafield:

{% assign bindings = app.metafields.app_config.widget_bindings.value %}
{% assign widget_enabled = false %}
{% assign widget_visible = false %}
{% if bindings %}
  {% assign binding = bindings['flash-sale'] %}
  {% if binding %}
    {% if binding.enabled == true %}
      {% assign widget_enabled = true %}
      {% assign widget_visible = true %}
      {% if binding.planLocked == true %}
        {% assign widget_visible = false %}
      {% endif %}
      {% if widget_visible %}
        {% assign bs = binding.settings %}
        {% if bs.primary_color != blank %}{% assign primary_color = bs.primary_color %}{% endif %}
        {% if bs.bg_color != blank %}{% assign bg_color = bs.bg_color %}{% endif %}
      {% endif %}
    {% endif %}
  {% endif %}
{% endif %}

This implements a state gate with four outcomes:

No binding exists → widget doesn't render at all (merchant hasn't configured it)
Binding exists, enabled: false → widget is configured but disabled (merchant turned it off)
Binding exists, enabled: true, planLocked: true → widget is enabled but locked behind a paywall (merchant is on a free plan, paid widget unavailable). widget_enabled is true but widget_visible is false — the binding data stays intact, so upgrading just flips planLocked to false.
Binding exists, enabled: true, planLocked: false → widget renders with the merchant's visual settings

The widget_enabled vs widget_visible distinction matters for the "paid widget on free plan" scenario. When a merchant downgrades, we set planLocked: true on non-free widgets but keep enabled: true and the binding data intact. The widget doesn't render, but if the merchant upgrades again, we flip planLocked to false without needing to rebuild the configuration. In practice, widget_enabled tracks whether the merchant explicitly turned the widget on (useful for logging and debugging), while rendering decisions depend solely on widget_visible.

Production Incidents

Incident 1: Sync Order Catastrophe

A refactor accidentally swapped the order of metafield writes in the sync pipeline. The metaobject write (backup storage) was made to execute first, and when it failed (due to a stale ID), the error short-circuited the entire sync — meaning the Function metafield (Plane 1) was never updated. Automatic discounts silently stopped working for affected merchants.

The fix: restore "metafield first, metaobject as non-blocking backup" ordering, and add self-healing for stale metaobject IDs. The metafield write to Plane 1 happens first; the code below shows the backup metaobject step that follows:

try {
  await updateMetaobject(shop, rules);
} catch (e) {
  if (isRecordNotFound(e)) {
    await clearStaleMetaobjectId(shop);
    await createMetaobject(shop, rules); // retry with create path
  }
  // metaobject is a backup — if it fails, Plane 1 (metafield) already has the data.
  // We await it (not fire-and-forget) so the caller can log duration, but the catch
  // ensures the failure doesn't propagate to the sync pipeline.
}

Incident 2: Paid Widgets After Downgrade

When merchants downgraded from Pro to Free, the UI correctly showed paid widgets as "locked." But the metafield had no planLocked field set for those widgets (defaulting to falsy), so they continued rendering on storefronts. Merchants were getting paid-tier features for free.

The fix was a lockPaidWidgets() function that runs on plan downgrade, setting planLocked: true on all non-free widgets while keeping enabled and settings intact — so upgrading instantly restores them:

async function lockPaidWidgets(shop: string) {
  const bindings = await readBindings(shop);
  for (const def of WIDGET_DEFINITIONS) {
    if (!def.free && bindings[def.handle]) {
      bindings[def.handle].planLocked = true;
    }
  }
  await writeBindings(shop, bindings);
}

Incident 3: Stale Widget Data After Rule Edit

A merchant edited a rule (changed discount from 10% to 20%), but the storefront widget continued showing "10% OFF." The widget bindings stored the ruleId but not the rule version, so there was no way to detect that the rule had changed since the last sync.

The fix was adding ruleVersion (mapped to Rule.revision) to every binding write. The sync writes the new version to both binding.ruleVersion and binding.ruleSnapshot.ruleVersion atomically. The storefront then checks for internal inconsistency:

{% if binding.ruleVersion != binding.ruleSnapshot.ruleVersion %}
  {% comment %} Partial sync detected — snapshot wasn't fully updated {% endcomment %}
  {% assign widget_visible = false %}
{% endif %}

This catches partial sync failures — where the outer version was bumped but the snapshot wasn't regenerated. It does not catch a complete sync failure where neither field is updated (both remain at the old version, equal to each other). That scenario is handled by the retry and alerting layer described in the Sync Resilience section below: exponential backoff for transient failures, alerting on failure rate spikes, and a manual re-sync button as the escape hatch. The version check is one layer of defense, not the only one.

Incident 4: Priority=0 Treated as Falsy

The tier-rules shared JavaScript used || 999 as a fallback for missing priority values. But priority: 0 is a legal value meaning "highest priority" — and 0 || 999 evaluates to 999, pushing the highest-priority rule to the bottom.

// BEFORE (buggy)
rules.sort((a, b) => (a.priority || 999) - (b.priority || 999));

// AFTER (correct)
rules.sort((a, b) =>
  (a.priority != null ? a.priority : 999) - (b.priority != null ? b.priority : 999)
);

Incident 5: Concurrent Metafield Writes

Two simultaneous rule edits from the merchant's admin could trigger concurrent read-modify-write cycles on the same metafield. Thread A reads bindings, Thread B reads bindings, Thread A writes (adding widget X), Thread B writes (adding widget Y) — Thread A's write is lost because Thread B's write was based on the stale pre-X state.

The fix was a per-shop async mutex:

const shopLocks = new Map<string, Promise<void>>();

async function withShopLock<T>(shop: string, fn: () => Promise<T>): Promise<T> {
  const prev = shopLocks.get(shop) ?? Promise.resolve();
  const next = prev
    .catch((e) => {
      // Previous operation failed — log but don't cascade the failure.
      // Each sync is independent; one merchant's stale data shouldn't block the next write.
      console.warn(`[withShopLock] previous op failed for ${shop}:`, e);
    })
    .then(fn);
  const cleanup = next.finally(() => {
    if (shopLocks.get(shop) === next) {
      shopLocks.delete(shop);
    }
  });
  cleanup.catch(() => {}); // Prevent unhandled rejection from the cleanup chain
  shopLocks.set(shop, next);
  return next;
}

Each operation chains onto the previous one for the same shop, serializing writes without blocking other shops. The .catch() before .then(fn) is deliberate: if the previous operation failed, we log it and still proceed with the current operation. Each sync is an independent write — one merchant's stale data shouldn't block the next write. The cleanup logic carefully only deletes the Map entry when no successor has chained on, preventing unbounded growth.

Sync Resilience: Retries, Alerts, and Rollbacks

The five incidents above all share a common theme: silent failures. A sync fails, nobody notices, and the storefront shows stale or missing data until a merchant complains. After incident #1 (the sync order catastrophe), we added a resilience layer on top of the sync pipeline:

Structured failure logging. Every sync attempt logs a structured event with shop, ruleId, widgetHandle, attempt, and duration. Failures include the full error object. This lets us query "show me all sync failures for shop X in the last hour" from our log aggregator.

Exponential backoff retry. Transient failures (Shopify API rate limits, network timeouts) retry up to 3 times with exponential backoff (1s, 2s, 4s). Permanent failures (validation errors, missing resources) fail immediately — retrying won't help.

Alerting on failure rate. If a shop's sync failure rate exceeds 10% over a 15-minute window, an alert fires. This catches the "silent degradation" pattern where individual failures are rare but accumulate over time.

Manual re-sync endpoint. The admin panel has a "Re-sync widgets" button per rule that forces a full syncRuleSnapshotsToWidgets() run. This is the escape hatch for when automated sync fails for non-transient reasons (e.g., a bug in the snapshot builder that we've since fixed).

Metafield rollback on corruption. If a sync write produces a metafield that fails JSON parsing on the next read, we log an alert and restore from the metaobject backup (the non-blocking write from incident #1). This is a last resort — the metaobject backup exists precisely for this recovery scenario.

The key insight: sync failures are not "if" but "when." Shopify's API has rate limits, network partitions happen, and metafield size limits surprise you. The system needs to detect failures, retry what's retryable, alert on what's not, and provide manual override for edge cases.

The Shared Module Pattern

Some widgets share logic. The tier-table and quantity-discount-badge widgets both need to resolve tier rules from a shared pool, match them to the current product, and sort by priority. Instead of duplicating this logic, we extracted it into tier-rules-shared.js:

window.MkTierRules = {
  resolveTiers: function(raw) { /* parse + normalize tier rules */ },
  matchesProduct: function(rule, productId, productType, tags, collections) {
    /* check product conditions */
  }
};

Both widgets load the shared script via <script src="{{ 'tier-rules-shared.js' | asset_url }}" defer>, then use a retry-based initialization to handle the race condition where the deferred script hasn't loaded yet:

var retries = 0;
function init() {
  if (!window.MkTierRules) {
    if (retries++ < 20) { setTimeout(init, 50); }
    return;
  }
  var tiers = window.MkTierRules.resolveTiers(rawRules);
  // ... proceed with rendering
}
init();

20 retries at 50ms intervals gives a 1-second window for the shared script to load — generous enough for slow connections, short enough to not noticeably delay rendering. The rawRules variable is read from a data-tier-rules JSON attribute on the widget root element, which the Liquid template renders from the widget_tier_rules metafield channel.

What I Learned

After shipping 18 widgets across 6 languages with a dual-plane sync architecture, here's what I'd tell anyone building a similar system:

Design the sync boundary first. The split between Plane 1 (checkout Function data) and Plane 2 (storefront widget data) is the hardest part to get right. Get the snapshot schema wrong, and you'll either blow the metafield size limit or leave widgets without the data they need.
Version everything — but don't rely on versions alone. Rule revisions, binding versions, snapshot versions — version numbers let you detect partial sync failures where one layer was updated but another wasn't. But they can't detect a complete sync failure where nothing was updated. For that, you need retry logic, failure alerting, and a manual re-sync escape hatch.
The i18n bridge pattern scales well. Serializing translations into data-i18n JSON attributes is a bit verbose, but it's mechanical, auditable, and has zero runtime cost. We added Japanese and Chinese late in the project with zero JavaScript changes.
Inline JavaScript is technical debt. CSP compliance, maintainability, and browser caching all push toward external JS files. Extract early — retrofitting is painful when you have 18 templates with inline scripts.
Metafield concurrency is real. Any app that does read-modify-write on metafields needs serialization. The per-shop mutex pattern is simple and effective, but you need to think about cleanup to prevent memory leaks.

Markdo is a Shopify discount app with 18 storefront widgets and a Rust-based checkout Function. The widget system described here is part of the Theme Extension that renders discount information on merchant storefronts.

Building a Webhook Queue on PostgreSQL: Why We Ditched Redis for Shopify Webhook Processing

yuntongsoft — Tue, 06 Oct 2026 07:41:27 +0000

When you're building a Shopify app, webhooks are your lifeline. Orders, products, customers, checkouts — Shopify sends you a webhook for everything. But here's the problem: Shopify expects a 200 response within 5 seconds, or it retries. And if you process webhooks synchronously, a single slow handler blocks your entire server.

Our solution? A custom async job queue built entirely on PostgreSQL. No Redis. No Bull. No external dependencies. Just a database table, some clever SQL, and a lot of edge case handling.

This is the story of how we built it, why we made these choices, and the production bugs that taught us the hard way.

The Problem: Shopify Webhooks Are Brutal

Shopify's webhook contract is simple but unforgiving:

Shopify sends a POST request to your endpoint
You must respond with 200 OK within 5 seconds
If you don't respond, Shopify retries (up to 19 times over 48 hours)
If you respond with anything other than 200, Shopify retries
Shopify doesn't guarantee delivery order
Shopify can send the same webhook multiple times (at-least-once delivery)

Our discount app, DealCraft, needs to do a lot of work when an order webhook arrives:

Match the order to discount rules
Record analytics
Update customer usage counts
Generate post-purchase discount codes
Trigger loyalty point awards
Check referral rewards
Sync metafields back to Shopify

This takes 2-10 seconds per order. If we processed synchronously, we'd timeout on every webhook. So we needed a queue.

Why Not Redis?

The obvious choice is Redis + Bull (or BullMQ). It's the standard Node.js job queue. But we had three constraints:

1. Single-server deployment

DealCraft runs on a single VPS (we're bootstrapping, not VC-funded). Adding Redis means another service to manage, monitor, and backup. We already have PostgreSQL — why add complexity?

2. Durability matters more than speed

Redis is in-memory. If the server crashes, you lose unprocessed jobs (unless you configure AOF persistence, which adds latency). For webhook processing, losing a job means losing an order's discount attribution. That's unacceptable.

3. We need idempotency at the database level

Shopify can send the same webhook multiple times. We need to guarantee that processing the same webhook twice doesn't create duplicate discount codes or double-count analytics. Redis queues don't give you this for free — you still need to implement deduplication logic.

PostgreSQL gives us all three: it's already running, it's durable by default, and we can enforce idempotency with unique constraints.

The Schema: Idempotency by Design

Here's the WebhookJob table:

model WebhookJob {
  id          String    @id @default(uuid())
  topic       String    @map("topic")
  shopId      String    @map("shop_id")
  shopDomain  String    @map("shop_domain")
  webhookId   String?   @map("webhook_id")
  payload     Json      @map("payload")
  status      String    @default("pending")  // pending | processing | completed | failed
  attempts    Int       @default(0)
  lastError   String?   @map("last_error")
  createdAt   DateTime  @default(now()) @map("created_at")
  updatedAt   DateTime  @updatedAt @map("updated_at")
  processedAt DateTime? @map("processed_at")
  retryAfter  DateTime? @map("retry_after")

  @@index([status, createdAt])
  @@index([status, updatedAt])
  @@unique([topic, shopId, webhookId])  // The magic line
  @@map("webhook_jobs")
}

That @@unique([topic, shopId, webhookId]) constraint is the key. Shopify sends an X-Shopify-Webhook-Id header with every webhook — a unique identifier for that specific event. By making [topic, shopId, webhookId] unique, the database itself prevents duplicate processing.

One caveat: webhookId is nullable (String?). In PostgreSQL, NULL != NULL in unique constraints, so rows with webhookId = NULL bypass deduplication. In practice, Shopify always sends the header for standard webhooks (ORDERS_CREATE, PRODUCTS_CREATE, etc.), so this only affects internally-generated events (like our custom FLOW:* topics). If you rely on this pattern, either make the field non-nullable or generate synthetic IDs for events that lack one.

If Shopify retries the same webhook (or sends it twice due to a network glitch), the second INSERT throws a P2002 unique constraint violation. We catch it and silently ignore it. No duplicate jobs. No complex deduplication logic in application code.

This is idempotency by schema design, not by application logic.

Security: HMAC Verification at the Edge

Before any of this queue logic runs, we need to verify the webhook actually came from Shopify. Every webhook endpoint in our app goes through authenticate.webhook(request) from the Shopify SDK, which validates the X-Shopify-Hmac-Sha256 header against the request body using our API secret. If the signature doesn't match, we return 401 before the payload ever touches our queue.

This is handled by the SDK so we don't have to think about it in every route — but it's worth understanding that the security boundary is at the HTTP edge, not inside the queue.

Enqueueing: Fire and Forget (Almost)

When a webhook arrives at our endpoint, we do this:

async function handleWebhook(topic: string, shopDomain: string, payload: any, webhookId: string) {
  const shop = await findShopByDomain(shopDomain);
  if (!shop) return;  // Unknown shop, ignore

  try {
    // Persist the job to the database
    await prisma.webhookJob.create({
      data: {
        topic,
        shopId: shop.id,
        shopDomain,
        webhookId,
        payload,
        status: "pending",
      },
    });

    // Trigger immediate consumption (non-blocking)
    setImmediate(() => consumeWebhookBatch(20));
  } catch (error) {
    if (error.code === "P2002") {
      // Duplicate webhook — already enqueued, ignore
      return;
    }
    // Database error — fall back to synchronous processing
    await dispatch(topic, shopDomain, payload);
  }
}

Three things to notice:

We persist first, then consume. The setImmediate is just an optimization — it triggers consumption immediately so the job doesn't wait for the next cron tick. But if setImmediate fails, the job is still in the database and will be picked up by the cron fallback. One caveat: if 50 webhooks arrive in rapid succession (bulk operations, flash sales), we fire 50 concurrent consumeWebhookBatch calls. CAS prevents duplicate processing, but each call still runs recoverWebhookJobs() and a findMany — wasted DB queries. In production, this hasn't been a problem at our scale (~100 jobs/min), but a debounce or advisory lock would be prudent at higher throughput.
We catch P2002 specifically. If the unique constraint fires, it means this webhook was already enqueued. We return silently — no error, no retry.
We have a fallback — with a narrow duplicate window. If the database is down (rare, but it happens), we fall back to synchronous dispatch(). This blocks the webhook response, but at least the business logic runs. Better to timeout than to lose the job entirely. The catch block doesn't just fire on "DB is down" — Prisma throws on connection pool exhaustion, network timeouts, and other errors. Some of these (like connection timeouts) may mean the INSERT actually succeeded but the response didn't reach us. In that case, the sync fallback processes the event and the persisted job will be consumed later — a duplicate. Our processors are idempotent by design (checking existing records before creating), so this window is tolerable. But it's worth understanding: the sync fallback is a last resort, not a safe path. It bypasses all queue protections (CAS, heartbeat, lease) and runs the full processing chain synchronously.

After enqueueing, we return 200 to Shopify immediately. Total time: ~50ms (one database INSERT). Shopify is happy.

CAS Claiming: The Heart of the Queue

Here's where it gets interesting. Multiple consumers might be running (we have a cron job that runs every minute, plus the setImmediate trigger). How do we prevent two consumers from processing the same job?

Compare-And-Swap (CAS) claiming.

async function consumeWebhookBatch(limit: number = 20) {
  // 1. Recover any crashed jobs (expired leases)
  await recoverWebhookJobs();

  // 2-3. CAS claim inside a transaction
  const claimedJobs = await prisma.$transaction(async (tx) => {
    // 2. Fetch pending jobs
    const pendingJobs = await tx.webhookJob.findMany({
      where: {
        status: "pending",
        attempts: { lt: MAX_ATTEMPTS },
      },
      orderBy: { createdAt: "asc" },
      take: limit,
    });

    const claimed: WebhookJob[] = [];

    // 3. Atomic claim per job
    for (const job of pendingJobs) {
      const result = await tx.webhookJob.updateMany({
        where: {
          id: job.id,
          status: "pending",
          attempts: job.attempts,  // The CAS token
        },
        data: {
          status: "processing",
          attempts: { increment: 1 },
          updatedAt: new Date(),
        },
      });

      if (result.count === 1) {
        // We successfully claimed this job
        claimed.push({ ...job, attempts: job.attempts + 1 });
      }
      // If count === 0, another consumer already claimed it — skip
    }
    return claimed;
  });

  // 4. Process claimed jobs
  for (const job of claimedJobs) {
    await processJob(job);
  }
}

The magic is in the updateMany WHERE clause: { id, status: "pending", attempts: job.attempts }.

id ensures we're updating the right job
status: "pending" ensures it hasn't been claimed yet
attempts: job.attempts is the CAS token — it's the generation number

When we read the job, attempts is, say, 0. We try to update it with attempts: 0 in the WHERE clause. If another consumer has already claimed it (incrementing attempts to 1), the WHERE clause won't match, and updateMany returns count: 0. We skip the job.

This is optimistic concurrency control — we assume the job is available, try to claim it, and back off if we're wrong. The SELECT and UPDATEs run inside a $transaction, which ensures they share the same database connection. But the real safety net is PostgreSQL's row-level locking: even without the transaction, each updateMany is individually atomic, and the CAS condition ensures only one consumer wins.

Lease Protection: What If the Consumer Crashes?

CAS claiming prevents duplicate processing, but what if a consumer crashes mid-processing? The job is stuck in status: "processing" forever.

Solution: lease-based expiration with heartbeat renewal.

const WEBHOOK_LEASE_MS = 5 * 60_000;  // 5 minutes
const WEBHOOK_HEARTBEAT_MS = 60_000;   // 1 minute

// After claiming a batch, start a heartbeat
const heartbeatTimer = setInterval(() => {
  renewHeartbeat(claimedJobs);
}, WEBHOOK_HEARTBEAT_MS);

heartbeatTimer.unref();  // Don't prevent process exit

async function renewHeartbeat(jobs: WebhookJob[]) {
  const owners = jobs.map(j => ({ id: j.id, attempts: j.attempts }));

  await prisma.webhookJob.updateMany({
    where: {
      status: "processing",
      updatedAt: { gt: new Date(Date.now() - WEBHOOK_LEASE_MS) },
      OR: owners,
    },
    data: {
      updatedAt: new Date(),
    },
  });
}

Every 60 seconds, we touch the updatedAt field on all outstanding jobs. This renews their lease.

If a consumer crashes, the heartbeat stops. After 5 minutes, the job's lease expires (updatedAt <= now - 5min). The next consumer's recoverWebhookJobs() call finds it and resets it to pending:

const MAX_ATTEMPTS = 3;
const RECOVER_LIMIT = 50;

async function recoverWebhookJobs() {
  const expiredWhere = {
    status: "processing",
    updatedAt: { lte: new Date(Date.now() - WEBHOOK_LEASE_MS) },
  };

  // Batch limit: recover at most 50 at a time to avoid overwhelming the consumer
  const expiredJobs = await prisma.webhookJob.findMany({
    where: expiredWhere,
    select: { id: true, attempts: true },
    take: RECOVER_LIMIT,
  });

  const failIds = expiredJobs
    .filter(j => j.attempts >= MAX_ATTEMPTS)
    .map(j => j.id);
  const requeueIds = expiredJobs
    .filter(j => j.attempts < MAX_ATTEMPTS)
    .map(j => j.id);

  if (failIds.length > 0) {
    await prisma.webhookJob.updateMany({
      where: { id: { in: failIds }, status: "processing" },
      data: {
        status: "failed",
        lastError: "Processing lease expired after maximum attempts",
        processedAt: new Date(),
      },
    });
  }

  if (requeueIds.length > 0) {
    await prisma.webhookJob.updateMany({
      where: { id: { in: requeueIds }, status: "processing" },
      data: {
        status: "pending",
        lastError: "Processing lease expired; retry pending",
        retryAfter: null,  // Clear any backoff timer
      },
    });
  }
}

This is eventual consistency for job processing. If a consumer crashes, the job is automatically requeued. No manual intervention.

The Pre-Dispatch Lease Check

There's one more edge case: what if the lease expires during processing, right before we try to update the job status?

Example:

Consumer A claims job (attempts: 1, status: processing)
Consumer A starts processing (takes 6 minutes due to slow Shopify API)
Consumer A's heartbeat hasn't fired yet (or the server is under load)
Consumer B's recoverWebhookJobs() sees the expired lease and resets the job to pending
Consumer B claims the job (attempts: 2, status: processing)
Consumer A finishes processing and tries to mark the job as completed

Now we have a race condition. Consumer A might overwrite Consumer B's work.

Solution: check the lease before every status transition.

async function processJob(job: WebhookJob) {
  const owner = { id: job.id, status: "processing", attempts: job.attempts };
  const activeOwner = () => ({
    ...owner,
    updatedAt: { gt: new Date(Date.now() - WEBHOOK_LEASE_MS) },
  });

  try {
    // Check lease before dispatching
    const leaseCheck = await prisma.webhookJob.updateMany({
      where: activeOwner(),
      data: { updatedAt: new Date() },  // Renew lease
    });

    if (leaseCheck.count !== 1) {
      // Lease lost — another consumer took over
      return;
    }

    // Dispatch to the appropriate handler
    await dispatch(job.topic, job.shopDomain, job.payload);

    // Mark as completed (with CAS + lease check)
    await prisma.webhookJob.updateMany({
      where: activeOwner(),
      data: {
        status: "completed",
        processedAt: new Date(),
      },
    });
  } catch (error) {
    // Handle failure (with CAS + lease check)
    await handleJobFailure(job, error);
  }
}

Every terminal state transition (completed, failed) includes the CAS token (attempts) and the lease check (updatedAt > now - 5min). If either fails, we back off. This prevents zombie consumers from corrupting state. The heartbeat and pre-dispatch check use lighter guards — they only need to confirm the lease hasn't expired, not enforce full CAS.

Retry Logic: Three Strikes with Exponential Backoff

When a job fails, we reset it to pending — but not for immediate retry. Hammering a failing API three times in rapid succession doesn't help anyone. Instead, we use exponential backoff via a retryAfter timestamp:

const BACKOFF_BASE_MS = 30_000;  // 30 seconds

// activeOwner() builds the WHERE clause for terminal state transitions:
// it combines the CAS token (attempts) with a lease check (updatedAt).
const owner = { id: job.id, status: "processing", attempts: job.attempts };
const activeOwner = () => ({
  ...owner,
  updatedAt: { gt: new Date(Date.now() - WEBHOOK_LEASE_MS) },
});

// In the failure handler:
const nextStatus = job.attempts >= MAX_ATTEMPTS ? "failed" : "pending";
const retryAfter = nextStatus === "pending"
  ? new Date(Date.now() + BACKOFF_BASE_MS * Math.pow(2, job.attempts - 1))
  : null;

await prisma.webhookJob.updateMany({
  where: activeOwner(),
  data: { status: nextStatus, lastError: errMsg, retryAfter },
});

The consumer skips jobs whose retryAfter is in the future:

const pending = await tx.webhookJob.findMany({
  where: {
    status: "pending",
    attempts: { lt: MAX_ATTEMPTS },
    OR: [
      { retryAfter: null },
      { retryAfter: { lte: new Date() } },
    ],
  },
  // ...
});

This gives us: 1st failure → 30s delay, 2nd failure → 60s delay, 3rd failure → dead-letter. Most transient errors (Shopify rate limits, temporary network issues) resolve within the first backoff window.

We use MAX_ATTEMPTS = 3. After 3 failures, the job is marked failed (dead-letter). An admin can inspect the lastError field and manually retry or investigate.

Why 3 attempts? Because most webhook failures are transient: Shopify API timeouts, network glitches, temporary rate limits. If it fails 3 times, it's probably a bug or a data issue that needs manual intervention.

The Dispatch Router

Once a job is claimed, we route it to the appropriate handler based on the topic:

async function dispatch(topic: string, shopDomain: string, payload: any) {
  switch (topic) {
    case "ORDERS_CREATE":
      await handleOrderCreate(shopDomain, payload);
      break;
    case "ORDERS_PAID":
      await handleOrderPaid(shopDomain, payload);
      break;
    case "PRODUCTS_CREATE":
      await handleProductCreate(shopDomain, payload);
      break;
    case "APP_SUBSCRIPTIONS_UPDATE":
      await billingService.handleSubscriptionUpdate(shopDomain, payload);
      break;
    case "FLOW:ABANDONED_CART":
      await handleAbandonedCart(shopDomain, payload);
      break;
    // ... 10+ more topics
    default:
      throw new Error(`Unknown webhook topic: ${topic}`);
  }
}

The ORDERS_CREATE handler is the most complex — it does discount attribution, analytics, loyalty points, post-purchase codes, and more. It takes 2-10 seconds. This is why we needed the queue in the first place.

Production Bugs That Taught Us Lessons

Bug 1: The Heartbeat That Didn't Unref

Symptom: The Node.js process wouldn't exit after processing webhooks. It hung forever.

Cause: The heartbeat setInterval was keeping the event loop alive. We forgot to call .unref() on the timer.

Fix:

const heartbeatTimer = setInterval(() => renewHeartbeat(jobs), WEBHOOK_HEARTBEAT_MS);
heartbeatTimer.unref();  // Allow process to exit

Bug 2: The Duplicate Post-Purchase Codes

Symptom: Some orders got two post-purchase discount codes instead of one.

Cause: The handleOrderCreate processor wasn't idempotent. If the job was retried (due to a transient error), it would create a second discount code.

Fix: We added an idempotency check — query existing RuleLog entries for the order, and skip already-logged rules:

const existingLogs = await prisma.ruleLog.findMany({
  where: { orderId: order.id },
});

const logsToCreate = allLogs.filter(
  log => !existingLogs.some(existing => existing.ruleId === log.ruleId)
);

if (logsToCreate.length > 0) {
  await prisma.ruleLog.createMany({
    data: logsToCreate,
    skipDuplicates: true,  // Belt and suspenders
  });
}

Bug 3: The Zombie Consumer

Symptom: Jobs were stuck in processing even though the consumer had crashed.

Cause: The consumer crashed before the heartbeat could renew the lease, and the recoverWebhookJobs() function wasn't being called frequently enough.

Fix: We call recoverWebhookJobs() at the start of every consumeWebhookBatch(), not just in the cron job. This ensures that crashed jobs are recovered immediately.

Performance: Is PostgreSQL Fast Enough?

Yes. Here are the numbers from our production deployment:

Enqueue latency: ~20ms (one INSERT)
Claim latency: ~50ms (one SELECT + N UPDATEs, where N ≤ 20)
Throughput: ~100 jobs/minute (limited by processing time, not queue overhead)
Table size: ~10,000 rows (we cleanup jobs older than 7 days)

The bottleneck is the processing logic (Shopify API calls), not the queue itself. PostgreSQL adds maybe 50ms of overhead per job — negligible compared to the 2-10 seconds of processing time.

When Would You Use Redis Instead?

Our PostgreSQL queue works great for a single-server deployment processing ~100 webhooks/minute. But there are scenarios where Redis would be better:

Multi-server deployment — If you have multiple app servers, Redis provides a centralized queue. PostgreSQL works, but you need to coordinate consumers across servers (which we do with CAS, but it's more complex).
High throughput — If you're processing 10,000+ jobs/second, Redis is faster (in-memory vs. disk).
Advanced features — Redis queues (Bull, BullMQ) give you priority queues, delayed jobs, rate limiting, and more out of the box.

For our use case (single server, ~100 jobs/minute, need durability and idempotency), PostgreSQL is the right choice.

The Takeaways

Idempotency by schema design — Use unique constraints to prevent duplicate processing, not application logic. Know the NULL caveat.
CAS claiming — Use a generation token (attempts) to prevent duplicate consumption. Each updateMany is individually atomic via PostgreSQL row-level locking; wrapping in $transaction shares the connection but isn't the safety net — the CAS condition is.
Lease-based expiration — Use updatedAt as a lease timestamp, with heartbeat renewal and automatic recovery. Batch-limit the recovery and guard updateMany with status: "processing" to prevent racing a concurrent completion.
Exponential backoff — Don't retry failures immediately. A retryAfter timestamp gives transient errors time to resolve without wasting attempts.
Fallback to synchronous — If the queue is unavailable, process synchronously as a last resort. Accept that the duplicate window is wider than the normal path (you can't distinguish "INSERT failed" from "INSERT succeeded but response timed out"). Make processors idempotent.
Beware implicit fan-out — setImmediate per webhook is fine at low volume, but creates concurrent consumer storms under burst traffic. Debounce or use an advisory lock if throughput grows.
PostgreSQL is good enough — For most use cases, you don't need Redis. PostgreSQL gives you durability, idempotency, and sufficient performance.

This post is based on our production experience building a Shopify app with TypeScript and Rust. If you're designing a webhook queue yourself, or have different takes on idempotency, CAS claiming, lease recovery, or exponential backoff, I'd love to hear your perspective in the comments.

5 Surprising Challenges Building a Shopify Discount Function in Rust

yuntongsoft — Mon, 05 Oct 2026 07:03:59 +0000

Most Shopify Function tutorials show you the happy path. Here's what actually broke during 3 months of building a production discount engine.

The Setup

I spent 3 months building DealCraft — a discount app that supports 12+ discount types (percentage, BOGO, volume, bundle, spend-tier, mix-and-match, etc.). The discount engine is a Rust Function compiled to WASM, running at Shopify's checkout. I chose Rust because the Function runtime demands it, and because I wanted the type safety for complex discount stacking logic.

The tech was straightforward. The edge cases weren't.

1. WASM Has No Clock

Our app supports time-windowed discounts — "10% off, valid from Oct 1 to Oct 7." Simple, right?

Except std::time::SystemTime::now() panics in Shopify's WASM runtime. There's no concept of "now" inside a Function.

The fix: Evaluate time conditions at sync time, not at checkout time. When the merchant saves a rule, the backend checks if the current time falls within the window. If not, the rule isn't written to the metafield at all. If it is, the time condition is "constant-folded" to true in the config JSON.

Merchant saves rule (Oct 1-7)
  → Backend checks: is now() within Oct 1-7?
  → No  → Don't write to metafield
  → Yes → Write rule with timeCondition: true (already satisfied)

The downside: if a rule's window starts while the Function is cached, it won't activate until the next sync. We handle this with two scheduled jobs — an hourly cron that auto-activates rules whose scheduledStart has arrived, and a 15-minute full sync that re-evaluates all shops as a safety net.

2. GraphQL Query Cost Almost Killed Us

Shopify Functions have a query complexity limit of 30. Our initial approach stored each discount rule as a separate metafield on the Shop object:

query {
  shop {
    rule1: metafield(namespace: "$app", key: "rule_1") { value }
    rule2: metafield(namespace: "$app", key: "rule_2") { value }
    # ... × 12 rules
  }
}

12 metafield lookups × 3 complexity each = 36 units. Rejected at deploy time.

The fix: Store all rules in a single Metaobject with a JSON field. One metaobject lookup costs 4 units (1 root + 3 for field(key)), well within budget. The metaobject also supports 128KB values, while metafields exceeding 10,000 bytes are not returned by the Function input query (the value is stored, but the Function receives null).

query {
  shop {
    rules: metaobject(handle: "dealcraft_rules") {
      field(key: "config") { value }
    }
  }
}

Lesson: Design your data model around query cost, not just data shape.

3. Discount Code + Automatic Discount Collision

Shopify has two discount mechanisms:

Discount codes — customer enters a code at checkout
Automatic discounts — applied by Functions without customer action

Our app creates automatic discounts via the Function. But merchants also create discount codes natively in Shopify. When a customer enters a code AND our Function has an automatic discount, who wins?

Shopify's default behavior: both apply. That's a merchant nightmare — double-dipping discounts.

The fix — "Strategy C": The Function reads the entered_discount_codes from the cart input and checks them against its own rule configurations. Each rule in the metafield carries a codes array — the discount codes associated with that rule. When a customer enters a code:

Code matches a rule the Function manages → The Function checks if the cart satisfies that rule's conditions AND not all lines are excluded. If both pass, the Function yields (returns empty) and lets the native discount code handle it. If either fails (cart doesn't qualify OR all lines are excluded), the Function rejects the code via EnteredDiscountCodesReject with a message like "This discount code is not valid for the items in your cart."
Code doesn't match any rule → The Function does NOT reject it. Instead, it simply suppresses its own automatic discounts and lets Shopify handle the entered code natively.

// Step 1: Validate entered codes — reject if cart doesn't qualify
for entered in &ctx.entered_codes {
    if !entered.rejectable { continue; }
    for rule in &rules {
        if rule.codes.is_empty() { continue; }
        if rule.codes.iter().any(|c| c.eq_ignore_ascii_case(&entered.code)) {
            let conditions_met = check_conditions(rule.conditions, ctx);
            let all_excluded = check_all_lines_excluded(rule, ctx);
            if !conditions_met || all_excluded {
                return reject_code(entered.code, "This discount code is not valid for the items in your cart");
            }
            break; // One code belongs to one rule
        }
    }
}

// Step 2: Match rules and calculate discounts...

// Step 3: If any discount code is entered, suppress automatic discounts
if ctx.has_discount_code {
    return Ok(empty_result());
}

This gives merchants one mental model: "DealCraft handles all discounts." Unknown codes pass through; known codes are validated against our rules.

4. A/B Testing Required Deterministic Hashing Across Two WASM Targets

We built A/B testing for discount rules — show 50% of customers a 10% discount, the other 50% a 15% discount. The split must be deterministic: same customer always sees the same variant.

The tricky part: our unified Function has two WASM export targets — cart_lines (product discounts) and delivery_options (free shipping). Both targets evaluate the same A/B test independently. If they hash differently, a customer could see 10% on products but 15% on shipping — a merchant nightmare.

Both targets share the same domain module, so the hash function itself is identical. But the inputs must also be identical. We use format!("{}{}", identity, anchor) where:

identity: customer ID for logged-in users, cart token for guests
anchor: min(rule.id, rule.ab_test_variant_id) — lexicographic minimum, ensuring both the control and variant rule compute the same hash seed

fn simple_hash(s: &str) -> i64 {
    let mut hash: i32 = 0;
    for cu in s.encode_utf16() {
        hash = hash
            .wrapping_shl(5)       // hash * 32 (mod 2^32)
            .wrapping_sub(hash)    // - hash = hash * 31 (mod 2^32)
            .wrapping_add(cu as i32);
    }
    (hash as i64).abs()
}

// Bucket assignment
let hash = simple_hash(&format!("{}{}", identity, anchor));
let bucket = (hash % 100) as u32;
let in_variant = bucket < rule.ab_test_split;

We use UTF-16 code units (encode_utf16() returns u16 values) rather than Rust's native UTF-8 bytes because the original prototype was in JavaScript (charCodeAt() returns UTF-16 code units). The compatibility is at the code unit level — both produce the same u16 values for the same characters. The i32 accumulator with wrapping_shl(5).wrapping_sub(hash) is the classic Java string hash (hash * 31 + codeUnit), chosen specifically because it's what the JS prototype used. The wrapping_* operations ensure overflow behavior matches JavaScript's silent wraparound (though JS uses floating-point, the integer results are equivalent for typical string lengths).

The key lesson: when you have multiple evaluation points for the same decision, "same function" isn't enough. The inputs must also be guaranteed identical. The anchor = min(id, variant_id) trick ensures that regardless of which rule (control or variant) is evaluating, the hash seed is the same.

5. Free Shipping Has Different Exclusion Semantics

Our unified Function handles both cart discounts and free shipping in a single WASM binary (two export targets, shared domain logic). But exclusion rules behave differently:

Cart discount: If product A is excluded, only product A is removed from the discount. Other products still get discounted.
Free shipping: If ANY product in the cart is excluded, the entire free shipping discount is voided.

Why? Because delivery groups can't be split per-line. You either get free shipping on the whole order or you don't.

Concrete example: Cart has products A, B, C. Product A is excluded from the discount.

Cart discount: A is removed, B and C still get 10% off
Free shipping: Entire discount voided because A is in the cart

This meant the same exclusion config produced different outcomes depending on the target. We had to add a strict_exclusion flag in the domain module:

fn check_exclusions(lines: &[Line], excluded_ids: &[String], strict: bool) -> bool {
    if strict {
        // Free shipping: any excluded line → block entire discount
        !lines.iter().any(|l| excluded_ids.contains(&l.product_id))
    } else {
        // Cart discount: filter out excluded lines, discount the rest
        true // always pass; filtering happens downstream
    }
}

Small difference, massive debugging session.

What I'd Do Differently

Looking back:

Start with query cost analysis — before writing a single line of Rust, calculate your GraphQL query complexity. We lost a week redesigning our data model after the first deploy failed.
Test with edge cases from day one — our best bug finds came from real carts with discount codes + automatic discounts + excluded products all at once. Unit tests missed these interactions.
Unify early — the separate free-shipping Function was a mistake. Maintaining two WASM binaries with shared logic was harder than one binary with two targets.

If you're building Shopify Functions, what edge cases have you hit? I'm especially curious about how others handle the query cost limit — did you find creative solutions beyond metaobjects?