Routing API

The Routing API resolves URL paths to content with automatic variant selection and translation resolution. This is the primary API for building headless frontends.

Queries

resolveRoute

Resolve a URL path to fully rendered content.


query ResolvePage($path: String!, $locale: String, $contexts: JSON) {
  resolveRoute(path: $path, locale: $locale, contexts: $contexts) {
    record {
      id
      modelKey
      naturalKey
      metadata
    }
    variant {
      id
      variantKey
    }
    content {
      fields {
        key
        type
        label
        value
        order
      }
    }
    resolvedWith {
      locale
      contexts
    }
  }
}

Parameters:

Parameter	Type	Description
`path`	String!	URL path to resolve (e.g., “/about”, “/products/shirt”)
`locale`	String	Locale for translations (e.g., “en-US”, “ja-JP”)
`contexts`	JSON	Context dimensions for variant selection
`referenceOptions`	ReferenceResolutionOptionsInput	Control reference resolution
`versionSelection`	VersionSelectionInput	Version selection (dev keys only)

Example with contexts:


query ResolveWithContext {
  resolveRoute(
    path: "/products/premium-jacket"
    locale: "en-GB"
    contexts: {
      market: "uk"
      device: "mobile"
    }
  ) {
    record { id naturalKey }
    content { fields { key value } }
  }
}

getEntityRoutes

Get routes for a single entity with optional child routes.


query GetProductRoutes($modelKey: String!, $naturalKey: String!) {
  getEntityRoutes(input: {
    modelKey: $modelKey
    naturalKey: $naturalKey
    includeChildren: true
    childModelKey: "shopify-product-variant"
  }) {
    naturalKey
    found
    entityId
    metadata
    routes {
      path
      isCanonical
      aliasStrategy
      canonicalPath
      contexts
    }
    children {
      naturalKey
      routes {
        path
        contexts
      }
    }
  }
}

Input parameters:

Parameter	Type	Description
`modelKey`	String!	Entity model key
`naturalKey`	String!	Entity natural key (slug/handle)
`includeChildren`	Boolean	Include child entity routes
`childModelKey`	String	Filter children by model
`childContexts`	JSON	Filter children by context
`country`	String	Country for URL generation
`locale`	String	Locale for URL generation

getEntitiesRoutes

Batch lookup routes for multiple entities. Efficient for product listing pages.


query GetProductListRoutes($handles: [String!]!) {
  getEntitiesRoutes(input: {
    modelKey: "shopify-product"
    naturalKeys: $handles
    country: "US"
    locale: "en"
  }) {
    results {
      naturalKey
      found
      entityId
      metadata
      routes {
        path
        isCanonical
        contexts
      }
    }
    notFound
  }
}

Use case: Get URLs for product cards on a collection page.

resolveEntities

Batch resolve full entity content. Use when you need complete content for multiple entities at once.


query ResolveProducts($naturalKeys: [String!]!) {
  resolveEntities(input: {
    modelKey: "shopify-product"
    naturalKeys: $naturalKeys
    locale: "en-US"
    contexts: { market: "us" }
  }) {
    results {
      naturalKey
      found
      resolution {
        record { id naturalKey }
        content {
          fields { key type value }
        }
      }
    }
    notFound
    resolvedWith {
      locale
      contexts
    }
  }
}

Response Types

ResolvedRoute

The main response from resolveRoute:


type ResolvedRoute {
  record: ResolvedEntityRecord!    # Entity identity
  variant: ResolvedEntityVariant!  # Selected variant
  content: ResolvedContent!        # Renderable content
  resolvedWith: ResolutionContextOutput!  # Resolution context
}

ResolvedContent

Content ready for rendering:


type ResolvedContent {
  fields: [ResolvedField!]!         # All renderable fields
}

ResolvedField

Individual resolved field:


type ResolvedField {
  key: String!           # Field key
  type: String!          # Field type or modelKey
  label: String          # Display label
  required: Boolean      # Is required
  value: JSON            # Resolved value
  order: Int             # Field order
}

Context Resolution

The contexts parameter controls variant selection:


resolveRoute(
  path: "/products/jacket"
  contexts: {
    market: "uk"        # Market context (from shopify-market)
    device: "mobile"    # Device type
    segment: "vip"      # Customer segment
  }
)

Common context keys:

Key	Description	Example Values
`market`	Geographic market	”us”, “uk”, “de”
`device`	Device type	”desktop”, “mobile”, “tablet”
`locale`	Language/region	”en-US”, “ja-JP”
`segment`	Customer segment	”vip”, “wholesale”

Reference Resolution

Control how nested references are resolved:


resolveRoute(
  path: "/about"
  referenceOptions: {
    maxDepth: 3           # Limit nesting depth
    resolveMedia: true    # Resolve media references
    resolveEntities: true # Resolve entity references
  }
)

Version Selection (Dev Keys)

Preview unpublished content with development keys:


resolveRoute(
  path: "/new-page"
  versionSelection: {
    versionState: LATEST  # Get latest draft
  }
)

Or fetch a specific version:


resolveRoute(
  path: "/about"
  versionSelection: {
    versionState: SPECIFIC
    versionId: "ver_abc123"
  }
)

Examples

Basic Page Resolution


query HomePage {
  resolveRoute(path: "/", locale: "en-US") {
    record { naturalKey }
    content {
      fields {
        key
        value
      }
    }
  }
}

Product Page with Market Context


query ProductPage($handle: String!, $market: String!) {
  resolveRoute(
    path: "/products/$handle"
    locale: "en-US"
    contexts: { market: $market }
  ) {
    record {
      naturalKey
      metadata  # Contains Shopify synced data
    }
    content {
      fields {
        key
        type
        value
      }
    }
  }
}

Collection with Product URLs


query CollectionPage($handle: String!) {
  # Get collection content
  collection: resolveRoute(path: "/collections/$handle") {
    record { naturalKey }
    content { fields { key value } }
  }
 
  # Get product URLs for the collection
  productRoutes: getEntitiesRoutes(input: {
    modelKey: "shopify-product"
    naturalKeys: ["product-1", "product-2", "product-3"]
  }) {
    results {
      naturalKey
      routes { path isCanonical }
    }
  }
}

404 Handling

When a route is not found, resolveRoute returns null:


const { data } = await client.query({
  query: RESOLVE_ROUTE,
  variables: { path: "/unknown-page" }
});
 
if (!data.resolveRoute) {
  // Render 404 page
  return <NotFoundPage />;
}