Operation reference

Runtime context

GRAPHQL Runtime read:settings

Verify the selected store, normal storefront, request, session, consent, localization, market, and currency. B2B storefront domains are hosted-only and reject Storefront GraphQL.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token returned by visitorSessionCreate.
`X-Customer-Access-Token`	optional	Customer access token returned by customerLogin.

query RuntimeContext {
  runtimeContext {
    store { id name currency timezone primaryDomain }
    storefront { id name kind locale domain currentDomain }
    request { host }
    session { present source expiresAt }
    customer { authenticated id authSurface }
    consent {
      required
      given
      categories
      timestamp
      country
      banner {
        enabled
        showTo
        countries
        categories { analytics marketing personalization }
      }
    }
    localization { locale baselineLocale country resolvedBy }
    currency { code name symbol taxIncluded resolvedBy }
    b2b {
      state
      companyId
      companyLocationId
      contactId
      catalogId
      catalogSource
      role
      canPlaceOrders
    }
  }
}

Variables

Sample variables

{}

Create the visitor session token used by headless clients for consent, cart, and session-scoped state. Rejected with SESSION_ALREADY_ACTIVE when a valid X-Tringify-Session-Token is already presented — use visitorSessionRenew to extend an existing session.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.

mutation VisitorSessionCreate {
  visitorSessionCreate {
    token
    expiresAt
  }
}

Variables

Sample variables

{}

Customer login

GRAPHQL Customers / Mutations write:customer

Authenticate with the code from customerAuthCodeSend (purpose LOGIN). Put the returned token in X-Customer-Access-Token. The same flow works for EMAIL and PHONE providers — the code is the only credential.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token whose consent/cart state should be linked during login.

mutation Login($input: CustomerLoginInput!) {
  customerLogin(input: $input) {
    customerAccessToken { accessToken expiresAt }
    userErrors { code message }
  }
}

Variables

Sample variables

{
  "input": {
    "provider": "EMAIL",
    "code": "123456",
    "email": "ada@example.com"
  }
}

Customer context

GRAPHQL Customers read:customer

Read the authenticated customer visible to this GraphQL request.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Customer-Access-Token`	required	Customer access token returned by customerLogin.

query CustomerContext {
  isLoggedIn
  customer {
    id
    email
    displayName
    acceptsMarketing
  }
}

Variables

Sample variables

{}

Set language

GRAPHQL Runtime / Localization write:session

Persist a storefront-served language choice on the visitor session. Query runtimeContext afterward to verify localization.resolvedBy becomes choice.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Tringify-Session-Token`	required	Visitor session token returned by visitorSessionCreate.

mutation SetLanguage($code: String!) {
  setLanguage(code: $code) {
    languageCode
    currencyCode
    response {
      code
      message
      locale
      params { key value }
    }
  }
}

Variables

Sample variables

{
  "code": "en"
}

Give consent

GRAPHQL Runtime / Consent write:session

