Note

    agentic-endpoints

    Feature-flagged catalog and checkout-prep API contracts for external agents.

    Document Metadata

    • title: Agentic Commerce API Endpoints
    • description: Feature-flagged catalog and checkout-prep API contracts for external agents.
    • status: evolving
    • lastUpdated: "2026-04-09 14:11 ET (America/New_York)"
    • owner: Engineering

    Agentic Commerce API Endpoints These endpoints provide a controlled API surface for external agents to retrieve catalog context and

    Agentic Commerce API Endpoints

    These endpoints provide a controlled API surface for external agents to retrieve catalog context and prepare checkout handoff.

    Runtime Gates

    • SHOPIFY_AGENTIC_ENABLED:
      • true enables /api/agents/* routes
      • false returns 403 (AGENTIC_DISABLED).
    • SHOPIFY_AGENTIC_CATALOG_MODE:
      • readonly allows catalog retrieval only
      • checkout allows checkout preparation route.
    • SHOPIFY_AGENTIC_ALLOWED_ORIGINS:
      • comma-separated origin allowlist (for example: https://agent.example.com,https://partner.example.com)
      • when set, non-allowlisted origins receive 403 (AGENTIC_ORIGIN_FORBIDDEN).
    • SHOPIFY_AGENTIC_STOREFRONT_ACCESS_TOKEN (optional):
      • if set, agent routes use this token for Storefront API calls
      • if empty, routes fall back to SHOPIFY_STOREFRONT_ACCESS_TOKEN.

    Buyer IP Forwarding

    When using a private Storefront token (shpat_), the Storefront client forwards buyer IP using incoming request headers in this priority order:

    1. Shopify-Storefront-Buyer-IP
    2. x-forwarded-for (first value)
    3. x-real-ip
    4. cf-connecting-ip
    5. fly-client-ip
    6. x-vercel-forwarded-for

    This aligns agent requests with Shopify guidance for private token traffic attribution and throttling behavior.

    GET /api/agents/catalog

    Read-only catalog and policy context for agent retrieval.

    Query params:

    • query or q (optional): search query string
    • limit (optional): max products returned (1-50, default 10)
    • pathname (optional): explicit storefront pathname used to resolve the approved Shopify Markets launch contract for localized pricing/context (for example /en-fr/search)

    Market-context rules:

    • External callers may localize catalog responses by supplying a supported storefront pathname or by sending a referer on a supported localized storefront path.
    • Internal Shopify routing headers such as x-market-locale-prefix and x-market-original-pathname are ignored on /api/agents/* requests and must not be treated as a public API contract.
    • Unsupported locale-like path hints (for example /en-ca/search), whether supplied explicitly as pathname or inferred from referer, return 400 / INVALID_PATHNAME instead of silently falling back to the primary market.

    Success response (200):

    • mode
    • query
    • count
    • products[]:
      • id, handle, title, description
      • productType, vendor
      • availableForSale
      • price (minAmount, maxAmount, hasRange, displayLabel, currencyCode)
      • productUrl (resolved against the approved localized market path when a supported localized pathname or referer is supplied)
      • image
      • variants[] (id/title/availability/price/options/url, preserving the same localized product base URL)
    • policies[] (title/handle/url, preserving the same localized market path when applicable)
    • generatedAt

    Error responses:

    • 400 - INVALID_QUERY, INVALID_PATHNAME
    • 403 - AGENTIC_DISABLED, AGENTIC_ORIGIN_FORBIDDEN
    • 500 - AGENT_CATALOG_UNAVAILABLE

    POST /api/agents/checkout

    Creates a checkout-ready Shopify cart from agent-selected line items.

    Request body:

    {
  "pathname": "/en-fr/products/example-product",
  "lines": [
    {
      "merchandiseId": "gid://shopify/ProductVariant/1234567890",
      "quantity": 1
    }
  ]
}

    Validation:

    • lines is required.
    • Line count must be 1 to 25.
    • merchandiseId must be non-empty.
    • quantity must be an integer between 1 and 25.
    • pathname is optional, but when supplied it must either be a primary-domain path (for example /search) or one of the supported localized path families under the approved Shopify Markets launch contract.

    Market-context rules:

    • Localized checkout preparation uses the same path-based market-resolution contract as the catalog route.
    • Unsupported locale-like path hints, whether explicit pathname values or localized referer fallbacks, return 400 / INVALID_PATHNAME instead of silently falling back to the primary market.
    • Internal Shopify routing headers are ignored on external /api/agents/* calls.

    Success response (200):

    • mode (checkout)
    • checkout:
      • cartId
      • checkoutUrl
      • totalQuantity
      • subtotalAmount
      • totalAmount
    • generatedAt

    Error responses:

    • 400 - INVALID_JSON, INVALID_LINES, INVALID_PATHNAME
    • 403 - AGENTIC_DISABLED, AGENTIC_ORIGIN_FORBIDDEN, AGENTIC_CHECKOUT_DISABLED
    • 500 - AGENT_CHECKOUT_UNAVAILABLE

    Provenance