Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceQueriesmenu

menu

Get a specific link list/menu by handle.

Query Structure

query {
  menu(handle: String!) {
    handle
    levels
    links {
      title
      url
      links {
        title
        url
      }
    }
    title
  }
}

Arguments

ArgumentTypeDescriptionRequiredDefault Value
handleStringThe handle of the link list to retrieveYesN/A

Return Type

Menu

Represents a navigational menu containing a list of links, typically used for site navigation structures such as main menus or footers.

FieldTypeDescription
handleStringUnique identifier (token) for this menu, used to reference the menu programmatically.
levelsIntThe total number of nested levels in this menu, representing the depth of the menu hierarchy.
links[Link]The list of top-level links in this menu. Each link may have its own child links, forming a hierarchical structure.
titleStringThe display name of the menu, typically shown as the menu’s title in navigation components.

Link

FieldTypeDescription
titleStringThe display text of the link.
urlStringThe URL the link points to.
links[Link]Child links nested under this link (optional).

Examples

Basic Query

query {
  menu(handle: "main-menu") {
    title
    links {
      title
      url
    }
  }
}

Advanced Query

query {
  menu(handle: "footer-menu") {
    handle
    title
    levels
    links {
      title
      url
      links {
        title
        url
      }
    }
  }
}

Field Selection

query {
  menu(handle: "sidebar-menu") {
    title
    links {
      title
      url
    }
  }
}

cURL Example

curl -X POST https://www.mystoreurl.com/graphql/0.8.0 \
  -H "Content-Type: application/json" \
  -d '{"query":"query { menu(handle: \"main-menu\") { title links { title url } } }"}'

JavaScript Example

async function fetchMenu(handle) {
  const query = `
    query {
      menu(handle: "${handle}") {
        title
        links {
          title
          url
        }
      }
    }
  `;
 
  try {
    const response = await fetch("https://www.mystoreurl.com/graphql/0.8.0", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ query })
    });
 
    const { data, errors } = await response.json();
 
    if (errors) {
      console.error("GraphQL errors:", errors);
      return null;
    }
 
    return data.menu;
  } catch (error) {
    console.error("Network error:", error);
    return null;
  }
}
 
// Usage example
fetchMenu("main-menu").then(menu => {
  if (menu) {
    console.log("Menu title:", menu.title);
    console.log("Links:", menu.links);
  }
});

Response Format

{
  "data": {
    "menu": {
      "handle": "main-menu",
      "levels": 2,
      "links": [
        {
          "title": "Home",
          "url": "/",
          "links": []
        },
        {
          "title": "Products",
          "url": "/products",
          "links": [
            {
              "title": "New Arrivals",
              "url": "/products/new-arrivals"
            }
          ]
        }
      ],
      "title": "Main Menu"
    }
  }
}

Error Handling

Error CodeDescriptionHandling Recommendation
BAD_USER_INPUTThe provided handle argument is missing or invalid.Verify the handle argument is provided and valid.
NOT_FOUNDNo menu found for the given handle.Confirm the handle exists and is correctly spelled.
INTERNAL_SERVER_ERRORUnexpected server error occurred.Retry the request after some time or contact support.

Errors will be returned in the errors array in the GraphQL response. Always check for errors before processing data.

Performance Considerations

  • Query only the fields you need to reduce response size and improve performance.
  • Avoid requesting deeply nested links unless necessary, as this can increase query complexity.
  • Use pagination or limit nested levels if supported in future API versions to optimize performance.
  • The API enforces rate limiting; excessive requests may result in throttling. Implement exponential backoff or retry logic.
  • Responses may be cached by clients or intermediate proxies. Use cache headers if provided to improve efficiency.

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

  • Menu: The main return type representing the navigational menu.
  • Link: Represents individual links within the menu, including nested child links.

Notes

  • The handle argument is mandatory and must exactly match the menu’s unique identifier.
  • The levels field indicates the depth of nested links but does not provide the links themselves.
  • The links field may contain nested links arrays to represent submenus.
  • Always validate the presence of optional fields before accessing them in your application code.