Persist consent categories on the visitor session used by both headless GraphQL and hosted CTX.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Tringify-Session-Token`	required	Visitor session token returned by visitorSessionCreate.

mutation ConsentGive($categories: [String!]!) {
  consentGive(categories: $categories) {
    required
    given
    categories
    timestamp
    country
    banner {
      enabled
      showTo
      countries
      categories { analytics marketing personalization }
    }
    response {
      code
      message
      locale
      params { key value }
    }
  }
}

Variables

Sample variables

{
  "categories": ["analytics"]
}

Withdraw consent

GRAPHQL Runtime / Consent write:session

Withdraw consent on the current visitor session and verify runtimeContext.consent afterward.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the selected storefront/API version.
`X-Tringify-Session-Token`	required	Visitor session token returned by visitorSessionCreate.

mutation ConsentWithdraw {
  consentWithdraw {
    required
    given
    categories
    timestamp
    country
    response {
      code
      message
      locale
      params { key value }
    }
  }
}

Variables

Sample variables

{}

Product price runtime currency

GRAPHQL Catalog / Normal storefront read:products

On a normal storefront, compare runtimeContext.currency with product price currency to verify product pricing reads the resolved runtime currency.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale/market/currency choice.

query ProductPriceRuntimeCurrency($first: Int) {
  runtimeContext {
    storefront { kind domain currentDomain }
    localization { locale resolvedBy }
    currency { code resolvedBy }
  }
  products(first: $first) {
    edges {
      node {
        id
        slug
        title
        price {
          current { amount currencyCode currencySymbol formatted }
          regular { amount currencyCode currencySymbol formatted }
          sale { amount currencyCode currencySymbol formatted }
          onSale
        }
      }
    }
  }
}

Variables

Sample variables

{
  "first": 1
}

Cart context

GRAPHQL Cart read:cart

Read the current cart for the supplied visitor/customer context on a normal storefront. The cart also carries evaluated discounts: discounts (eligible automatics + applied-code outcomes), advertisedCoupons (merchant show_in_cart opt-ins only), discountNudges (near-miss automatics), and discountTotal.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

query CartContext {
  runtimeContext {
    storefront { kind domain currentDomain }
    session { present source }
    customer { authenticated id authSurface }
  }
  cart {
    totalItems
    uniqueItems
    coupons
    items { productId variantId quantity }
  }
}

Variables

Sample variables

{}

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version with read:menus.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale choice.

query NavigationMenu($handle: String!, $first: Int) {
  runtimeContext {
    storefront { kind domain currentDomain }
    localization { locale baselineLocale resolvedBy }
  }
  navigationMenu(handle: $handle) {
    id
    handle
    name
    itemCount
    rootItems(first: $first) {
      totalCount
      pageInfo { hasNextPage endCursor }
      edges {
        cursor
        node {
          id
          menuId
          parentId
          title
          url
          linkType
          linkLabel
          openInNewTab
          childCount
        }
      }
    }
  }
}

Variables

Sample variables

{
  "handle": "main-menu",
  "first": 50
}

Add to cart

GRAPHQL Cart / Mutations write:cart

Add a line to the cart. properties sets declared cart line properties (keys are "namespace.key" from the store's cart line definitions); unknown keys and invalid values return userErrors. Properties are part of line identity — the same product with different properties is a separate line with its own lineId.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation AddToCart($input: AddToCartInput!) {
  addToCart(input: $input) {
    cart {
      totalItems
      uniqueItems
      items { productId variantId quantity lineId properties { key value } }
    }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "quantity": 1,
    "properties": [{ "key": "custom.engraving", "value": "MOM" }]
  }
}

Update cart item

GRAPHQL Cart / Mutations write:cart

Set a line's quantity (0 removes it). Target a specific line with lineId — required for lines with properties; bare productId/variantId targeting matches only the property-less line.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation UpdateCartItem($input: UpdateCartItemInput!) {
  updateCartItem(input: $input) {
    cart { items { productId quantity lineId properties { key value } } }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "quantity": 2,
    "variantId": null
  }
}

Remove from cart

GRAPHQL Cart / Mutations write:cart

Remove a line. lineId targets a specific line — required for lines with properties; bare productId/variantId matches only the property-less line.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation RemoveFromCart($productId: Int!, $variantId: Int, $lineId: String) {
  removeFromCart(productId: $productId, variantId: $variantId, lineId: $lineId) {
    cart { totalItems items { productId quantity lineId } }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "productId": 1,
  "variantId": null
}

Clear cart

GRAPHQL Cart / Mutations write:cart

Empty the cart. Returns ClearCartPayload { cart, userErrors }.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation ClearCart {
  clearCart {
    cart {
      totalItems
      uniqueItems
      items { productId variantId quantity }
    }
    userErrors {
      code
      field
      message
    }
  }
}

Variables

Sample variables

{}

Cart userErrors reference

GRAPHQL Cart / Mutations write:cart

Recoverable cart-mutation failures are returned in the payload userErrors array (code, field, message), never as top-level GraphQL errors. Codes: CART_PRODUCT_UNAVAILABLE (product missing/inactive/not in this channel), CART_VARIANT_REQUIRED (variable product needs a variantId), CART_VARIANT_INVALID (variantId not found / wrong product), CART_VARIANT_NOT_ALLOWED (simple product given a variantId), CART_QUANTITY_INVALID (addToCart quantity must be > 0; updateCartItem quantity must be >= 0). Messages are localized to the resolved visitor locale. System / auth / transport / invalid-GraphQL failures remain top-level errors. Stock / inventory / order-limit validation is not yet applied at add-to-cart.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation AddToCartInvalidQuantity($input: AddToCartInput!) {
  addToCart(input: $input) {
    cart { totalItems }
    userErrors {
      code
      field
      message
    }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "quantity": 0
  }
}

Product reviews

GRAPHQL Reviews / Queries read:products

Approved reviews for a product, newest first, with the rating aggregate. Reviewer names arrive ALREADY shaped by the store's reviewer_display setting; images are the EXIF-stripped review-media CDN JPEGs. Returns only approved reviews — moderation states never cross this API.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query ProductReviews($slug: String!) {
  product(slug: $slug) {
    id
    title
    reviewStats {
      averageRating
      totalCount
    }
    reviews(first: 10, sort: NEWEST) {
      edges {
        node {
          id
          rating
          title
          content
          reviewerName
          verifiedPurchase
          helpfulCount
          createdAt
          images { url altText }
        }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Variables

Sample variables

{
  "slug": "your-product-slug"
}

Review statistics

GRAPHQL Reviews / Queries read:products

The star aggregate for a product — average, total, and per-star distribution. Use it for grid badges and the review-summary block without fetching review items.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query ReviewStats($slug: String!) {
  product(slug: $slug) {
    reviewStats {
      averageRating
      totalCount
      verifiedPurchases
      reviewsWithImages
      ratingBreakdown { oneStar twoStar threeStar fourStar fiveStar }
    }
  }
}

Variables

Sample variables

{
  "slug": "your-product-slug"
}

Submit a review

GRAPHQL Reviews / Mutations write:customer

Submit a product review — productId is required (reviews are product reviews, period). EVERY store review setting is enforced server-side: moderation mode, anonymous policy, rune-counted content lengths, require_purchase (verified_purchase derives from real order history and can never be set by the client), and the merchant's content filters (blocked words, URL/email blocking) which auto-reject at submit. The returned status reflects the store's moderation flow (pending vs approved vs rejected). reviewMediaIds attach photos uploaded through the review-media flow. Validation failures return registered codes in userErrors with params filled.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token — the guest identity reviews and photo claims bind to.
`X-Customer-Access-Token`	optional	Customer access token — required by stores with require_purchase enabled.

mutation SubmitReview($input: SubmitReviewInput!) {
  submitReview(input: $input) {
    review {
      id
      rating
      title
    }
    approved
    userErrors {
      code
      field
      message
    }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "rating": 5,
    "title": "Great product",
    "content": "Exactly as described — arrived fast and works perfectly.",
    "reviewerName": "Ada L.",
    "reviewerEmail": "ada@example.com"
  }
}

Vote review helpful

GRAPHQL Reviews / Mutations write:customer

Vote a review helpful/unhelpful. One vote per visitor (session or customer); voting again switches the vote. removeReviewVote clears it.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token (guest votes).
`X-Customer-Access-Token`	optional	Customer access token.

mutation VoteReview($reviewId: ID!, $vote: ReviewVote!) {
  voteReview(reviewId: $reviewId, vote: $vote) {
    success
    helpfulCount
  }
}

Variables

Sample variables

{
  "reviewId": "review-uuid",
  "vote": "HELPFUL"
}

Get wishlist

GRAPHQL Wishlist / Queries read:wishlist

The current visitor's wishlist (guest session or customer). enabled reflects the store's wishlist settings; guest wishlists honor the store's guest policy.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token (guest wishlist).
`X-Customer-Access-Token`	optional	Customer access token.

query Wishlist {
  wishlist {
    enabled
    itemCount
    items {
      productId
      variantId
      availableForSale
      product { title slug }
    }
  }
}

Variables

Sample variables

{}

Add to wishlist

GRAPHQL Wishlist / Mutations write:wishlist

Add a product (or specific variant) to the wishlist. toggleWishlist flips membership; removeFromWishlist removes.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token (guest wishlist).
`X-Customer-Access-Token`	optional	Customer access token.

mutation AddToWishlist($input: WishlistItemInput!) {
  addToWishlist(input: $input) {
    wishlist { itemCount }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "variantId": null
  }
}

Register a customer

GRAPHQL Customers / Mutations write:customer

Create a customer by proving the email/phone with the code from customerAuthCodeSend (purpose REGISTER). No password exists or ever will. Gated by the store's self-registration setting. Guest state (cart, wishlist, review photos) and any guest ORDERS on this email attach to the new account automatically.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation Register($input: CustomerRegisterInput!) {
  customerRegister(input: $input) {
    customer { id email }
    customerAccessToken { accessToken expiresAt }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "provider": "EMAIL",
    "code": "123456",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "L"
  }
}

Send a sign-in code

GRAPHQL Customers / Mutations write:customer

Step one of every customer auth flow: request a one-time code for an email or phone. The server derives whether this is a LOGIN (account exists) or REGISTER (new) and returns it as mode — your UI learns post-send which completion form to render; it is never asked to pre-know. Phone requires an active SMS/WhatsApp provider. There are no passwords anywhere on this API — the code IS the credential.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation SendCode($input: CustomerAuthCodeSendInput!) {
  customerAuthCodeSend(input: $input) {
    mode
    expiresAt
    userErrors {
      code
      field
      message
    }
  }
}

Variables

Sample variables

{
  "input": {
    "provider": "EMAIL",
    "email": "ada@example.com"
  }
}

Get a blog post

GRAPHQL Blog / Queries read:content

Fetch one published post by slug. Content is the rendered HTML body.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BlogPost($slug: String!) {
  blogPost(slug: $slug) {
    id
    title
    slug
    excerpt
    content
  }
}

Variables

Sample variables

{
  "slug": "hello-world"
}

List blog posts

GRAPHQL Blog / Queries read:content

Published posts, newest first; filter by category or tag slug, paginate with the cursor.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BlogPosts($first: Int, $categorySlug: String) {
  blogPosts(first: $first, categorySlug: $categorySlug) {
    edges {
      node {
        id
        title
        slug
        excerpt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Variables

Sample variables

{
  "first": 10
}

List blog categories

GRAPHQL Blog / Queries read:content

The category tree for navigation.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BlogCategories {
  blogCategories {
    id
    name
    slug
  }
}

Variables

Sample variables

{}

List comments on a post

GRAPHQL Blog / Queries read:content

Approved comments with one level of replies. Pending comments never appear here — and when the store's comments mode is DISABLED this returns an empty connection and commentCount reads zero everywhere (existing comments are hidden, not deleted; re-enabling restores them).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BlogComments($postSlug: String!, $first: Int) {
  blogComments(postSlug: $postSlug, first: $first) {
    edges {
      node {
        id
        authorName
        content
        createdAt
        replies {
          id
          authorName
          content
        }
      }
    }
    totalCount
  }
}

Variables

Sample variables

{
  "postSlug": "hello-world",
  "first": 50
}

Blog comment settings

GRAPHQL Blog / Queries read:content

Who may comment (disabled / all / registered) and whether new comments await moderation — read this before rendering a comment form. disabled turns the whole surface off: submissions are refused AND existing comments stop being served (hidden, not deleted).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BlogCommentSettings {
  blogCommentSettings {
    mode
    moderation
  }
}

Variables

Sample variables

{}

Add a blog comment

GRAPHQL Blog / Mutations read:content

Submit a comment. Guests supply authorName + authorEmail; logged-in customers (X-Customer-Access-Token) comment under their account identity and those fields are ignored. Gated by the comments mode; moderation may hold it before it renders.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation AddBlogComment($input: AddBlogCommentInput!) {
  addBlogComment(input: $input) {
    success
    userErrors {
      code
      field
      message
    }
    response {
      code
      message
    }
  }
}

Variables

Sample variables

{
  "input": {
    "postSlug": "hello-world",
    "content": "Great post!",
    "authorName": "Ada",
    "authorEmail": "ada@example.com"
  }
}

Get a page

GRAPHQL Content / Queries read:content

Fetch one published page by slug.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query GetPage($slug: String!) {
  page(slug: $slug) {
    id
    title
    slug
    content
  }
}

Variables

Sample variables

{
  "slug": "about-us"
}

Get a policy

GRAPHQL Content / Queries read:content

Fetch one published policy by slug (refund, privacy, terms...).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query GetPolicy($slug: String!) {
  policy(slug: $slug) {
    id
    title
    slug
    content
  }
}

Variables

Sample variables

{
  "slug": "privacy-policy"
}

Product by slug

GRAPHQL Catalog / Product detail read:products

Fetch a single product detail page by slug (direct-DB; base or locale-translated slug). Returns core fields, media, variants, options, price/priceRange, basic categories, and 'can buy 1 now' availability/purchaseState/notifyMeEligible. A non-visible/unresolvable slug returns null.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale/market/currency choice.

query ProductBySlug($slug: String!) {
  product(slug: $slug) {
    id
    slug
    title
    description
    productType
    vendor
    tags
    availableForSale
    inventoryStatus
    featuredImage { url altText }
    images { url altText }
    price {
      current { amount currencyCode currencySymbol formatted }
      regular { amount currencyCode currencySymbol formatted }
      sale { amount currencyCode currencySymbol formatted }
      onSale
    }
    priceRange { min { amount currencyCode } max { amount currencyCode } hasRange }
    options {
      attribute { slug name }
      options { option { label value } available }
    }
    variants {
      id
      title
      sku
      availableForSale
      inventoryStatus
      selectedOptions { attribute { slug name } option { label value } }
      price { current { amount currencyCode } onSale }
      image { url altText }
    }
    categories { id name slug }
  }
}

Variables

Sample variables

{
  "slug": "final-test-1"
}

Product by id

GRAPHQL Catalog / Product detail read:products

Fetch a single product detail page by internal id (direct-DB). Same shape as product(slug). A non-visible/unresolvable id returns null.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale/market/currency choice.

query ProductById($id: ID!) {
  productById(id: $id) {
    id
    slug
    title
    productType
    availableForSale
    inventoryStatus
    featuredImage { url altText }
    price { current { amount currencyCode } regular { amount currencyCode } onSale }
    priceRange { min { amount currencyCode } max { amount currencyCode } hasRange }
    variants {
      id
      title
      availableForSale
      selectedOptions { attribute { slug } option { label value } }
      price { current { amount currencyCode } }
    }
    categories { id name slug }
  }
}

Variables

Sample variables

{
  "id": "4"
}

Product variant by selected options

GRAPHQL Catalog / Product detail read:products

Resolve a single variant of a product from a complete set of selected options (direct-DB; no productservice NATS). Each selected option is attributeSlug + optionSlug, where optionSlug is the stable attribute option value. Returns the variant only when the selection is COMPLETE and resolves to exactly one variant; an incomplete, unknown, or non-matching selection (or a simple product) returns null. A genuine backend failure returns a GraphQL error.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale/market/currency choice.

query ProductVariant($productSlug: String!, $selectedOptions: [SelectedOptionInput!]!) {
  productVariant(productSlug: $productSlug, selectedOptions: $selectedOptions) {
    id
    title
    sku
    availableForSale
    inventoryStatus
    selectedOptions { attribute { slug name } option { label value } }
    price { current { amount currencyCode } regular { amount currencyCode } onSale }
    image { url altText }
  }
}

Variables

Sample variables

{
  "productSlug": "canvas-pattern-tote",
  "selectedOptions": [
    { "attributeSlug": "color", "optionSlug": "black" },
    { "attributeSlug": "fabric-pattern", "optionSlug": "striped" }
  ]
}

variantBySelectedOptions (on Product)

GRAPHQL Catalog / Product detail read:products

The Product child field used by a PDP after fetching the product: given the product's options, resolve the selected variant client-side via selectedOptions. attributeSlug + optionSlug (the stable option value). Same direct-DB resolution and null semantics as productVariant. Shown here composed with product(slug) so a single round-trip fetches the product and resolves the chosen variant.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for a normal storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token if testing a stamped locale/market/currency choice.

query ProductWithSelectedVariant($slug: String!, $selectedOptions: [SelectedOptionInput!]!) {
  product(slug: $slug) {
    id
    title
    options {
      attribute { slug name }
      options { option { label value } available }
    }
    variantBySelectedOptions(selectedOptions: $selectedOptions) {
      id
      title
      availableForSale
      selectedOptions { attribute { slug } option { value } }
      price { current { amount currencyCode } onSale }
      image { url altText }
    }
  }
}

Variables

Sample variables

{
  "slug": "canvas-pattern-tote",
  "selectedOptions": [
    { "attributeSlug": "color", "optionSlug": "black" },
    { "attributeSlug": "fabric-pattern", "optionSlug": "striped" }
  ]
}

Apply discount code

GRAPHQL Cart / Mutations write:cart

Store a discount code on the cart. Unknown codes fail with CART_COUPON_CODE_INVALID; an applied code that is not currently eligible STAYS on the cart and reports its reason through cart.discounts (eligible: false). All discount math comes from the platform evaluator — the same engine orders use.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation ApplyDiscountCode($code: String!) {
  applyDiscountCode(code: $code) {
    cart {
      coupons
      discounts { id name type activation code amount formattedAmount eligible reason }
      discountNudges { id name type reason }
      discountTotal { amount currencyCode }
      formattedDiscountTotal
    }
    userErrors { code field message }
  }
}

Variables

Sample variables

{"code": "SUMMER10"}

Remove discount code

GRAPHQL Cart / Mutations write:cart

Remove an applied discount code from the cart (no-op when absent).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token for a guest cart.
`X-Customer-Access-Token`	optional	Customer access token for a customer cart.

mutation RemoveDiscountCode($code: String!) {
  removeDiscountCode(code: $code) {
    cart {
      coupons
      discounts { id name amount formattedAmount eligible }
      discountTotal { amount currencyCode }
    }
    userErrors { code field message }
  }
}

Variables

Sample variables

{"code": "SUMMER10"}

Search

GRAPHQL Products / Queries read:products

Unified storefront search over the search index. Results group per the store's enabled search_result_types; the query expands through the store's synonym groups at query time and runs against the resolved locale's documents. Product hits ride the listing pipeline — channel/visibility gated, priced in the visitor's currency — and the filters argument narrows them (search finds, filters narrow). Disabled search refuses. Content hits carry permalink-correct urls.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query Search($q: String!) {
  search(query: $q, first: 12) {
    query
    productTotalCount
    products {
      totalCount
      edges { node { title slug price { current { amount currencyCode } } } }
    }
    docs {
      type
      totalCount
      items { title excerpt url }
    }
  }
}

Variables

Sample variables

{"q": "gaming"}

Product facets

GRAPHQL Products / Queries read:products

Live disjunctive facet counts for the store's enabled filters — each key is counted against the base narrowed by every OTHER selection, so a selected value's siblings stay countable. Labels resolve from the source (vendors, attribute options, metafield choices) in the request locale. Pair with products(filters: {facets: [...]}) — same base semantics; attribute filters enforce the same-variant rule.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query ProductFacets($filters: ProductFiltersInput) {
  productFacets(filters: $filters) {
    groups {
      key
      label
      displayType
      values { key label count }
    }
    priceMin
    priceMax
  }
}

Variables

Sample variables

{"filters": {"facets": [{"key": "vendor", "values": ["acme"]}]}}

Products (listing)

GRAPHQL Catalog / Listing read:products

Paginated product cards (direct-DB; no productservice NATS). Card fields only — id/slug/title/vendor/featuredImage/price/priceRange/availableForSale. Cursor pagination (first/after). Sorts: TITLE, PRICE_ASC, PRICE_DESC, CREATED_AT, UPDATED_AT (RELEVANCE/BEST_SELLING return an error). Filters: vendors, tags, priceMin/Max, onSale, inStock, productType (SIMPLE/VARIABLE). searchQuery and attribute filters return an explicit unsupported-filter error.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token.
`X-Tringify-Session-Token`	optional	Visitor session token for a stamped locale/market/currency.

query Products($first: Int, $after: Cursor, $sortKey: ProductSortKey, $filters: ProductFiltersInput) {
  products(first: $first, after: $after, sortKey: $sortKey, filters: $filters) {
    totalCount
    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
    edges {
      cursor
      node {
        id slug title vendor availableForSale inventoryStatus
        featuredImage { url altText }
        price { current { amount currencyCode } onSale }
        priceRange { min { amount currencyCode } max { amount currencyCode } hasRange }
      }
    }
  }
}

Variables

Sample variables

{
  "first": 12,
  "sortKey": "PRICE_ASC",
  "filters": { "inStock": true }
}

Collection with products

GRAPHQL Catalog / Listing read:products

A collection's metadata + its product listing (direct-DB; no productservice NATS). collection(slug) resolves metadata; the products field paginates the collection's members (first/after/sortKey).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token.
`X-Tringify-Session-Token`	optional	Visitor session token.

query Collection($slug: String!, $first: Int) {
  collection(slug: $slug) {
    id slug name description productCount
    image { url }
    products(first: $first, sortKey: CREATED_AT) {
      totalCount
      edges { node { id slug title price { current { amount currencyCode } } } }
    }
  }
}

Variables

Sample variables

{
  "slug": "summer",
  "first": 12
}

Collections

GRAPHQL Catalog / Listing read:products

Active collections, paginated (direct-DB; no productservice NATS).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token.

query Collections($first: Int) {
  collections(first: $first) {
    totalCount
    pageInfo { hasNextPage }
    edges { node { id slug name productCount image { url } } }
  }
}

Variables

Sample variables

{
  "first": 20
}

Category with products + tree

GRAPHQL Catalog / Listing read:products

A category's metadata, tree fields (parent/children/breadcrumbs), product count, and its product listing — all direct-DB (no productservice NATS).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token.
`X-Tringify-Session-Token`	optional	Visitor session token.

query Category($slug: String!, $first: Int) {
  category(slug: $slug) {
    id slug name description hasChildren productCount
    breadcrumbs { slug name }
    children { slug name }
    products(first: $first, sortKey: TITLE) {
      totalCount
      edges { node { id slug title price { current { amount currencyCode } } } }
    }
  }
}

Variables

Sample variables

{
  "slug": "accessories",
  "first": 12
}

Category tree

GRAPHQL Catalog / Listing read:products

Top-level categories; nested children resolve lazily via Category.children (direct-DB; no productservice NATS).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token.

query CategoryTree {
  categoryTree {
    slug name hasChildren productCount
    children { slug name hasChildren }
  }
}

Variables

Sample variables

{}

Page by slug

GRAPHQL Content / Pages read:content

Fetch a published storefront page by slug (direct-DB; no contentservice NATS). Returns id/title/slug/content (HTML) + SEO. A draft or unknown slug returns null. Requires the read:content scope.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with the read:content scope.
`X-Tringify-Session-Token`	optional	Visitor session token for a stamped locale (pages are locale-aware).

query Page($slug: String!) {
  page(slug: $slug) {
    id
    title
    slug
    content
    seo { title description }
  }
}

Variables

Sample variables

{
  "slug": "about-us"
}

Policy by slug

GRAPHQL Content / Policies read:content

Fetch a published storefront policy by slug (direct-DB; no contentservice NATS). Returns id/type/title/slug/content (HTML) + SEO. type is the policy kind (privacy/terms/refund/shipping/cookie). A draft or unknown slug returns null. Requires the read:content scope.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with the read:content scope.

query Policy($slug: String!) {
  policy(slug: $slug) {
    id
    type
    title
    slug
    content
    seo { title description }
  }
}

Variables

Sample variables

{
  "slug": "privacy-policy"
}

Blog post by slug

GRAPHQL Content / Blog read:content

Fetch a published blog post by slug (direct-DB; no contentservice NATS). Public gate: status=published AND visibility=public — a draft/private/unknown slug returns null. Returns content (HTML), excerpt, featured image, author, SEO, publishedAt, commentCount, categories, tags. Requires read:content.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:content.
`X-Tringify-Session-Token`	optional	Visitor session token for a stamped locale (posts are locale-aware).

query BlogPost($slug: String!) {
  blogPost(slug: $slug) {
    id
    title
    slug
    content
    excerpt
    publishedAt
    commentCount
    featuredImage { url altText }
    author { name }
    seo { title description }
    categories { name slug }
    tags { name slug }
  }
}

Variables

Sample variables

{
  "slug": "my-first-post"
}

Blog category by slug

GRAPHQL Content / Blog read:content

A blog category's metadata (direct-DB; no contentservice NATS). Compose with blogPosts(categorySlug:) for the category's posts. Unknown slug → null. Requires read:content.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:content.

query BlogCategory($slug: String!, $first: Int) {
  blogCategory(slug: $slug) {
    id name slug description postCount
    seo { title description }
  }
  blogPosts(categorySlug: $slug, first: $first) {
    totalCount
    edges { node { id title slug publishedAt } }
  }
}

Variables

Sample variables

{
  "slug": "news",
  "first": 10
}

Blog tags

GRAPHQL Content / Blog read:content

All blog tags (direct-DB; no contentservice NATS). Requires read:content.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:content.

query BlogTags {
  blogTags { id name slug postCount }
}

Variables

Sample variables

{}

Vendor by slug

GRAPHQL Catalog / Vendors & Brands read:products

Fetch a vendor by slug with its products (direct-DB; no contentservice/productservice NATS). Products are filtered by the vendor entity id (not a name match). Unknown slug → null. Requires read:products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:products.
`X-Tringify-Session-Token`	optional	Visitor session token (locale-aware: vendors are translatable).

query Vendor($slug: String!, $first: Int) {
  vendor(slug: $slug) {
    id
    name
    slug
    description
    productCount
    image { url }
    seo { title description }
    products(first: $first) {
      totalCount
      pageInfo { hasNextPage endCursor }
      edges { node { id title slug } }
    }
  }
}

Variables

Sample variables

{
  "slug": "acme",
  "first": 10
}

Brand by slug

GRAPHQL Catalog / Vendors & Brands read:products

Fetch a brand by slug with its products (direct-DB; no NATS). Products are filtered by the brand entity id. Unknown slug → null. Requires read:products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:products.
`X-Tringify-Session-Token`	optional	Visitor session token (locale-aware).

query Brand($slug: String!, $first: Int) {
  brand(slug: $slug) {
    id
    name
    slug
    description
    productCount
    image { url }
    seo { title description }
    products(first: $first) {
      totalCount
      edges { node { id title slug } }
    }
  }
}

Variables

Sample variables

{
  "slug": "brand2",
  "first": 10
}

Vendors

GRAPHQL Catalog / Vendors & Brands read:products

All vendors for the store (direct-DB; no NATS). Requires read:products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:products.

query Vendors {
  vendors { id name slug productCount image { url } }
}

Variables

Sample variables

{}

Brands

GRAPHQL Catalog / Vendors & Brands read:products

All brands for the store (direct-DB; no NATS). Requires read:products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token with read:products.

query Brands {
  brands { id name slug productCount image { url } }
}

Variables

Sample variables

{}

Renew visitor session

GRAPHQL Sessions / Mutations write:session

Renew the session supplied by X-Tringify-Session-Token — returns a fresh token and expiry. Renew before expiry to keep the cart and preferences.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation VisitorSessionRenew {
  visitorSessionRenew {
    token
    expiresAt
  }
}

Destroy visitor session

GRAPHQL Sessions / Mutations write:session

Destroy the current visitor session. The token becomes invalid; create a new session for the next visit.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation VisitorSessionDestroy {
  visitorSessionDestroy {
    success
  }
}

Set currency

GRAPHQL Sessions / Mutations write:session

Set the session's preferred currency. The code must come from storeConfig availableCurrencies — an unknown code is an error, never a silent fallback.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation SetCurrency($code: String!) {
  setCurrency(code: $code) {
    currencyCode
    languageCode
  }
}

Variables

Sample variables

{
  "code": "EUR"
}

Store configuration

GRAPHQL Runtime / Queries read:settings

Markets, currencies, and languages the store serves — the source of truth for currency/language pickers.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query StoreConfig {
  storeConfig {
    markets { id name countries currencyCode }
    currentMarket { id name currencyCode }
  }
}

Localization context

GRAPHQL Runtime / Queries read:settings

The active country/language plus everything switchable — a projection of runtimeContext.localization for building pickers.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query Localization {
  localization {
    country { isoCode name currencyCode }
    language { isoCode name }
    availableCountries { isoCode name currencyCode }
    availableLanguages { isoCode name }
  }
}

Restock notification

GRAPHQL Cart / Mutations write:cart

Request a back-in-stock notification for an out-of-stock or pre-order product. Idempotent per (product, variant, contact); contactType is "email" (default) or "sms".

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation RestockNotifyMe($input: RestockNotifyMeInput!) {
  restockNotifyMe(input: $input) {
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1,
    "variantId": null,
    "contactType": "email",
    "email": "shopper@example.com"
  }
}

Subscribe to newsletter

GRAPHQL Marketing / Mutations write:marketing

Subscribe an email address. When requiresConfirmation is true the store runs double opt-in: a confirmation email carries the token for confirmNewsletterSubscription.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation SubscribeNewsletter($email: String!) {
  subscribeNewsletter(email: $email) {
    success
    requiresConfirmation
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "email": "shopper@example.com"
}

Confirm newsletter subscription

GRAPHQL Marketing / Mutations write:marketing

Complete double opt-in with the emailed token.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation ConfirmNewsletter($token: String!) {
  confirmNewsletterSubscription(token: $token) {
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "token": "<from the confirmation email>"
}

Unsubscribe from newsletter

GRAPHQL Marketing / Mutations write:marketing

Unsubscribe with the tokenized link from any newsletter email.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

mutation UnsubscribeNewsletter($token: String!) {
  unsubscribeNewsletter(token: $token) {
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "token": "<from the unsubscribe link>"
}

Log out

GRAPHQL Customers / Mutations write:customer

Invalidate the current customer access token.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation CustomerLogout {
  customerLogout {
    success
    userErrors { code field message }
  }
}

Update profile

GRAPHQL Customers / Mutations write:customer

Update the logged-in customer's profile fields. Requires X-Customer-Access-Token.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation UpdateProfile($input: UpdateProfileInput!) {
  updateProfile(input: $input) {
    customer { id firstName lastName email }
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "firstName": "Ada",
    "lastName": "Lovelace"
  }
}

Add address

GRAPHQL Customers / Mutations write:customer

Create an address on the logged-in customer's address book.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation AddAddress($input: AddressInput!) {
  addAddress(input: $input) {
    address { id type firstName lastName address1 city countryCode }
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "type": "SHIPPING",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "address1": "1 Analytical Way",
    "city": "London",
    "countryCode": "GB"
  }
}

Update address

GRAPHQL Customers / Mutations write:customer

Update one address by id.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation UpdateAddress($addressId: ID!, $input: AddressInput!) {
  updateAddress(addressId: $addressId, input: $input) {
    address { id address1 city countryCode }
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "addressId": "<address id>",
  "input": {
    "type": "SHIPPING",
    "address1": "2 Analytical Way",
    "city": "London",
    "countryCode": "GB"
  }
}

Delete address

GRAPHQL Customers / Mutations write:customer

Delete one address by id.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation DeleteAddress($addressId: ID!) {
  deleteAddress(addressId: $addressId) {
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "addressId": "<address id>"
}

Set default shipping address

GRAPHQL Customers / Mutations write:customer

Mark an address as the default shipping address.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation SetDefaultShipping($addressId: ID!) {
  setDefaultShippingAddress(addressId: $addressId) {
    address { id }
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "addressId": "<address id>"
}

Set default billing address

GRAPHQL Customers / Mutations write:customer

Mark an address as the default billing address.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation SetDefaultBilling($addressId: ID!) {
  setDefaultBillingAddress(addressId: $addressId) {
    address { id }
    success
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "addressId": "<address id>"
}

Request data export

GRAPHQL Customers / Mutations write:customer

Ask for an export of the customer's data (delivered by email). Requires X-Customer-Access-Token.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation RequestDataExport {
  requestDataExport {
    success
    userErrors { code field message }
  }
}

Request account deletion

GRAPHQL Customers / Mutations write:customer

Initiate account deletion for the logged-in customer.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation RequestAccountDeletion {
  requestAccountDeletion {
    success
    userErrors { code field message }
  }
}

Search products (paged)

GRAPHQL Catalog / Queries read:products

Cursor-paged product search. The storefront-search operation returns the richer SearchResults shape (facets, suggestions); this one is the plain paged list.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query SearchProducts($query: String!, $first: Int, $after: Cursor, $sortKey: ProductSortKey) {
  searchProducts(query: $query, first: $first, after: $after, sortKey: $sortKey) {
    edges { node { id title slug price { current { formatted } } } }
    pageInfo { hasNextPage endCursor }
  }
}

Variables

Sample variables

{
  "query": "linen shirt",
  "first": 20,
  "sortKey": "RELEVANCE"
}

Product recommendations

GRAPHQL Catalog / Queries read:products

Recommendations seeded by one product — the "you may also like" rail on a product page.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query ProductRecommendations($productSlug: String!, $first: Int) {
  productRecommendations(productSlug: $productSlug, first: $first) {
    id
    title
    slug
    price { current { formatted } }
  }
}

Variables

Sample variables

{
  "productSlug": "linen-shirt",
  "first": 8
}

Featured products

GRAPHQL Catalog / Queries read:products

The store's featured products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query FeaturedProducts($first: Int) {
  featuredProducts(first: $first) {
    id
    title
    slug
    price { current { formatted } }
  }
}

Variables

Sample variables

{
  "first": 8
}

New arrivals

GRAPHQL Catalog / Queries read:products

Newest published products.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query NewArrivals($first: Int) {
  newArrivals(first: $first) {
    id
    title
    slug
    price { current { formatted } }
  }
}

Variables

Sample variables

{
  "first": 8
}

Best sellers

GRAPHQL Catalog / Queries read:products

Top sellers by sales signals.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query BestSellers($first: Int) {
  bestSellers(first: $first) {
    id
    title
    slug
    price { current { formatted } }
  }
}

Variables

Sample variables

{
  "first": 8
}

On-sale products

GRAPHQL Catalog / Queries read:products

Cursor-paged products currently discounted against their compare-at price.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query OnSale($first: Int, $after: Cursor) {
  onSaleProducts(first: $first, after: $after) {
    edges { node { id title slug price { current { formatted } compareAt { formatted } } } }
    pageInfo { hasNextPage endCursor }
  }
}

Variables

Sample variables

{
  "first": 20
}

Track product view

GRAPHQL Catalog / Mutations write:cart

Record a product view on the session — feeds recentlyViewedProducts and personalization. Fire-and-forget (returns a boolean).

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation TrackProductView($productId: ID!) {
  trackProductView(productId: $productId)
}

Variables

Sample variables

{
  "productId": "1"
}

Collection by slug

GRAPHQL Catalog / Queries read:collections

One collection by slug (collectionById fetches by id). Null when the slug does not resolve.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.

query Collection($slug: String!) {
  collection(slug: $slug) {
    id
    name
    slug
    description
  }
}

Variables

Sample variables

{
  "slug": "summer"
}

Remove review vote

GRAPHQL Reviews / Mutations write:customer

Withdraw a previously cast helpfulness vote.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Customer-Access-Token`	optional	Customer access token (required for account operations).

