---
title: "Evaluate Strategy"
method: POST
path: "/api/public/strategy/evaluate"
---

# Evaluate Strategy

`POST /api/public/strategy/evaluate`

## Request

- Base URL: `https://start.aftersell.app`
- URL: `https://start.aftersell.app/api/public/strategy/evaluate`
- Auth: API key in header `X-Strategy-Api-Key`

Evaluate a strategy against provided context to return the desired experience.

## Request body

- EvaluateRequest
  - `shopDomain` string, required: Your store's permanent domain
  - `strategyId` string, required: The strategy ID to evaluate (a single 24-char hex MongoDB ObjectId)
  - `surface` 'checkout' | 'post_purchase' | 'thank_you' | 'custom' | 'cart' | 'pdp': Optional surface the evaluation is running on. Recorded for tracing and reporting.
  - `context` object, required
    - `products` ContextProduct[]: Products to evaluate the strategy against. Optional — omit or pass `[]` to evaluate context-only rules (e.g. cart, customer, session, datetime predicates) such as a curated collection for an empty cart. Product-scoped predicates fall through to `false` when no products are supplied.
      - `productId` string, required: Shopify GID format: `gid://shopify/Product/{id}`
      - `variantId` string: Shopify GID format: `gid://shopify/ProductVariant/{id}`
      - `quantity` number: Item quantity (non-negative integer)
      - `price` number: Unit price in dollars (non-negative)
      - `handle` string: Product handle/slug
      - `title` string: Product title
      - `vendor` string: Product vendor name
      - `productType` string: Product type
      - `tags` string[]: Product tags
      - `collections` string[]: Collection GIDs the product belongs to
      - `sellingPlan` 'subscription' | 'one-time': Selling plan type
      - `metafields` Metafield[]: Product metafields for predicate matching. Used for evaluation only — never returned in the response.
        - `namespace` string, required: Metafield namespace
        - `key` string, required: Metafield key
        - `value` string, required: Metafield value
    - `cartToken` string: Shopify cart token. Either `cartToken` or `checkoutToken` must be provided.
    - `checkoutToken` string: Shopify checkout token. Either `cartToken` or `checkoutToken` must be provided.
    - `sessionId` string: Optional session identifier for tracking and tracing
    - `cart` CartContext
      - `subtotal` number: Cart subtotal in store-currency major units (e.g. dollars), consistent with product `price`. The value is compared verbatim against `cart_subtotal` rule thresholds — no unit conversion is applied — so send the same units you author your rules in.
      - `itemCount` number: Total item quantity across all lines
      - `lineCount` number: Number of distinct line items
      - `attributes` object: Cart attributes as a key-value map
      - `notes` string: Cart note
    - `customer` CustomerContext
      - `customerId` string: Shopify Customer GID
      - `tags` string[]: Customer tags
      - `countryCode` string: Customer billing country code
      - `provinceCode` string: Customer billing province code
      - `locale` string: Customer locale
      - `orderCount` number: Number of orders placed
      - `totalSpent` number: Lifetime spend in store currency
      - `acceptsMarketing` boolean: Whether the customer accepts marketing
    - `session` SessionContext
      - `landingUrl` string: Raw landing URL (e.g. window.location.href). Matched by the `landing_url` predicate via case-insensitive substring/equality - use this to target a specific campaign or channel by matching a parameter embedded in the URL.
      - `currencyCode` string: Store currency code
      - `shippingCountryCode` string: Shipping destination country code
      - `shippingProvinceCode` string: Shipping destination province code
      - `shippingMethod` string: Selected shipping method name
    - `visitorId` string: Optional viewer key used to resolve the shopper's recently-viewed history. This is not a Hermes session id, and it does not satisfy the `cartToken` / `checkoutToken` requirement. Fails open — an invalid value is ignored rather than rejected.
    - `localization` LocalizationContext: Buyer localization, used to select Shopify-computed contextual prices on multi-currency stores. Every field is optional and fails open: a malformed value is ignored rather than rejected, and pricing falls back to the shop currency.
      - `country` string: Buyer's country as an ISO 3166-1 alpha-2 code. Validated against Shopify's CountryCode enum and used for Admin API contextual pricing. Case-insensitive.
      - `currency` string: Buyer's presentment currency as an ISO 4217 three-letter code. Case-insensitive. Used as a targeting input only: it fills `context.session.currencyCode`, the value the `store_currency_code` rule predicate matches against, and only when the caller has not already supplied one. It does not set the `currencyCode` returned on recommended products — that follows Shopify contextual pricing, which is selected by `localization.country`, and otherwise falls back to the shop's own currency. Unlike `country`, this value is only checked for being three letters; an unrecognised code is accepted and simply matches no rule.
      - `language` string: Buyer's language tag, e.g. `en` or `en-AU`. Reserved for future translation support.

