Feature request: `lineAdd` operation for the Cart Transform Function API (critical for agentic checkouts)

Functions
1

Hi all,

I’m Stephen from Magical Apps. I’ve raised parts of this directly with the checkout extensions team over the past year, but I want to put it in a public place where other developers can add their use cases and Shopify can see the demand in one thread.

The ask

Add a lineAdd operation to the Cart Transform Function API that lets a function insert a new cart line (by variant ID + quantity, with optional price/title/image/attributes) that isn’t already in the cart.

Today Cart Transform supports lineExpand, linesMerge, and lineUpdate. There is no way for a function to add a line, and there’s no way to remove one either. See the long-running request in Shopify/function-examples#213: 62 votes since 2023, latest comment May 2026, no staff response since 2024.

Why this is now urgent: agentic checkouts

Until recently, apps that need to conditionally add an item to the cart could get away with client-side workarounds: theme app extension JS calling /cart/add.js, or applyCartLinesChange from a checkout UI extension.

Agentic Storefronts change that. When an order flows through ChatGPT / Copilot / Gemini / Perplexity via UCP:

  • There is no theme, so theme app extension JavaScript never runs.
  • Checkout UI extensions are restricted in agentic checkouts. This was covered directly at DotDev in the “How Shopify Functions help you succeed in agentic checkouts” session, where the guidance was to lean on Functions and native platform capabilities. Notably, the workaround suggested in #213 back in 2024 was checkout UI extensions, which is exactly the surface that is now restricted.
  • Functions do run, but they can’t add a line.

So for any merchant whose business rules require an item to be present in the cart, agentic orders will silently skip it. That isn’t a UX gap, it’s a revenue and compliance gap: the merchant is completing sales without the required item.

Concrete examples we support today that break in agentic checkout:

  • Required fees represented as products: payment method surcharges, handling fees, environmental/regulatory fees (EHF, tariffs, deposits) that legally must be on the order.
  • Required add-ons: assembly service, mandatory insurance, container deposits, hazmat handling.
  • Conditional gifts / bundles: free gift over threshold, mandatory companion items.

I’ll note that native “additional fees” capabilities were mentioned in the same DotDev session as part of the platform path. A native fee primitive is welcome, and we’d use it. But it doesn’t cover add-on products: gifts, deposits, insurance, assembly, companion items, or fees that must be represented as products for legal or accounting reasons. Those need a real cart line.

lineExpand is the closest existing tool (Shopify’s own docs use a gift-wrap example), but it only works by attaching components to an existing line as a bundle, and in our testing it’s rejected when a selling plan is present. That’s a workaround, not a primitive.

It also closes the Scripts gap

Scripts stopped executing on June 30. Several developers in #213 said they couldn’t leave Scripts because Functions can’t add or remove lines. That capability is now simply gone, with no replacement. This is the missing piece.

Proposed shape

input LineAddOperation {
  merchandiseId: ID!            # ProductVariant GID
  quantity: Int!
  price: PriceAdjustment        # optional fixed/percentage override
  title: String                 # optional presentation override
  image: ImageInput             # optional
  attributes: [AttributeInput!] # optional line item properties
  parentCartLineId: ID          # optional: associate with a triggering line so removal cascades
}

Behaviour notes that would matter to us:

  • Deterministic and idempotent. Running the function twice on the same cart shouldn’t double-add. Ideally Shopify dedupes on (merchandiseId, attributes), or the function receives previously-added lines with a marker so it can decide.
  • Dedupe needs to work across apps too. The docs already define collision rules for lineExpand/linesMerge/lineUpdate when multiple apps’ transforms target the same line (ordered by cartTransformCreate activation time). lineAdd should get the same treatment.
  • Runs on every cart mutation, same as existing operations, so removal of the trigger product naturally results in the added line no longer being emitted.
  • Available on all plans, not gated to Plus. The whole point is parity across surfaces, including ones merchants don’t control.
  • Respect inventory policy (fail closed or open per the cart transform’s blockOnFailure setting).

Related asks that compound this

  • lineRemove / quantity adjustment (#213)
  • Selected payment method in Cart Transform and Validation Function input, so fee lines can be conditional on payment method
  • Higher metafield limits for function configuration. Fee rule sets for real merchants run 50-250KB. Function input metafields silently return null above 10KB, and the 2026-04 change capping JSON metafield writes at 128KB (down from 2MB) moves the wrong direction.

What I’m hoping for

If you build anything that conditionally adds items to the cart (fees, gifts, add-ons, bundles, deposits), please reply with your use case and whether you’ve tested it against an agentic order. And if anyone from the Functions or checkout team can share whether cart line addition is on the roadmap, that would help a lot of us plan.

Thanks,
Stephen

3

Hey @stephensmith - thanks for the thoughtful writeup and the concrete use cases.

I’m submitting your feedback as a feature request for review. I don’t have a roadmap or timeline to share, but I’ll include the context you’ve provided here and I’ll follow up in this thread if anything changes.

Hope this helps!