mutation RemoveReviewVote($reviewId: ID!) {
  removeReviewVote(reviewId: $reviewId) {
    success
    helpfulCount
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "reviewId": "<review id>"
}

Remove from wishlist

GRAPHQL Wishlist / Mutations write:wishlist

Remove a product (or specific variant) from the wishlist.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation RemoveFromWishlist($productId: Int!, $variantId: Int) {
  removeFromWishlist(productId: $productId, variantId: $variantId) {
    wishlist { itemCount }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "productId": 1,
  "variantId": null
}

Toggle wishlist

GRAPHQL Wishlist / Mutations write:wishlist

Flip wishlist membership — the one-call heart button.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation ToggleWishlist($input: WishlistItemInput!) {
  toggleWishlist(input: $input) {
    wishlist { itemCount }
    userErrors { code field message }
  }
}

Variables

Sample variables

{
  "input": {
    "productId": 1
  }
}

Clear wishlist

GRAPHQL Wishlist / Mutations write:wishlist

Empty the wishlist.

Headers

Name	Required	Description
`X-Storefront-Access-Token`	required	Storefront access token for the storefront/API version.
`X-Tringify-Session-Token`	optional	Visitor session token.
`X-Customer-Access-Token`	optional	Customer access token.

mutation ClearWishlist {
  clearWishlist {
    wishlist { itemCount }
    userErrors { code field message }
  }
}

Operation reference#

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers

Headers