## Response `200`

Evaluation successful

- EvaluateResponse
  - `success` boolean: Whether the evaluation succeeded
  - `products` RecommendedProduct[]: Fully enriched recommended products
    - `productId` string: Shopify Product GID
    - `handle` string: Product handle/slug
    - `title` string: Product title
    - `vendor` string: Vendor name
    - `productType` string: Product type
    - `price` string: Lowest variant price as a dollar-amount string
    - `compareAtPrice` string, nullable: Compare-at price, or null if not set
    - `currencyCode` string: ISO 4217 currency of the product-level `price` and `compareAtPrice` rollup: the buyer's market currency when contextual pricing was resolved (see `context.localization`), otherwise the shop currency. May be absent, in which case fall back to your own presentment currency.
    - `availableForSale` boolean: Whether the product is available for purchase
    - `description` string: Product description
    - `url` string: Relative product URL
    - `tags` string[]
    - `collectionIds` string[]
    - `images` ProductImage[]
      - `src` string: Image URL
      - `altText` string: Image alt text (may be absent)
      - `position` number: Image sort position
    - `variants` ProductVariant[]
      - `variantId` string: Shopify ProductVariant GID
      - `title` string: Variant title
      - `price` string: Variant price as a dollar-amount string
      - `compareAtPrice` string, nullable: Variant compare-at price, or null
      - `currencyCode` string: ISO 4217 currency of `price` and `compareAtPrice`: the buyer's market currency when contextual pricing was resolved (see `context.localization`), otherwise the shop currency. May be absent, in which case fall back to your own presentment currency.
      - `availableForSale` boolean: Whether this variant is available
      - `sku` string: Variant SKU (may be absent)
      - `image` object: Variant-specific image, used to swap the card image on variant select. Absent when the variant has no distinct image — fall back to the product image.
        - `src` string
      - `selectedOptions` object[]: Array of option name/value pairs (may be absent)
        - `name` string
        - `value` string
  - `evaluationId` string: Unique identifier for this evaluation. Echo it back as a line item property (e.g. `__as_offer_id`) when a shopper adds a recommended product, so the resulting order attributes back to this specific evaluation in AfterSell reporting. Present on successful evaluations; absent on error responses that short-circuit before evaluation.
  - `resolution` object
    - `strategyId` string, nullable: The strategy that produced the result. `null` on any error response, and on a successful evaluation where no strategy matched the requested ID for this shop; otherwise echoes the requested `strategyId`.
    - `matchedRuleIds` string[]: IDs of rules that matched
    - `selectionMethod` string: Always `rules_engine`
    - `fallbackUsed` boolean: Whether fallback logic was used
  - `meta` object
    - `servedFromCache` boolean: Whether product data was served from cache
    - `processingTimeMs` number: Server-side processing time in milliseconds
    - `data` object: Key-value pairs emitted by matched rules with `key_value` outputs. Values are always strings. Always present; may be an empty object. Keys from the first matching rule win.
    - `explanation` string: Optional debug explanation (may be absent)
  - `errors` ApiError[]: Present only when errors occur
    - `code` string: Error code
    - `message` string: Human-readable error description

## Other responses

- `400`: Validation error — missing required fields, invalid ObjectId format, or neither `cartToken` nor `checkoutToken` provided
- `401`: Authentication error — missing or invalid API key, key not configured for shop, or unrecognized shop domain. No further detail is returned in the response body.
- `403`: Authorization error — Strategy is not enabled for this shop.
- `500`: Server error — shop configuration issue or unexpected internal error

## Changes

- **2026-11-03** `fc01854f97fd`: 5 warning, 19 info
  - removed the request property `context/session/utmCampaign`
  - removed the request property `context/session/utmContent`
  - removed the request property `context/session/utmMedium`
  - removed the request property `context/session/utmSource`
  - …20 more

[Operation history](https://skmtc.dev/aftersell/apis/aftersell-strategies-api/changes/api/public/strategy/evaluate/post.md)

---

[API](https://skmtc.dev/aftersell/apis/aftersell-strategies-api.md) - [All operations](https://skmtc.dev/aftersell/apis/aftersell-strategies-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aftersell/apis/aftersell-strategies-api/revisions/fc01854f97fd?raw)
