DEV Community: Eli

Your variant has one image, your product has twenty — the Shopify gallery filter question, finally answered

Eli — Wed, 05 Aug 2026 13:34:15 +0000

I found this one in a Shopify Community thread that collected 13 posts in 24 hours and still has no accepted answer. A merchant on the Horizon theme asked the question store owners have asked for a decade: when a shopper picks Black, show only the black images — no paid app, no Plus.

The thread is a museum of every classic wrong answer: a layout setting sold as filtering, the one-image-per-variant confusion, a "send me your store URL" service pitch, and a working code snippet the OP couldn't get running. I've watched this question get half-answered for years, so here's the whole picture — including why the "correct" code so often "doesn't work."

Root cause: two things that look alike

Shopify's data model gives you two different things:

A variant can carry its own media — variant.featured_image / variant.featured_media in Liquid, ProductVariant.media in the Admin GraphQL API. This is what you set when you assign an image to a variant in the admin. Exactly one is "featured," and themes (Horizon included) swap it into the main gallery slot on selection. Native, free, every plan.
The product's media set — product.media — is a flat pool shared by all variants. Any image not assigned to a variant belongs to every color simultaneously. There is no native structure for "these five images belong to Black."

So "show only the selected variant's images" is two different problems:

Case	What you want	Native support
A	One representative image per color, swapped on selection	Yes — variant featured image, every theme
B	A gallery per color (3–8 shots each), filtered on selection	No — not in the data model, not a Horizon setting

If you're in Case A, stop here: assign each variant's featured image in Products → your product → Variants. On Horizon, additionally enable "Hide other variants' media after selecting a variant" in the Media Gallery block settings (field report, community-verified by three independent posters in topic 659928 — it hides down to the one assigned image per variant, not a multi-image set).

Everything below is Case B.

Minimal reproduction

Five minutes on a dev store:

Create a product "Test Tee", option Color: Black, White.
Upload 6 images: 3 black, 3 white. Assign the first black image as Black's featured image, first white as White's.
Publish with Horizon, Media Gallery in grid mode (the default).
Select Black on the storefront: the main image swaps — and the other 5 images, including all 3 white shots, stay in the gallery. Select White: same in reverse.

That's the ceiling of native behavior. No toggle changes it.

Route 1 — Alt-text tagging + gallery filter (free, code, no app)

Tag every color image with its color in Alt text (Products → product → click image → Alt text → Black, White, …; leave shared images like size charts untagged). Then filter the gallery on the selected option value, in a Custom Liquid block or section on the product template:

{% assign current_variant = product.selected_or_first_available_variant %}
{% assign selected_color = current_variant.options.first %}

{% for media in product.media %}
  {% if media.media_type == 'image' %}
    {% if media.alt == blank or media.alt == selected_color %}
      <img
        src="{{ media | image_url: width: 800 }}"
        alt="{{ media.alt | escape }}"
        loading="lazy">
    {% endif %}
  {% endif %}
{% endfor %}

The notes that make or break this in production:

product.media filtered with where: 'media_type', 'image' is the documented pattern; media.alt is the string you typed in the admin. Both documented.
Alt text must match the option value exactly — Black ≠ black ≠ Black (trailing space). This, plus browser cache, is why the OP reported the community code "not working."
The snippet filters on first render only. Switching colors is a client-side event — you need a small JS listener on the variant picker that re-filters (or hides/shows) gallery items without a reload. This is the half people paste-and-pray without.
Untagged images stay visible for every color — exactly what you want for size charts and lifestyle shots.
This approach was tested on a live Horizon store (grid layout) with before/after screenshots in the thread; the untagged size chart correctly persisted across colors.

Route 2 — Shopify Combined Listings (free, first-party, Plus only)

If each color deserves its own full media set — and its own URL for ads and SEO — the first-party answer is Combined Listings: each color is a separate product with its own images, and the combined listing displays all child products on one product page. Zero code. The catch is hard: Combined Listings are available only to stores on a Shopify Plus plan (shopify.dev, verified 2026-08-05). For the OP, who excluded both apps and Plus, this route is out — but it's the correct answer for Plus stores, and worth knowing before you write any Liquid.

Route 3 — Apps

Exist, work, out of scope: the constraint was "no paid app," and Routes 1–2 cover the free space completely.

Decision tree

One image per color?            → Variant featured image (+ Horizon's
                                  "hide other variants' media" toggle). Done.
Multiple images per color?
  ├─ On Plus?                   → Combined Listings. No code.
  └─ Not on Plus?               → Alt-text tagging + Custom Liquid/JS filter.
                                   Match alt text to option names exactly.

Checklist

Decide your case first: one image per color (native) vs. a gallery per color (code or Plus).
Case A: assign each variant's featured image; on Horizon, enable "Hide other variants' media" in the Media Gallery block.
Case B, Route 1: tag every color image's Alt text with the exact option value (case, spelling, trailing spaces).
Filter product.media by media_type == 'image' and media.alt == selected_color; leave media.alt == blank items visible for shared shots.
Add the JS listener on variant change — server-rendered Liquid only filters the first paint.
Test on grid and carousel; the layout setting changes markup, not filtering.
Hard-refresh / incognito before concluding "the code doesn't work" — stale cached HTML is the #1 false negative.
On Plus? Skip all of it: Combined Listings gives each color its own product and media set, natively.

