--- title: "List a rule's scenarios" method: GET path: "/v25-10-beta/agentic-logic/rules/{ruleId}/scenarios" tags: ["Agentic Logic"] --- # List a rule's scenarios `GET /v25-10-beta/agentic-logic/rules/{ruleId}/scenarios` ## Request - Base URL: `https://api.intelligems.io` - URL: `https://api.intelligems.io/v25-10-beta/agentic-logic/rules/{ruleId}/scenarios` - Auth: API key in header `intelligems-access-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) ```http GET /v25-10-beta/agentic-logic/rules/{ruleId}/scenarios ``` Lists the validation scenarios of the rule's saved draft (code rules) or the scenarios its template describes (builder rules). - `status` is `ready`, or `pending` when the generated scenarios do not yet cover the draft's current branches. The read never starts generation. - `branchIds` lists the draft's `attempt()` branch labels, so coverage gaps are visible. Use the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled. **Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s. ## Path parameters - `ruleId` string, uuid, required ## Response `200` OK - object - `scenarios` object[], required - `name` string, required: Human-readable scenario name, shown in test results and gate details. - `request` object, required: The recommendation request the scenario evaluates. `placementId` and `surface` here are wire shape, not references: gates evaluate the rule directly, never an assignment, so no real placement is involved. - `surface` 'onsite' | 'checkout' | 'post-purchase', required: Surface the recommendation will render on. There is deliberately no 'headless' value — API callers declare the surface they render. - `placementId` string, required: Identifier of the placement being filled. - `cart` object, nullable, required: Snapshot of the visitor's current cart. An empty cart (zero lines) is a legal cart — distinct from cart: null, which means the surface has no cart at all (post-purchase). - `currency` string, required: ISO-4217 currency code all money fields in this cart are in. - `subtotal` integer, required: Cart merchandise subtotal in integer minor units of `currency`, before shipping and taxes. - `itemCount` integer, required: Total unit quantity across all lines (sum of line quantities) — units, not the count of distinct lines. - `lines` object[], required: The cart lines. - `productId` string, required: Shopify product GID (gid://shopify/Product/). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected. - `variantId` string, required: Shopify variant GID (gid://shopify/ProductVariant/). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected. - `quantity` integer, required: Number of units on the line. Positive integer. - `unitPrice` integer, required: Per-unit price actually in the cart, in integer minor units of the cart's currency. - `lineTotal` integer, required: Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency. - `selectedOptions` object[], required: Selected product options for the line's variant. - `name` string, required: Option name as configured on the Shopify product (e.g. 'Size'). - `value` string, required: Selected option value (e.g. 'Medium'). - `isSubscriptionLine` boolean, required: True when the line carries a selling plan (subscription), false for a one-time purchase. - `flags` object, required: Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats. - `giftCard` boolean, nullable, required: True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there. - `syntheticGift` boolean, nullable, required: True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker. - `bundleChild` boolean, nullable, required: True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all. - `igUpsell` boolean, nullable, required: True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker. - `tags` string[]: The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags. - `collections` string[]: Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`. - `order` object, nullable, required: The completed order a post-purchase surface is rendered against. First-class on the post-purchase surface only; null everywhere else. Deliberately carries NO customer field — the top-level request `customer` is the single customer reference. - `orderId` string, required: Shopify order GID (gid://shopify/Order/). - `checkoutToken` string: Shopify checkout token for the checkout that produced this order, when available. - `createdAt` string, date-time, required: Order creation time as an ISO-8601 UTC timestamp. - `currencyCode` string, required: ISO-4217 shop currency code the order's money fields are denominated in. - `presentmentCurrency` string, required: ISO-4217 currency code the shopper saw at checkout, which may differ from `currencyCode`. - `itemsSubtotal` integer, required: Merchandise subtotal after line-level discounts but before order-level discounts, shipping, and taxes. Integer minor units. - `discountTotal` integer: Total order-level discount amount in integer minor units, when any. - `shippingTotal` integer: Shipping charged in integer minor units, when known. - `taxTotal` integer: Taxes charged in integer minor units, when known. - `total` integer, required: What the shopper was actually charged, in integer minor units. - `lines` object[], required: The purchased order lines. - `productId` string, required: Shopify product GID (gid://shopify/Product/). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected. - `variantId` string, required: Shopify variant GID (gid://shopify/ProductVariant/). The bare numeric id the Shopify admin and most PIM exports show is accepted and promoted to GID form on the way in; anything that is neither is rejected. - `quantity` integer, required: Number of units on the line. Positive integer. - `unitPrice` integer, required: Per-unit price actually in the cart, in integer minor units of the cart's currency. - `lineTotal` integer, required: Line total (unit price times quantity, after line-level adjustments), in integer minor units of the cart's currency. - `selectedOptions` object[], required: Selected product options for the line's variant. - `name` string, required: Option name as configured on the Shopify product (e.g. 'Size'). - `value` string, required: Selected option value (e.g. 'Medium'). - `isSubscriptionLine` boolean, required: True when the line carries a selling plan (subscription), false for a one-time purchase. - `flags` object, required: Provenance flags (gift card, synthetic gift, bundle child, Intelligems upsell). Which flags a surface can actually answer differs per surface — see the request contract's per-surface caveats. - `giftCard` boolean, nullable, required: True when the line is a Shopify gift-card product, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every checkout and post-purchase line — neither surface exposes a gift-card marker, so a clause keyed on this flag is inert there. - `syntheticGift` boolean, nullable, required: True when the line was injected as a gift-with-purchase by a promotion, false when known not to be one, or null when the surface exposes no authoritative marker. - `bundleChild` boolean, nullable, required: True when the line is a child component of an expanded bundle, false when known not to be one, or null when the surface exposes no authoritative marker. NULL on every post-purchase line, and never `true` onsite — `/cart.js` does not list bundle component lines at all. - `igUpsell` boolean, nullable, required: True when the line was added by an Intelligems upsell, false when known not to be one, or null when the surface exposes no authoritative marker. - `tags` string[]: The line product's Shopify tags, hydrated ONLY when an evaluated rule targets on tags — absent otherwise. Absent means 'not looked up' and an empty array means 'looked up, none'; the two are never interchangeable, and a rule reading an absent value must fail loudly rather than treat it as no tags. - `collections` string[]: Shopify collection GIDs the line product belongs to, hydrated ONLY when an evaluated rule targets on collections — absent otherwise. Bare numeric collection ids are accepted and promoted to GID form on the way in. Same absent-vs-empty rule as `tags`. - `title` string: Product title at purchase time, when available. - `vendor` string: Product vendor at purchase time, when available. - `productType` string: Shopify product type at purchase time, when available. - `sellingPlanId` string: Shopify selling-plan GID (gid://shopify/SellingPlan/) when the line was purchased on a subscription. - `discountAllocations` object[]: Line-level discount allocations applied to this line, when any. - `amount` integer, required: Discount amount allocated to the line, in integer minor units of the order's currency. - `title` string: Discount title or code as shown on the order, when available. - `pageProduct` object, nullable, required: The product a PDP placement is rendered on. Populated for onsite product-page placements only; null everywhere else. - `productId` string, required: Shopify product GID of the product being viewed (gid://shopify/Product/). The bare numeric id the Shopify admin shows is accepted and promoted to GID form on the way in; anything that is neither is rejected. - `handle` string, required: Shopify product handle (URL slug) of the product being viewed. - `targeting` object, nullable: Theme product facts used for onsite product targeting. Null when the theme has no product data; product-targeted branches then do not match. Absent from clients that predate the field; serving then reads the facts from Shopify when the rule targets the product. - `tags` string[], required - `collectionIds` integer[], required - `inventory` integer, required - `lowestVariantPrice` integer, required - `customer` object, nullable, required: Minimal identified-customer context, or null for guests. PII-MINIMAL GUARANTEE: this object carries ids, counts, and money aggregates ONLY — no email, name, phone, or address field may ever be added here. That is a contract property, not a data-availability accident; richer profile data is fetched at rule runtime via sdk.getCustomer(). - `id` string, required: Shopify customer GID (gid://shopify/Customer/). - `ordersCount` integer, nullable, required: Number of orders this customer has placed, or null when the surface did not supply it — checkout supplies it for a verified buyer when the app's protected-customer-data grant covers it; onsite and post-purchase never do. Integer, >= 0, when present. Null-check it, or use sdk.getCustomer() for a count that does not depend on the grant. - `amountSpent` object: Lifetime spend aggregate, when known. - `amount` integer, required: Lifetime amount spent in integer minor units of `currency`. - `currency` string, required: ISO-4217 currency code `amount` is denominated in. - `shipping` object, required: Shipping-incentive context. Required — 'not-applicable' is expressed in-band via its state field, never by omitting the object. - `state` 'resolved' | 'assumed' | 'not-applicable' | 'unavailable', required: 'resolved' = thresholds are known facts for this visitor; 'assumed' = best-effort defaults that may be wrong, so treat them as a hint rather than a fact when steering; 'not-applicable' = the store has no shipping incentive here, and the order may not be shipping at all; 'unavailable' = the shipping facts could not be read before the serving deadline (a Shopify read failed or timed out), so no threshold field is present and nothing is known — never read it as 'no incentive'. - `currency` string, required: ISO-4217 currency code the threshold fields are denominated in. Always present, even when state is 'not-applicable'. - `freeShippingThreshold` integer: Cart subtotal at which shipping becomes free, in integer minor units — pre-resolved to the visitor's assigned variation's threshold. Absent when there is no free-shipping incentive. - `remainingToFreeShipping` integer, nullable: How much more the visitor must add to qualify for free shipping, in integer minor units. 0 = already qualifies; absent or null = unresolvable. - `tiers` object[]: Tiered incentive ladder in ascending threshold order, when the store runs tiered incentives. - `threshold` integer, required: Cart subtotal at which this tier unlocks, in integer minor units of the shipping context's currency. - `label` string, required: Shopper-facing label for the tier (e.g. 'Free shipping'). - `delivery` object: The delivery options Shopify computed for this checkout, as observed facts rather than merchant settings. Present only at checkout, and only once Shopify has computed options (an address or a pickup selection exists); absent onsite, post-purchase, and on first render. Present under every state, including 'not-applicable' for local pickup. - `isLocalPickup` boolean, required: True when every selected delivery option is a pickup option — the buyer is not shipping anything. - `selected` object: The buyer's currently selected option, when exactly one delivery group has a selection. Absent before the buyer picks, and when multiple groups (a subscription plus a one-time purchase) select different options — read `options` then. - `title` string: Shopper-facing option title, when Shopify reports one. - `isPickup` boolean, required: True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate. - `selected` boolean, required: True when this is the buyer's currently selected option in its delivery group. - `cost` integer: The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost. - `currency` string: ISO-4217 currency code of `cost`. Absent with it. - `carrierName` string: Carrier presenting the option, when Shopify reports one. - `transitDays` object: Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only. - … - `options` object[], required: Every option Shopify computed, flattened across delivery groups, in Shopify's order. A zero-cost non-pickup option means the buyer already qualifies for free shipping. - `title` string: Shopper-facing option title, when Shopify reports one. - `isPickup` boolean, required: True for a pickup option (pickup point or pickup location) rather than a shipping rate. Pickup options carry no cost and no transit estimate. - `selected` boolean, required: True when this is the buyer's currently selected option in its delivery group. - `cost` integer: The option's cost after shipping discounts, in integer minor units of `currency`. 0 = free. Absent on pickup options, which have no cost. - `currency` string: ISO-4217 currency code of `cost`. Absent with it. - `carrierName` string: Carrier presenting the option, when Shopify reports one. - `transitDays` object: Estimated time in transit in whole days, when Shopify reports one — `min` rounded down, `max` rounded up. Shipping options only. - … - `country` string, nullable: OPTIONAL. ISO-3166-1 alpha-2 code of the market this request should be evaluated in, e.g. 'CA'. Omit it (or send null) and the platform evaluates in its default market, 'US'. Name it whenever the cart is denominated in a non-shop currency, so the catalog reads run in the same market the money does. - `cartFingerprint` string: Opaque client-supplied fingerprint of the cart state this request was built from. The engine echoes it verbatim on the result envelope so the rendering surface can compare and discard late results. - `context` object: Optional evaluation context override. When absent the harness supplies a representative preview context. - `isPreview` boolean, required: True when the evaluation is a preview (editor/test-lab) run rather than live traffic. - `slotsNeeded` integer, required: How many recommendation slots the placement wants filled. Non-negative integer, at most 50 — ZERO is reachable, because a placement can resolve to no slots, so a rule must answer zero with an empty envelope before it reads anything. - `excludeOutOfStock` boolean, required: The rule's out-of-stock setting. When true, every SDK catalog read and product recommendation drops products with no variant for sale, so rule code never filters stock itself. Defaults to true, the rule setting's own default. A read that passes its own `excludeOutOfStock` overrides it. - `evaluatedAt` integer: Optional author-pinned evaluation instant, epoch milliseconds UTC. When absent the harness stamps the publish job's own instant. Pin it to make a time-dependent scenario stable: a case like 'a 30-day supply ordered 34 days ago' needs both ends fixed, or its expected verdict drifts with the calendar. - `description` string: Display copy for scenario pickers, phrased for a merchant (e.g. 'A cart that matches your matching cover-ups rule'). Absent on scenarios authored before display copy existed. - `targetBranchId` string, nullable: The branch this scenario is designed to fire: the graph branch node id (=== the attempt() base label). Null marks the nothing-matches scenario whose cart clears no branch; absent means unannotated (typically hand-authored). - `origin` 'authored' | 'generated': 'authored' = written by a person or authoring agent alongside the rule; 'generated' = produced by the scenario-generation service. Regeneration replaces only 'generated' scenarios and never clobbers authored ones. - `status` 'ready' | 'pending', required - `branchIds` string[], required ## Other responses - `429`: Too Many Requests --- [API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)