Community thread content (the Horizon "Hide other variants' media" setting, the tested alt-text solution, the OP's failed implementation) is a field report from Shopify Community topic 659928; every load-bearing technical claim is verified against Shopify's official documentation (Liquid variant.featured_image/featured_media, media.alt, product.media where-filter, Admin GraphQL ProductVariant.media, Combined Listings) as of 2026-08-05.

Originally published at https://clawmama.run/blog/shopify-horizon-variant-media-filter/

Google kept rejecting a bookstore's print listings — because the ebook was still buyable on the same URL

Eli — Wed, 05 Aug 2026 13:32:57 +0000

I stumbled onto this one in a Shopify Community thread that had 13 answers and no accepted one. A book publisher sells every title in three formats — print, ebook, audiobook. They did what every feed management app tells you to do: exclude every digital edition from the Google Merchant Center data source. And Google's automated review kept rejecting their print book listings anyway.

I've seen "just filter the feed" handed out as the complete answer to this problem for years, so I dug into why it wasn't working. The reason is structural, and it's documented — just not in one place. Here's the whole picture.

The structural fact that explains everything

One respondent in the thread (dropfeed) actually audited the merchant's catalog: 423 of the store's 480 products carry a single Format option with Audiobook, Ebook, Paperback and Hardcover as variants of one product. All four formats share one URL and one item group.

Hold that fact next to three documented ones:

Google's Shopping policies don't support ebooks. The "Unsupported Shopping content" policy lists "eBooks and digital books (not including audiobooks)" — PDFs, ePub, MOBI — as content that cannot be promoted.
Google evaluates the landing page, not just the feed. The landing page requirements: when your page contains multiple products "such as variants", the product in your product data must be the primary focus and the price must match. The link attribute doc: one link per product or product variant. And Google's structured data docs show variants are addressed by preselecting via URL parameters (?size=small&color=green).
On the submitted URL, the ebook is still buyable. Ebook and audiobook are variants of the same Shopify product, so the print URL renders one Add to Cart form whose Format picker lets anyone select — and purchase — a digital edition.

The thread converged on a precise dividing line (field report, but consistent with the policy pages):

Allowed: mentioning "also available as ebook and audiobook" in the product copy. Text is not an offer.
Rejected: ebook/audiobook as selectable, purchasable variants in the Add to Cart form on the submitted URL.

That's why filtering the feed changed nothing: the merchant cleaned the data Google reads, not the page Google visits. Preselecting the paperback variant doesn't fix it either — the digital options are still one click away in the same form, still purchasable, same URL.

A quieter amplifier: if your product page emits JSON-LD offers for the digital variants (many themes and apps do), crawlers read the ebook as an offer even where a human sees only a dropdown. Google's ProductGroup pattern (hasVariant, variesBy, productGroupID) is correct markup for genuine multi-format pages — and a liability when some variants are unsupported content.

Minimal reproduction (no Google required)

The failure is structural and visible in Liquid on any dev store:

Create one product, dune, with option Format: Paperback ($18, requires shipping), Ebook ($9, digital), Audiobook ($15, digital).
Exclude the digital variants from your Google feed by whatever method you like.
Open the product URL with the paperback preselected: /products/dune?variant=<paperback_variant_id>.
View source. The Add to Cart form posts a variant id, and the Format selector still contains all three options. Any crawler sees three purchasable offers — two of them digital — on the submitted URL.

Feed-side exclusion verified; landing-side exposure intact.

Route A — Split the formats into separate products (the structural fix)

Print, ebook, and audiobook become separate Shopify products. Publish only the print products to Google surfaces; keep the digital products on the storefront, linked from the print page as text ("Also available as ebook / audiobook"). The submitted print URL offers only physical formats — exactly what passes review.

The merchant's objection is real: this multiplies the catalog 3-4x. Mitigations exist but don't eliminate the cost — bulk editors, metafield-driven cross-links, and for programmatic control the Admin GraphQL API (publicationCreate publishes a product to a channel; channel availability is product-level, and tags/metafields alone do not control sync).

Route B — Proxy page: a physical-only offer page per title (the theme fix)

Keep the variant structure. Create an alternate page template that renders only the physical variants of a given product, and submit those proxy URLs to Google. Shopify theme architecture supports alternate templates, and Liquid gives full markup control. Pull the product with all_products['your-handle'] and filter variants by requires_shipping — true for physical goods, false for digital ones:

{%- comment -%} templates/page.print-proxy.liquid {%- endcomment -%}
{%- assign book = all_products['dune'] -%}

<h1>{{ book.title }} — Print edition</h1>

<form method="post" action="/cart/add">
  <label for="fmt">Format</label>
  <select id="fmt" name="id">
    {%- for variant in book.variants -%}
      {%- if variant.requires_shipping -%}
        <option value="{{ variant.id }}">
          {{ variant.title }} — {{ variant.price | money }}
        </option>
      {%- endif -%}
    {%- endfor -%}
  </select>
  <button type="submit">Add to cart</button>
</form>

Mapped to the requirements:

The proxy URL's only purchasable options are physical. The offer on the page matches the submitted offer.
One product, one clean URL to submit as the link — Google wants exactly one link per product or variant.
Digital editions stay on sale at the canonical product URL, linked as text — copy, not an offer.

Two documented constraints:

all_products resolves at most 20 unique handles per page. One proxy page per title is fine; proxying a whole catalog from one page is not — use collections or one page per handle.
Keep the proxy page's JSON-LD honest: emit structured data only for the physical offers on the page; don't list digital variants as offers on the proxy URL. When you submit variant URLs elsewhere, preselect via URL parameters so price/availability match.

More template work than Route A, but the catalog survives.

Route C — GMC attribute rules with `excluded_destination` (the feed-hygiene fix)

Worth doing regardless of the structural route. In Merchant Center, "feed rules" are now called attribute rules (Google renamed them). Add a rule on your data source that sets excluded_destination when the title matches digital markers (e.g. "title contains ebook"), excluding from Shopping ads, free listings, display, etc. The attribute is documented precisely for preventing a product from appearing in chosen destinations.

What it does and doesn't:

Does: guarantee no digital SKU is ever submitted, even if your sync app misbehaves or a new digital product is added without tags.
Does not: change what a crawler finds on a shared-format product URL. Necessary hygiene, not a cure.

On sync: the Google & YouTube app syncs Shopify product data to Merchant Center automatically or manually — attribute rules sit after the data arrives, which is why they catch what channel-side visibility settings miss.

Checklist

Inventory: which products mix physical + digital formats as variants of one product? (The merchant's audit: 423 of 480.)
Classify every digital format against Google's Unsupported Shopping content list — ebooks explicitly listed; audiobooks explicitly not in that entry, but treat any instant-download good as suspect until verified.
Confirm the failure mode first: does the submitted URL offer digital formats for purchase? If yes, feed filtering alone can't clear the rejection.
Pick the structural route: split products (A) or proxy pages with requires_shipping-filtered forms (B). Text mentions can stay; purchasable selectors cannot.
Add GMC attribute rules setting excluded_destination on digital markers as a safety net regardless.
Audit JSON-LD on submitted URLs: emit only offers that are purchasable and supported; keep digital variants out of the proxy page's markup.
Submit one link per product/variant; preselect variant URLs via parameters so price and availability match.
After fixing, request a review on the affected items and watch for re-disapproval.

The community thread content (catalog audit, the "purchasable variant" diagnosis, the proxy-page suggestion, the attribute-rules recipe) is a field report from Shopify Community topic 658986; every load-bearing technical claim above is verified against Google and Shopify documentation (Unsupported Shopping content policy, landing page requirements, link/excluded_destination attributes, attribute rules, product-variant structured data, Liquid all_products/variant, theme templates, Admin GraphQL publicationCreate — latest stable 2026-07).

Originally published at https://clawmama.run/blog/shopify-gmc-format-variant-rejection/

A merchant asked for B2B subscriptions — so I read the schema and found the wall

Eli — Mon, 03 Aug 2026 13:32:25 +0000

This one started with a community thread I couldn't stop thinking about: a pure-B2B merchant — no D2C checkout at all, ~200k SKUs, selling maintenance bundles — wanted to sell those bundles as quarterly subscriptions. The only answer the thread produced was "make a draft order every month by hand." I've seen that advice given out for years, so I went to check whether it even works at the API level. It doesn't — and the reason is written down in Shopify's own docs. Here is the wall, and the three doors around it.

Root cause: a one-sentence wall

Shopify's B2B developer documentation states it in the Limitations section:

"B2B doesn't support purchase options, such as subscriptions, pre-orders, and try before you buy."

"Purchase options" is the umbrella term, and subscriptions are implemented through selling plans: a SellingPlan defines how a product can be sold and purchased through recurring billing — when to bill, when to fulfill, what pricing adjustments to apply — and a SellingPlanGroup attaches those plans to products and variants. No purchase options in B2B means no selling plans in the B2B checkout, which means no SubscriptionContract — the object that defines recurring purchases for a customer and tracks billing attempts, payment status, and generated orders — is ever born there.

Why "use a draft order" fails at the API level

Draft orders are the standard B2B instrument: the API lets you create draft orders for company contacts to review and approve, attach paymentTerms, send an invoiceUrl. So the community reflex is "sell the subscription through a draft order."

Open the Admin GraphQL reference for DraftOrder and DraftOrderLineItem (latest stable, 2026-07) and read the full field list: there is no selling-plan field anywhere — not on the draft order, not on its line items. You cannot smuggle a selling plan through a draft order, so a draft order cannot create a subscription contract either. The wall has no cracks on this side.

Minimal reproduction

You don't need a Plus sandbox to confirm the wall; you need the schema. Run an introspection query against any store's Admin GraphQL API:

{
  draftLineItem: __type(name: "DraftOrderLineItem") {
    fields { name }
  }
  draftOrder: __type(name: "DraftOrder") {
    fields { name }
  }
}

Grep the result for sellingPlan: zero hits on either type, matching the published object reference. What you will find on DraftOrder are the B2B-native fields: paymentTerms, purchasingEntity, invoiceUrl, and the deposit-aware totals (amountDueNowSet / amountDueLaterSet — when payment terms exist, "due now" is the deposit and "due later" is the remainder).

Two checks, five minutes, wall confirmed from primary sources.

Door 1 — the D2C lane (no app required)

The B2B object model has a built-in escape hatch: a company contact is associated with a retail customer record. That customer record can buy through the normal online-store checkout, where purchase options are supported. So the subscription is sold on the D2C lane to the contact's customer account, while the rest of the relationship stays B2B.

The trade-offs are real: that subscription order won't carry B2B catalog pricing, won't inherit payment terms, and won't roll up into company-level reporting. For a pure-B2B merchant it's a compromise lane, not a native feature.

Door 2 — the API door: build the contract without checkout

Here's the part almost nobody mentions: a subscription contract does not have to be born at checkout. The Admin GraphQL API exposes subscriptionContractCreate, which — per the reference — "creates a subscription contract draft, which is an intention to create a new subscription." You supply the customer, a customer payment method, and billing/delivery policies; you then finalize with subscriptionDraftCommit. No storefront involved:

# Adapted from the official mutation example (API version 2026-07)
mutation createSubscriptionContract($input: SubscriptionContractCreateInput!) {
  subscriptionContractCreate(input: $input) {
    draft { id }
    userErrors { field message }
  }
}

{
  "input": {
    "customerId": "gid://shopify/Customer/544365967",
    "currencyCode": "USD",
    "nextBillingDate": "2026-09-01T09:00:00Z",
    "contract": {
      "status": "ACTIVE",
      "paymentMethodId": "gid://shopify/CustomerPaymentMethod/b7cc6e3267aace169e516ed48be72dff",
      "billingPolicy": { "minCycles": 3, "maxCycles": 12, "intervalCount": 1, "interval": "MONTH" },
      "deliveryPolicy": { "intervalCount": 1, "interval": "MONTH" }
    }
  }
}

Once the draft commits, the contract exists. Billing then runs through subscriptionBillingAttemptCreate, which charges the contract for the current (or a selected) billing cycle and creates an Order on success; failed attempts expose a processingError, and the idempotencyKey argument exists specifically to prevent duplicate charges on retries.

The fine print, all verifiable in the reference:

Both mutations require the write_own_subscription_contracts access scope, and the acting user needs the manage_orders_information permission.
The contract's customerPaymentMethod must already exist — vaulting a card is a separate problem the API doesn't solve for you.
The contract belongs to the customer, not the company. B2B pricing, terms, and reporting still don't apply.
Selling plans and their associated records are automatically deleted 48 hours after the merchant uninstalls the app that created them — if you build on this, back those records up.

Door 3 — emulate recurrence with native B2B primitives

If "real subscriptions" are impossible but "recurring charges on a schedule" is the actual business need, the native building blocks are draft orders with paymentTerms: deposit semantics via amountDueNowSet/amountDueLaterSet, an invoiceUrl to collect payment, and company association via purchasingEntity. You generate the recurring draft orders on a schedule (your own automation) instead of a billing policy doing it.

A community contributor on the same thread described one concrete assembly of this — vaulting a B2B customer's card and using Shopify Flow's payment-schedule trigger with a "charge vaulted payment" action to automate the collection. I flag that specific assembly as a field report: it's practitioner testimony from the thread, not something re-verified line-by-line in the merchant documentation, so treat the exact trigger/action names as "confirm in your own admin" rather than gospel.

Checklist

Accept the wall: B2B doesn't support purchase options (subscriptions, pre-orders, try before you buy) — it's documented, not a bug.
Stop trying to attach selling plans to draft orders: neither DraftOrder nor DraftOrderLineItem has a selling-plan field in the Admin GraphQL API.
Decide what the business actually needs: contract semantics (Door 2), or just recurring collection (Door 3 / Door 1).
Door 1: route the subscription through the contact's retail customer record on the D2C checkout; document that B2B pricing/terms/reporting don't apply.
Door 2: use subscriptionContractCreate → subscriptionDraftCommit → subscriptionBillingAttemptCreate; confirm write_own_subscription_contracts scope + manage_orders_information permission; solve card vaulting first; back up selling-plan data against the 48-hour uninstall deletion rule.
Door 3: model recurrence with draft orders + paymentTerms + invoice collection; treat community Flow recipes as field reports to verify in your own admin.
Whatever you build: a subscription order created outside B2B will not appear in company-level B2B reporting — set stakeholder expectations in writing.

Originally published at https://clawmama.run/blog/shopify-b2b-subscription-gap/

Your AI fortune teller was making things up — so we took the math away from the model

Eli — Mon, 03 Aug 2026 11:55:51 +0000

A few weeks ago I bookmarked a viral post: "5 fortune-telling Skills on GitHub you should save." BaZi, ZiWei, QiMen, Tarot — thousands of stars combined. I bookmarked it too. And like most people, I never got past the bookmark.

When I finally dug in, I found a problem worse than setup friction: AI fortune-telling fails on the chart itself.

The chart is math, not prose

A BaZi "Four Pillars" chart or a ZiWei star map is deterministic calculation — dense rules, zero room for vibes. Ask a model to compute a chart from memory and it will get the day pillar wrong, then write you a gorgeous, confident, completely wrong reading.

Experts spot it immediately. Everyone else gets misled beautifully.

The projects that got it right

The most interesting repos in this wave take calculation away from the model:

TaiBu (github.com/hhszzzz/taibu) — fifteen local divination engines: BaZi, ZiWei, LiuYao, MeiHua, QiMen, Tarot, Western astrology, Chinese almanac. Charts are computed by a bundled engine; the model interprets, never calculates.
BaZi Skill (github.com/jinchenma94/bazi-skill) — interpretation rules distilled from nine classical texts into a structured framework.
Mingyu (github.com/Brhiza/mingyu) — chart workflows plus a public API that turns charts into AI-readable structured data.

What we built

We packaged these three into one ready-to-use Agent. You ask in plain language — "born May 20, 1990, 8 AM" — the Agent runs the real engines, then interprets the verified chart with classical rules.

I tested it with a known birth input: the computed pillars matched manual cross-checking exactly (Geng-Wu year, Xin-Si month, Yi-You day, Geng-Chen hour). That's the bar: the reading can be subjective, the chart cannot.

If you're building anything in the AI-metaphysics space, steal this architecture: deterministic engine for facts, model for interpretation, and never let the two trade places.

Try it: Fortune Reading Agent on ClawMama — one click, then chat with it in Telegram, WhatsApp or Discord.

Originally published at https://clawmama.run/blog/fortune-reading-agent

I gave my AI coding assistant a design degree (one skill, 875 likes later)

Eli — Mon, 03 Aug 2026 06:03:38 +0000

I asked my AI coding assistant to make a poster about "a rainy old bookstore." What I got was a book icon, some rain drops, and the visual charm of a school newsletter. That's when I went down the rabbit hole of why AI-generated visuals feel so... generic.

The gap isn't technical — it's aesthetic

AI coding assistants like Codex can place elements on a canvas all day long. What they can't do is tell you why one composition feels "quiet" and "premium" while another feels like clip art. Standard models don't carry a design system in their heads. The gap isn't compute — it's aesthetic literacy.

Someone decomposed "zine style" into executable rules

gc-minimal-zine-poster is an open-source Codex skill that encodes a complete zine visual language. Instead of asking for "a poster," you invoke a design system:

# Install
git clone https://github.com/LiamGvchi/gc-minimal-zine-poster.git \
  ~/.codex/skills/gc-minimal-zine-poster-v0-1

# Restart Codex, then use
$gc-minimal-zine-poster-v0-1 "a rainy old bookstore"

The skill decomposes "zine style" into four axes:

Composition: asymmetric balance, generous white space
Typography: handwritten or serif fonts, mixed scales
Color: muted palettes, single accent color
Texture: paper grain, subtle noise

Does it work?

The original author (@BTCqzy1 on X) posted a poster series made with it — 875 likes, ~50k views. Same one-sentence prompt, completely different output: intentional, gallery-worthy visuals instead of generic icons.

If your AI-generated visuals keep coming out soulless, the fix might not be a better prompt. It might be giving the model a design vocabulary it never had.

Originally published at https://clawmama.run/blog/gc-minimal-zine-poster

Our bundle math was wrong because Shopify rejected our cart transform — and then leaked a price

Eli — Sun, 02 Aug 2026 09:15:08 +0000

We found this one the way you always find the good ones: a community bug report that made us drop everything and go check our own function logs. A developer building a bundle app posted that when the same variant sits in the cart twice — once as a subscription line, once as a normal line — the normal line shows up in the Function input with the selling-plan price in cost.subtotalAmount. Their bundle math, computed from that cost, came out wrong. We run the same architecture in production. Here is the wall, the leak, and the defensive input handling that makes your math survive either way.

Wall #1: selling plans hard-reject Cart Transform operations

The Cart Transform API reference is unusually blunt about this. Under Invalid scenarios:

"Shopify rejects lineExpand, linesMerge, and lineUpdate operations if a selling plan is present."

The rejection is not scoped to the selling-plan line: if a selling plan is present, the operations are rejected. The surface-compatibility table on the same page draws the rest of the wall:

Cart: Supported. B2B: Supported. Draft orders: Supported.
Checkout: Partially supported — that footnote is the selling-plan rejection.
Subscription (Recurring Orders): Not supported.
Order Edit, Create Order API, Pre-order / Try Before You Buy: Not supported.

Two more constraints from the same page shape any bundle architecture:

One cart transform function per app per store; but if several apps each install one, all of them run. Your operations share the cart with every other bundle or upsell app the merchant installed.
lineUpdate requires a development store or Shopify Plus. On non-Plus production stores, expand and merge are what you have.

So the split isn't a style choice. It's the only architecture the platform permits:

Bundle type	Function	Why
One-time bundle	Cart Transform (`lineExpand` / `linesMerge`)	Native bundle UX; price presentation handled by the API
Subscription bundle	Discount function (`cart.lines.discounts.generate.run`)	Cart Transform rejects everything once a selling plan exists

The documented execution order makes this workable: Cart Transform runs first (step 1: cart lines); Discount functions run after (steps 2 and 5). Your discount logic sees the cart after the transform has expanded or merged it, which is exactly what you want for subscription bundles priced off component sums.

Wall #2: the price that leaks through

The community field report (topic 657784; flag this as unconfirmed platform behavior, since the docs define nothing here):

Same variant in the cart twice: line A with a selling plan, line B without. In the Function input, line B's cost.subtotalAmount reflects the selling-plan price, not the variant's regular price. Bundle calculations that trust cost are corrupted.

Whether this is a bug that gets fixed next quarter or a permanent edge of variant-level price resolution, the lesson generalizes: Function input is data crossing a trust boundary. Treat it like an API response, not like truth.

What the docs do define, on the cart-line input fields:

cost.subtotalAmount — "the cost of items in the cart before applying any discounts." Variant-priced.
cost.amountPerQuantity — the unit cost.
sellingPlanAllocation — present on lines that carry a selling plan, with priceAdjustments and perDeliveryPrice (the docs' own example: 6 deliveries at $48.00 → $8.00 per delivery).

If a line has a selling-plan price, the documented place to read it is sellingPlanAllocation, not cost. And the documented way to know a line is a subscription line is that sellingPlanAllocation exists on it.

The defensive pattern: composite keys, not variant IDs

The root mistake in most bundle math we've audited (including, briefly, our own) is grouping cart lines by variant.id alone. A variant is not a purchasable identity in the cart — a variant plus a selling-plan context is. Once you internalize that, the fix is mechanical:

# run.graphql — query the fields that disambiguate lines, not just prices
query Input {
  cart {
    lines {
      id
      quantity
      sellingPlanAllocation {
        sellingPlan { id }
        perDeliveryPrice { amount currencyCode }
        priceAdjustments { price { amount } }
      }
      cost {
        amountPerQuantity { amount currencyCode }
        subtotalAmount { amount currencyCode }
      }
      merchandise {
        __typename
        ... on ProductVariant { id title }
      }
      bundleOffer: attribute(key: "_bundleOfferId") { value }
    }
  }
}

// Group by (variant, sellingPlan) — never by variant alone.
function lineKey(line) {
  const variantId =
    line.merchandise.__typename === "ProductVariant" ? line.merchandise.id : "none";
  const planId = line.sellingPlanAllocation?.sellingPlan?.id ?? "onetime";
  return `${variantId}::${planId}`;
}

function effectiveUnitPrice(line) {
  // Documented source of truth for subscription pricing:
  if (line.sellingPlanAllocation) {
    return parseFloat(line.sellingPlanAllocation.perDeliveryPrice.amount);
  }
  // One-time lines only: never mix the two pools.
  return parseFloat(line.cost.amountPerQuantity.amount);
}

Three rules fall out of this:

1. Never aggregate across the selling-plan boundary. A bundle offer's lines must all come from the same key bucket. If your offer spans both, that's two offers.

2. Read subscription prices from sellingPlanAllocation. If the leaked-price behavior in the field report is real, this is immune to it — you never read cost on a subscription line, and you never let a subscription line's price contaminate a one-time line's bucket.

3. Keep the input query small. The input query is fixed at build time: max 3,000 bytes excluding comments, max calculated query cost 30, list arguments capped at 100 elements. Runtime-changing config belongs in a metafield JSON blob — under 10,000 bytes, because larger values come back absent, not truncated.

One more warning from Shopify's own bundle guide: line-item properties "can be modified by the browser, so they should not be relied upon for security or validation purposes." Properties like _bundleOfferId are fine as routing hints; the authoritative bundle definition belongs in metafields your app owns.

Minimal reproduction

In a dev store:

Create a selling plan group and attach it to variant V. Create a one-time bundle offer and a subscription bundle offer, both containing V.
Add V to the cart twice: once with the selling plan, once without.
Attempt a lineExpand or linesMerge from your Cart Transform: observe the rejection — the documented behavior — because a selling plan is present.
In your Discount function, log cart.lines[*].cost.subtotalAmount for the one-time line of V and compare it against V's regular price. If the field report still reproduces, the one-time line shows the selling-plan price. With composite-key grouping, your math is unaffected either way.

Step 3 is documented fact. Step 4 is the field report: log it and see.

The numbers worth pinning above your desk

Selling plan present ⇒ lineExpand, linesMerge, lineUpdate rejected; subscriptions not supported by Cart Transform at all.
Execution order: Cart Transform (1) → Discounts (2, 5). Discounts see the transformed cart.
One cart transform per app per store; multiple apps' transforms all run.
lineUpdate: dev stores and Plus only.
Bundle limits from the guide: 150 components, 3 options, no nested bundles; only the owning app manages a bundle's components.
Input query: 3,000 bytes, cost 30, lists ≤ 100 elements; config metafields over 10,000 bytes return nothing.
Group cart lines by (variant, sellingPlan); read subscription prices from sellingPlanAllocation.perDeliveryPrice, never cost.

Originally published at https://clawmama.run/blog/shopify-cart-transform-selling-plan/

I found out why our Shopify filters were missing options: the 1,000-tag ceiling

Eli — Sun, 02 Aug 2026 01:30:40 +0000

We ran a Shopify store that used product tags for everything — color, material, occasion, audience — and the theme rendered the collection filter UI from the collection's tags. Then a merchant report came in: filter options were missing, and the products behind them were unfindable by filtering. Nothing had errored, anywhere. Tracking down why led to one line in Shopify's own Liquid reference that almost nobody reads until it's too late.

Turns out we're not alone: in the Shopify Community thread that prompted this write-up, three independent experts converged on the same answer.

Root cause #1: collection.all_tags is hard-capped at 1,000

The classic tag-filter pattern looks like this (per Shopify's own tag-filtering docs, you loop the collection's tags and build add/remove links from current_tags):

{% comment %} sections/main-collection.liquid — the classic tag filter UI {% endcomment %}
<ul class="tag-filters">
  {% for tag in collection.all_tags %}
    <li>
      {% if current_tags contains tag %}
        {{ tag | link_to_remove_tag: tag }}
      {% else %}
        {{ tag | link_to_add_tag: tag }}
      {% endif %}
    </li>
  {% endfor %}
</ul>

Here is the part nobody reads until it's too late: the Liquid reference for the collection object states that all_tags returns a maximum of 1,000 tags. Not a soft limit, not a pagination hint — a cap. Tag number 1,001 onward simply never reaches your template. Your loop is fine; your data was truncated before it arrived.

Two properties make this failure nasty:

It is silent. Nothing in the admin counts your distinct tags against a budget. The theme renders happily with whatever it got.
It degrades asymmetrically. all_tags also includes tags from products that are filtered out of the current view, so the cap is consumed by your global tag vocabulary, not just the tags of the products currently visible. A big catalog burns through 1,000 distinct tags far faster than intuition suggests — every typo'd tag (grey vs gray), every seasonal tag, every supplier tag counts.

Meanwhile, tag-based URLs have their own sharp edges: multiple tags in a collection URL are combined with AND (products must carry all of them), and if a tag in the URL is used by no product in the store, Shopify redirects to the collection URL with that tag stripped. For "customers browse by attributes" UX, AND-semantics plus redirect-stripping is the opposite of faceted filtering.

Root cause #2: tags have no data model

Tags are strings. There is no type, no validation, no admin UI for "this attribute has these allowed values." That is fine for labels, and fatal for filter facets, because nothing stops the vocabulary from growing unbounded — which feeds root cause #1.

Metafields are the typed counterpart. A metafield is a key-value pair identified by a namespace + key (e.g. custom.material), with a value and a type. You first create a metafield definition, and definitions establish a data schema: type validation, Shopify admin integration, and query filtering. In other words, a definition is where "material is one of a fixed list of strings" becomes enforceable instead of aspirational.

Minimal reproduction

You can demonstrate the cap in a dev store in an afternoon:

Create one collection and ~50 products. Against those products, set 1,001+ distinct tags (e.g. tag-0001 … tag-1100, spread across products).
In the theme, render {{ collection.all_tags.size }} on the collection template.
Observe the output: 1000, regardless of how many distinct tags exist beyond that.
Render the tag-filter loop above: tags past the cap never appear as filter options, and there is no error anywhere to tell you why.

That size never exceeding 1000 is the entire bug report.

The fix: metafield-backed storefront filtering

Shopify documents two filtering methods for themes, and explicitly marks storefront filtering as the recommended one (tag filtering being the other). The migration looks like this:

1. Design the attribute schema. For each tag-family that acts as a filter facet (color, material, occasion…), create a product metafield definition. Check the type against what storefront filtering actually supports — metafield-based filters can reference only these types: single_line_text_field, list.single_line_text_field, metaobject_reference, list.metaobject_reference, number_integer, number_decimal, boolean. Multi-value facets (a product that is both "wool" and "silk") map to list.single_line_text_field.

2. Backfill values from tags. Walk the catalog, and for each product copy its tag values into the matching metafields. With the Admin GraphQL API, metafieldsSet sets metafield values (creating them if they don't exist yet); one call accepts a maximum of 25 metafields with a 10MB total payload cap, and the operation is atomic — either the whole call persists or nothing does. Batch accordingly. (We scripted this in chunks of 25 and logged every failure for retry; your backfill should be idempotent so re-runs are safe.)

3. Create the filters in admin. Storefront filters are not theme config — per the docs, filters need to be created in the Shopify admin before they can be applied (this is what the Search & Discovery app manages). One budget to know up front: a store can create a maximum of 25 filters. Consolidate ruthlessly — 25 well-typed facets beat 40 half-used ones.

4. Verify the URL contract. Applied filters show up in the URL. A metafield facet at product scope uses filter.p.m.<namespace>.<key>=value — e.g. /collections/all?filter.p.m.custom.material=wool — with comma-separated values for multi-select. If your theme (or a headless storefront) builds its own filter links, this is the contract to match.

5. One more ceiling to plan around. Storefront filtering has its own documented limit: collection.filters returns empty for collections containing over 5,000 products. For mega-catalogs, split big collections into smaller filtered collections rather than relying on the filter UI of a 10k-product "All" collection.

Checklist: are you near the ceiling?

Render {{ collection.all_tags.size }} on your biggest collection. At or near 1,000? Your tag filter UI is already dropping tags.
Count your global distinct tag vocabulary (exports, not one collection) — the cap is global-pressure.
Any facet that should be multi-select OR? Tag URLs combine with AND — that's a metafield filter job.
Budget your filters: 25 max per store. Consolidate before you create.
Backfill with metafieldsSet in ≤25-metafield atomic batches; make the script idempotent.
Any single collection over 5,000 products? collection.filters will be empty there — split it.
Keep tags for operational labels (pick lists, automation triggers); keep filterable attributes in metafields. Two vocabularies, two jobs.

Verified against Shopify's official documentation (Liquid collection object, theme filtering methods, storefront filtering, metafields, metafieldsSet) as of August 2026.

Originally published at https://clawmama.run/blog/shopify-tag-filtering-1000-limit/

Your Shopify Discount Function Can Silently Stop Working: The 10,000-Byte Metafield Trap

Eli — Fri, 31 Jul 2026 12:40:55 +0000

You built the right architecture: business rules in a JSON metafield, a Shopify Discount Function that reads them, no redeploys when a promotion changes. It works in testing. It works for months. Then the merchant adds one pricing tier too many — and every discount on the store silently stops applying. No error at checkout. Nothing in the order. The Function runs fine; it just returns nothing.

This failure mode costs money precisely because nothing looks broken. Here's why it happens and the design that survives it.

(Full bilingual writeup: canonical post on the ClawMama blog. This is part 2 of a Shopify-Functions-in-production series — part 1: rejecting discount codes cleanly. We build open-source Shopify agent skills — github.com/clawmama-run/shopify-growth-operator-agent — and a ready-to-use Shopify Agent.)

The two limits behind it

Both are documented on Shopify's Functions API page, buried in a limits table most people read once during setup.

Limit 1: the input query is static and capped at 3,000 bytes. Your Function's input query is fixed at build time (run.graphql). You can't add a field at runtime every time the merchant invents a new rule type. That's exactly why the config-as-JSON-blob pattern exists: one metafield field in the query, arbitrary structure inside.

Limit 2: a metafield value over 10,000 bytes is not returned. From the docs: "Metafields with values exceeding 10,000 bytes in size will not be returned." Not truncated — absent. The metafield node comes back empty, as if never set.

Follow the failure through your Function:

The config JSON grows past 10,000 bytes (a few dozen pricing tiers with conditions gets there fast).
The input query asks for the metafield; Shopify withholds it.
Your Function sees "no config" and does its unconfigured behavior — parse nothing, match nothing, return empty operations.
The store simply stops discounting. Checkout is valid. Orders complete. Nobody is notified.

And your last line of defense can't save you: Function logs are capped at 1 kB written, truncated.

The design that survives

Keep the config-in-metafield pattern (it's Shopify's own best practice for complex configuration) — but make it size-aware and fail-loud:

1. Budget the bytes, and measure them. 10,000 is the hard ceiling; treat ~8,000 as your alert line. The admin UI where merchants edit config should display the current byte size. new TextEncoder().encode(json).length — count bytes, not characters; CJK characters are 3 bytes each.

2. Fail loud, not silent. Decide what the Function does when the config metafield comes back absent, and make "absent" distinguishable from "legitimately empty." Apply a safe default and alert, or apply nothing but notify through your app's own monitoring (a daily Admin API job that reads the metafield — where it is returned — and checks size). The worst option is the default: shrug, return empty operations.

3. Shard before you hit the wall. Split config by domain — VIP tiers, quantity breaks, B2B rules — under your reserved $app: namespace, queried as separate fields. Three 4 KB metafields all come back; one 12 KB metafield comes back as nothing. Mind the query-side caps while sharding: list arguments max 100 elements, input query cost limit 30.

4. Test the boundary. Add a deliberately-over-10KB fixture config to your dev store test suite. Lock in "we get alerted," not "discounts vanish quietly."

Check your exposure today

Via Admin GraphQL, fetch the config metafield and measure the byte length of value (Admin API returns full values regardless of size — the cutoff applies to Function input queries only).
Under 8 KB: add the size display + alert, re-check as rule count grows.
Over: your discounts may already be intermittent. Check recent orders for missing discount applications, then shard.

Where an agent fits

The design fix is one-time. The ongoing risk is drift: rule counts creep, someone pastes a giant JSON, a new promotion type doubles the config. That's a monitoring loop a store operations agent can own — watching config size and discounted-order rate, flagging anomalies to the owner with evidence attached, before a customer notices.

Verified against Shopify's Functions API documentation (input query limits, fixed limits) as of July 2026. Field report via a Shopify Community thread — the practitioner who documented this failure mode had the numbers exactly right.

Affiliate Links vs. Discount Codes on Shopify: Why They Collide and How to Separate Them

Eli — Thu, 30 Jul 2026 08:56:20 +0000

A customer clicks your affiliate's referral link on Monday. On Wednesday they come back through your Instagram bio, grab the 10% popup code, and check out. Now one of two bad things happens: the affiliate loses their commission to last-touch attribution, or you pay commission and a discount on an order that needed only one incentive.

Every merchant running an affiliate program (GoAffPro, UpPromote, ReferralCandy…) alongside discount codes hits this. The question comes up constantly in the Shopify Community: can I block discount codes for customers who arrived through an affiliate link?

Short answer: no native setting exists. But there's a working architecture — and a newer piece of the Discount Function API makes the checkout experience much cleaner than it used to be.

(Full bilingual writeup with architecture details: canonical post on the ClawMama blog. We build open-source Shopify agent skills — github.com/clawmama-run/shopify-growth-operator-agent — and a ready-to-use Shopify Agent if you want the monitoring part without the setup.)

Why Shopify can't do this natively

Discount eligibility is conditioned on customer segments, products, collections, order minimums, combination rules. It never sees how the customer arrived. The referral source lives in your affiliate app's tracking script and cookie. Discount codes are validated at checkout entry — and checkout has no idea the customer clicked a referral link three days ago. No plan has an eligibility rule that reads "came from affiliate X."

So the fix must bridge two systems: get referral state into the cart, then let checkout logic act on it.

Fixes that look right but backfire

0% commission when a code is used. The most common affiliate-app setting people reach for. It solves double-payment by transferring the cost to your affiliate. First time a partner notices they drove a sale and earned nothing, they stop promoting you.

Cart Validation Function. You can block the order — but the customer sees a generic error, not "this code doesn't apply to you." Reads as "the store is broken."

Zeroing the discount via an automatic-discount Function. The code gets accepted and the total doesn't move. The store took their code and gave nothing. Arguably the worst ending.

Root problem in all three: the customer is never told, clearly, that the code can't be used on referral orders — and the affiliate's credit is an afterthought.

The working architecture

1. Capture referral state as a cart attribute. Cart attributes travel with the cart into checkout, and Discount Functions can read them. A small theme script detects the affiliate's referral signal (URL param or the app's cookie) and writes it via the Ajax API: POST /cart/update.js with attributes: { referral_source: "affiliate" }.

2. Attach a Discount Function to an automatic discount. Code discounts are validated before Functions get a say. So your Function runs on an automatic discount you create yourself (discountAutomaticAppCreate) — it doesn't need to discount anything; its job is to give your Function a seat at checkout. The input query reads your cart attribute plus enteredDiscountCodes.

3. Reject with enteredDiscountCodesReject. If referral state is present and the customer entered one of your marketing codes, return:

{
  "enteredDiscountCodesReject": {
    "codes": [{ "code": "WELCOME10" }],
    "message": "WELCOME10 can't be combined with a referral order — your referral already gives you the best deal."
  }
}

The customer sees a specific, human explanation. The affiliate keeps their commission because referral tracking was never touched. Nobody gets double-paid.

Three constraints from Shopify's docs:

Only Functions backed by an automatic discount can reject codes.
You can only reject codes still rejectable — entered but not yet applied. Act on enteredDiscountCodes at entry time, not retroactively.
The rejection message displays in checkout and should be localized.

enteredDiscountCodesReject arrived with the 2026-01 API version — which is why older threads about this problem end with "you can't do it cleanly." You can now.

The cookie-window trap

Affiliate referral cookies persist for days or weeks. If your theme script writes the referral attribute and it lingers, a customer who clicked a partner's link three weeks ago gets their birthday-email code rejected with no idea why.

Decide deliberately: session-scoped (reject only when the referral was detected this session — fewer angry customers, some attribution leakage) or window-scoped (reject for the full cookie window — cleaner economics, but you must communicate the rule). Whichever you pick, tell your affiliates upfront.

Test before you ship

Shop Pay / accelerated checkouts — does the rejection message surface?
Automatic discounts + codes combination rules.
Happy path — non-referral customers must still use the code normally.
POS and draft orders if you use them — Function behavior differs by surface.

Where an agent fits

The rejection logic is a one-time build. The ongoing work is monitoring: catching orders where a code and a referral both fired, spotting new conflict patterns (new partner, new code campaign), flagging anomalies before they become a month-end commission dispute. That's a loop a store-operations agent can own — surfacing conflicts with evidence while the rule itself stays a decision you make once.

Verified against Shopify's Discount Function documentation as of July 2026. enteredDiscountCodesReject requires API version 2026-01+.

AI-Era CRM Should Understand the Relationship, Not Just the Pipeline

Eli — Mon, 27 Jul 2026 05:14:31 +0000

Before your last meeting with someone important, did you open your company's CRM?

Probably not. You scrolled through the chat history.

A sales CRM is good at answering, "Where is this customer in the pipeline?" It is often worse at answering, "Where did I leave things with this person?"

That problem led us to build guanxi-crm, a free, open-source, local-first relationship-memory tool. It stores readable Markdown as the source of truth, uses a rebuildable SQLite index for recall, and gives AI agents a strict CLI for identity resolution and relationship history.

You can read the bilingual ClawMama Blog version, install the project from GitHub, or use the ready-to-run Personal Relationship Management Agent.

The point is not to replace sales CRM. It is to preserve the context that conventional records usually flatten: how two people met, what changed, what was promised, which channel works best, and what should be remembered before the next conversation.

The things that do not fit in fields

Try putting these into a conventional CRM:

He recently got divorced and does not want to discuss it.

His daughter takes the gaokao next year, and he is anxious.

He dislikes phone calls. Send a text instead.

Last time we spoke, he was interested in the book I recommended.

Which fields should hold them?

Usually they end up in Notes: the unstructured box that every CRM provides and few people read carefully later.

The structured record keeps the name, employer, title, email address, last-contact date, and deal value. Those fields are useful for a sales organization. They are less useful five minutes before a conversation. The title is on LinkedIn. The email is in an address book. What you need is context: what changed, where the last conversation stopped, and what deserves care this time.

Fields were a historical compromise

This was not careless design. When CRMs emerged, structure was the practical choice.

Databases needed schemas, and lists had to be scannable. To find everyone in manufacturing, based in Shanghai, with no contact in three months, a system needed columns for industry, city, and date. Each person became a row.

That compression was useful, but it was lossy. The first information to disappear was whatever could not be classified in advance.

For decades, there was no good alternative. Teams could store free-form meeting notes, but retrieving one relevant sentence from hundreds of thousands of words was difficult. Unstructured text was easy to write and hard to reuse.

Fields were not the ideal representation of a relationship. They were a reasonable design under a technical constraint.

That constraint is disappearing

Large language models make natural-language records readable by machines.

Consider this note:

He said his company was making layoffs. He thinks his job is safe, but his mood seemed off.

A model can distinguish the background event from his personal situation, preserve the uncertainty, and surface the note before the next meeting.

That suggests a different architecture: record the observation in natural language, then derive structure when it is read.

This does not mean schemas disappear. Stable IDs, dates, entity types, and explicit participants still matter. The shift is narrower: do not force every human detail into a fixed taxonomy merely so a machine can read it.

A person is not a static contact card

One person can be your former colleague, current customer, friend's spouse, and an investor in your side project.

The relevant role changes with the situation. Real roles overlap and evolve, and no schema designer will anticipate every category, including something as specific as "my cousin's landlord."

People change too. When someone changes employers, overwriting the old company removes useful history. Six months without contact is itself information. A communication pattern that has cooled may matter more than the current value of a job-title field.

Identity is just as untidy. Is Zhang San in WeChat the same person as San Zhang on LinkedIn, 张叁 on a business card, or the person represented only by a phone number? An email address or phone number is identity evidence. It is not the person.

A reliable system should not silently turn uncertain evidence into a confident identity merge. If it finds two people named Zhang Wei, it should stop and ask which one you mean. Missing information can be completed later. A wrong identity merge quietly corrupts every record that follows.

What guanxi adds to the conversation

The Chinese word guanxi (关系) is often translated as "connections" or "networking." Both translations are incomplete. Depending on context, it can refer to a relationship shaped over time by shared history, trust, social roles, favors, obligations, and an understanding of what each person can reasonably ask of the other.

That does not make Chinese relationships mysterious or uniquely transactional. Every culture distinguishes a contact from a person who has shown up for you repeatedly. The useful part of the Chinese term is that it makes accumulated relational context hard to ignore.

This is also why guanxi should not be reduced to "who can help me." The important memory may be that someone once made an introduction for you. It may also be that you promised to send a document, that their parent has been ill, or that a subject is better left alone. Reciprocity includes care and responsibility, not only access.

What changes when CRM is designed for agents

Traditional CRM and agent CRM do not have to compete. Sales and customer success still need accounts, opportunities, activities, and stages. An agent-native system adds another layer: the person and the context behind the workflow.

Traditional CRM is good at	An agent CRM should also do
Tracking accounts, opportunities, activities, and stages	Preserving the conversations, promises, preferences, introductions, and history behind them
Collecting data through forms, imports, and integrations	Extracting facts from conversations and events while retaining readable source context
Using a primary email or contact record as identity	Supporting multiple, shared, and changing identifiers, and stopping when a match is ambiguous
Recalling work through timelines, dashboards, tasks, and pipeline views	Producing a pre-meeting brief with recent interactions, forgotten details, referrals, and explicit follow-ups
Adding AI on top of an existing UI and schema	Giving agents native interfaces such as CLI, JSON, authoritative IDs, and documented recovery paths
Requiring people to use the CRM application	Letting people inspect the same memory through an agent, CLI, Obsidian, or Markdown files

An agent interface is not simply an API that returns success or failure. When identity resolution fails, the error needs to provide candidates and a safe next action. Otherwise an agent may route around the guardrail and invent an ID.

Incomplete information should be accepted. A note such as "someone I met at a conference, works in supply chain, surname may be Wang" is worth saving. Identity ambiguity, however, should fail loudly.

We banned scores for people

We adopted a product rule: no importance, priority, or value score on a person, and no leaderboard of "best contacts."

Once a tool asks users to judge whether someone is useful, records start filling with titles, employers, influence, and access. The ordinary details that create genuine context disappear. Sorting by observed facts is different. It can be reasonable to ask who has not been contacted recently. That answer describes the record. It does not claim to measure a human being's worth.

Relationship memory also contains sensitive information: family events, health concerns, job changes, private conversations. The data should be portable, inspectable, and stored with deliberate privacy boundaries.

An implementation: Markdown as truth, SQLite as recall

guanxi-crm is deliberately modest: a single-user, offline, headless CLI with no application server or dedicated graphical UI.

Its authoritative data lives in UTF-8 Markdown. SQLite is a disposable recall index that can be rebuilt from those files. People have stable IDs, while names, aliases, email addresses, and phone numbers remain identity evidence rather than primary keys. Shared identifiers and duplicate names may remain ambiguous instead of being silently resolved.

Interactions are separate, dated records. Their participants must be explicit; mentions in free-form text do not automatically become participants. The repository also ships a relationship-memory Skill that tells an agent to resolve authoritative IDs before writing and to stop for clarification when identity is ambiguous.

People can inspect the same vault directly in Obsidian, including Markdown, backlinks, and graph view. If you do not want to install the CLI and Skill yourself, ClawMama packages the workflow as a ready-to-use Personal Relationship Management Agent.

One useful test

Many CRM fields were designed for a world in which machines could not read human language. That world is changing.

A relationship-memory system does not need a grand metric. One question is enough:

Two months from now, before you meet someone, can it surface one thing you had forgotten but should remember?

If it cannot, it is still just a better address book.

AI-Era CRM Should Understand the Relationship, Not Just the Pipeline

Eli — Mon, 27 Jul 2026 03:33:50 +0000

Before your last meeting with someone important, did you open your company's CRM?

Probably not. You scrolled through the chat history.

A sales CRM is good at answering, "Where is this customer in the pipeline?" It is often worse at answering, "Where did I leave things with this person?"

AI-era CRM should handle both. Adding a chat box to the existing interface is not enough. The system has to preserve relationship context: how two people met, what changed, what was promised, which channel works best, and what should be remembered before the next conversation.

The things that do not fit in fields

Try putting these into a conventional CRM:

He recently got divorced and does not want to discuss it.

His daughter takes the gaokao next year, and he is anxious.

He dislikes phone calls. Send a text instead.

Last time we spoke, he was interested in the book I recommended.

Which fields should hold them?

Usually they end up in Notes: the unstructured box that every CRM provides and few people read carefully later.

Fields were a historical compromise

This was not careless design. When CRMs emerged, structure was the practical choice.

That compression was useful, but it was lossy. The first information to disappear was whatever could not be classified in advance.

Fields were not the ideal representation of a relationship. They were a reasonable design under a technical constraint.

That constraint is disappearing

Large language models make natural-language records readable by machines.

Consider this note:

He said his company was making layoffs. He thinks his job is safe, but his mood seemed off.

This is more than a bag of searchable keywords. A model can distinguish the background event from his personal situation, preserve the uncertainty, and surface the note before the next meeting.

That suggests a different architecture: record the observation in natural language, then derive structure when it is read.

If a user wants to filter people by industry, extract industry at query time. If they want a meeting brief, retrieve recent changes, previous topics, and communication preferences. The person writing the first note should not have to predict which facet will matter three years later.

A person is not a static contact card

One person can be your former colleague, current customer, friend's spouse, and an investor in your side project.

The relevant role changes with the situation. During a contract renewal, "customer" comes forward. At dinner with friends, it recedes. Real roles overlap and evolve, and no schema designer will anticipate every category, including something as specific as "my cousin's landlord."

A reliable system should not silently turn uncertain evidence into a confident identity merge.

If it finds two people named Zhang Wei, an agent can answer:

I found two matches: a colleague from 2019 and a photographer you met last month. Which one do you mean?

That admission of uncertainty is useful. A mistaken merge may produce no error at all, while every future note quietly attaches to the wrong person.

What guanxi adds to the conversation

The open-source project behind this idea is called guanxi-crm, so the name needs some explanation.

A contact database captures identifiers. Relationship memory has to preserve context, change, trust, and boundaries.

What changes when CRM is designed for agents

Traditional CRM is good at	An agent CRM should also do
Tracking accounts, opportunities, activities, and stages	Preserving the conversations, promises, preferences, introductions, and history behind them
Collecting data through forms, imports, and integrations	Extracting facts from conversations and events while retaining readable source context
Using a primary email or contact record as identity	Supporting multiple, shared, and changing identifiers, and stopping when a match is ambiguous
Recalling work through timelines, dashboards, tasks, and pipeline views	Producing a pre-meeting brief with recent interactions, forgotten details, referrals, and explicit follow-ups
Adding AI on top of an existing UI and schema	Giving agents native interfaces such as CLI, JSON, authoritative IDs, and documented recovery paths
Requiring people to use the CRM application	Letting people inspect the same memory through an agent, CLI, Obsidian, or Markdown files

The last two rows matter more than they first appear. An agent interface is not simply an API that returns success or failure. When an identity operation fails, the error has to provide candidates and a safe next action. Otherwise the agent may route around the guardrail and invent an ID from a filename or a fragment of context.

This leads to two useful asymmetries.

Incomplete information should be accepted. A note such as "someone I met at a conference, works in supply chain, surname may be Wang" is worth saving. A rigid form may reject it because required fields are missing. Worse, an agent asked to complete the form may invent values just to pass validation.

Identity ambiguity, however, should fail loudly. Missing information can be completed later. A wrong identity merge quietly corrupts every record that follows.

The same discipline applies to inference. Facts such as contact recency and frequency can be computed. A person's "importance" or "value" should not be.

We banned scores for people

While designing the system, we adopted a product rule: no importance, priority, or value score on a person, and no leaderboard of "best contacts."

The reason is partly ethical and partly practical. Once a tool asks users to judge whether someone is useful, the records start filling with titles, employers, influence, and access. The ordinary details that create genuine context disappear. The resulting data becomes less human and, eventually, less useful.

Sorting by observed facts is different. It can be reasonable to ask who has not been contacted recently or which relationships have frequent interactions. Those answers describe the record. They do not claim to measure a human being's worth.

Relationship memory also contains highly sensitive information: family events, health concerns, job changes, private conversations. Making prose machine-readable increases the need for user control. The data should be portable, inspectable, and stored with deliberate privacy boundaries.

An implementation: Markdown as truth, SQLite as recall

guanxi-crm is an open-source, local-first relationship-memory CLI built around these constraints.

Its authoritative data lives in UTF-8 Markdown files. SQLite is a disposable recall index that can be rebuilt from those files. People have stable IDs, while names, aliases, email addresses, and phone numbers remain identity evidence rather than primary keys. Shared identifiers and duplicate names are allowed to remain ambiguous instead of being silently resolved.

Interactions are separate, dated records. Their participants must be explicit; mentions in free-form text do not automatically become participants. A sensitive marker can keep a line in the source while excluding it from ordinary briefs. The repository also ships a relationship-memory Skill that tells an agent to resolve authoritative IDs before writing and to stop for clarification when identity is ambiguous.

The current project is deliberately modest: a single-user, offline, headless CLI with no application server or dedicated graphical UI. People can still open the vault directly in Obsidian to browse Markdown, backlinks, and its graph view. The system provides a trustworthy memory layer that an agent can query; it does not pretend to infer an entire social world from a contact list.

For people who prefer a ready-to-use version rather than installing the CLI and Skill, the Personal Relationship Management Agent on ClawMama packages the workflow into an Agent that can be used directly.

One useful test

Many CRM fields were designed for a world in which machines could not read human language.

That world is changing. We can now preserve relationships closer to the way people actually remember them: not only "name, company, title, deal value," but "his daughter's exam is next year," "he prefers text," and "he wanted to discuss that book again."

A relationship-memory system does not need a grand metric. One question is enough:

Two months from now, before you meet someone, can it surface one thing you had forgotten but should remember?

If it cannot, it is still just a better address book.

Shopify Sidekick vs. Shopify Magic: What Each One Actually Does After Spring '26

Eli — Sun, 26 Jul 2026 05:36:06 +0000

Type shopify.com/magic into a browser today and you land on the Sidekick page. As of 2026-07-26, the old Magic product URL redirects to shopify.com/sidekick. That redirect is the first useful fact in this comparison, because it shows how Shopify now frames the two names. The second useful fact: Magic is not discontinued. Shopify still documents Shopify Magic features and still uses the name on feature surfaces. What changed is the packaging: one assistant at the front door, the generation features behind it.

The short answer

Shopify Magic is the generation layer. Shopify's documentation presents it as a family of AI features embedded across the platform rather than an assistant you talk to: product and marketing text generation and rewriting, Shopify Email copy and subject-line suggestions, Shopify Inbox suggested replies, and product-media work like background removal, replacement, and generated scenes.

Sidekick is the store-aware assistant. Shopify's Sidekick page calls it an "AI Shopify expert" with direct access to store data, an understanding of commerce workflows, and the ability to take action in the admin. It requires no separate purchase. Shopify's exact FAQ wording: "No. Sidekick is included with your Shopify plan. Features and usage limits vary by plan."

So the decision is not "which AI is better." It is which job you are delegating. Blank page or product photo: Magic. A job that starts from store data or ends in an admin change: Sidekick. Either way, the merchant still defines the goal, supplies source facts, approves customer-visible or financial changes, and verifies results. Neither product replaces operations staff.

Compare by five dimensions, not a feature checklist

Feature lists go stale within a quarter. These five dimensions hold up better:

Context: Magic works on the content field in front of it. Sidekick reads store data, within the staff member's permissions.
Output: Magic produces drafts and generated media. Sidekick produces answers, analysis, configured objects, and supported actions.
Permission and approval: both operate inside your admin session and staff rights; writes wait for confirmation.
Verification: drafts get read, media gets compared against the physical product, actions get confirmed and checked.
Reach: Magic lives on native Shopify surfaces. Sidekick works in the admin, in the Shopify mobile app, and, since Spring '26, in a selected set of partner apps.

	Shopify Magic	Shopify Sidekick	Your part
What it is	Generation features embedded in Shopify surfaces	Store-aware assistant in the admin	Decide which job to delegate
Typical output	Text drafts, email copy, inbox replies, edited media	Answers, analysis, configured objects, supported actions	Review before anything goes live
Data context	The content field in front of it	Store data, within your staff permissions	Supply the facts AI cannot know
Reach	Native Shopify surfaces	Admin, mobile app, selected partner apps	Everything outside that reach

What Spring '26 changed

Per Shopify's Spring '26 Editions page, Sidekick now works with partner apps (starting with Judge.me, Klaviyo, Loop, Smile, and others), opens admin sessions with "Actionable guidance from Sidekick" covering acquisition, conversion, and repeat sales, asks multiple-choice clarifying questions, keeps working in the background across chats and closed windows, runs across the Shopify mobile app by typing or voice, creates customer records from plain-language descriptions, generates test events for Shopify Flow automations, and gains a generated-app editor with code editing, previews, and version history.

The operational consequence matters more than the feature count. Sidekick is moving from answering questions toward taking action, background work, app reach, and lightweight software creation. Every one of those moves increases what a wrong or premature action can touch. Permissions, confirmation, testing, and post-action verification matter more after this release, not less.

Six scenarios, and who does what

A product description. Magic's home ground: first drafts and tone variants in the product editor. Thin product facts produce fluent, generic copy. No generation feature recovers missing specs, verified claims, or brand policy. You supply substance and edit for truth.

A product photo background. Magic can remove or replace backgrounds and generate scenes. Treat output as a candidate: compare edges, proportions, textures, labels, shadows, and reflections against the physical product.

"What was my best product last month?" A Sidekick question with a trap inside. "Best" can mean gross sales, net sales, units, margin, conversion, repeat purchase, a channel, or a time window. Sidekick queries store data; you own the definition. For high-stakes reporting, deterministic reports and exports remain the safer path.

Creating a discount or a customer record. Sidekick can do both. Discounts touch money and are customer-visible: review the exact configuration before confirming, then check the storefront after.

Testing a Flow automation. Sidekick can generate test events to verify workflow logic before it touches real orders. An untested automation is an assumption, and a failed trigger is silent until someone looks.

Acting in a third-party app. Spring '26 names an initial partner set, which proves selective expansion, not universal compatibility. Confirm your specific app and action are supported before designing a process around them.

Permissions, approval, and what still requires a merchant

Sidekick inherits staff permissions. Shopify's exact FAQ wording: "Every staff member can use Sidekick based on their admin permissions. It respects access controls, so team members only interact with data and features they're authorized to use." Your permission hygiene now doubles as AI risk management.

Approval requirements protect the merchant and define the product's ceiling: a tool that waits for confirmation before a write is not unattended store operations. Five things stay human regardless: defining success (including metric definitions), supplying reliable source facts, approving customer-visible or financial changes, verifying outcomes after actions, and owning the systems Sidekick cannot reach, which still includes most external and legacy tooling.

Methodology and limitations

Research cutoff was 2026-07-26. I directly verified the /magic to /sidekick redirect and fetched the current Sidekick product page and Spring '26 Editions page. Capability examples cited are Shopify's own, labeled as such, not independent validation. No hands-on testing was performed for this article, and no claims are made about sales lift or output accuracy, because no broad independent dataset exists for the current Spring '26 Sidekick. Shopify's Help Center blocked automated fetching (HTTP 403), so Magic feature categories come from stable documented categories rather than a fresh fetch. Partner app support is selective and evolving.

The longer version of this analysis, with a FAQ and per-audience recommendations, lives on the ClawMama blog.

DEV Community: Eli

Your variant has one image, your product has twenty — the Shopify gallery filter question, finally answered

Root cause: two things that look alike

Minimal reproduction

Route 1 — Alt-text tagging + gallery filter (free, code, no app)

Route 2 — Shopify Combined Listings (free, first-party, Plus only)

Route 3 — Apps

Decision tree

Checklist

Google kept rejecting a bookstore's print listings — because the ebook was still buyable on the same URL

The structural fact that explains everything

Minimal reproduction (no Google required)

Route A — Split the formats into separate products (the structural fix)

Route B — Proxy page: a physical-only offer page per title (the theme fix)

Route C — GMC attribute rules with excluded_destination (the feed-hygiene fix)

Checklist

A merchant asked for B2B subscriptions — so I read the schema and found the wall

Root cause: a one-sentence wall

Why "use a draft order" fails at the API level

Minimal reproduction

Door 1 — the D2C lane (no app required)

Door 2 — the API door: build the contract without checkout

Door 3 — emulate recurrence with native B2B primitives

Checklist

Your AI fortune teller was making things up — so we took the math away from the model

The chart is math, not prose

The projects that got it right

What we built

I gave my AI coding assistant a design degree (one skill, 875 likes later)

The gap isn't technical — it's aesthetic

Someone decomposed "zine style" into executable rules

Does it work?

Our bundle math was wrong because Shopify rejected our cart transform — and then leaked a price

Wall #1: selling plans hard-reject Cart Transform operations

Wall #2: the price that leaks through

The defensive pattern: composite keys, not variant IDs

Minimal reproduction

The numbers worth pinning above your desk

I found out why our Shopify filters were missing options: the 1,000-tag ceiling

Root cause #1: collection.all_tags is hard-capped at 1,000

Root cause #2: tags have no data model

Minimal reproduction

The fix: metafield-backed storefront filtering

Checklist: are you near the ceiling?

Your Shopify Discount Function Can Silently Stop Working: The 10,000-Byte Metafield Trap

The two limits behind it

The design that survives

Check your exposure today

Where an agent fits

Affiliate Links vs. Discount Codes on Shopify: Why They Collide and How to Separate Them

Why Shopify can't do this natively

Fixes that look right but backfire

The working architecture

The cookie-window trap

Test before you ship

Where an agent fits

AI-Era CRM Should Understand the Relationship, Not Just the Pipeline

The things that do not fit in fields

Fields were a historical compromise

That constraint is disappearing

A person is not a static contact card

What guanxi adds to the conversation

What changes when CRM is designed for agents

We banned scores for people

An implementation: Markdown as truth, SQLite as recall

One useful test

AI-Era CRM Should Understand the Relationship, Not Just the Pipeline

The things that do not fit in fields

Fields were a historical compromise

That constraint is disappearing

A person is not a static contact card

What guanxi adds to the conversation

What changes when CRM is designed for agents

We banned scores for people

An implementation: Markdown as truth, SQLite as recall

One useful test

Shopify Sidekick vs. Shopify Magic: What Each One Actually Does After Spring '26

The short answer

Compare by five dimensions, not a feature checklist

What Spring '26 changed

Route C — GMC attribute rules with `excluded_destination` (the feed-hygiene fix)