Categories

About

The categories query retrieves the complete list of product categories with full details including translations, media assets, and hierarchy information. Use this query to:

• Build category navigation menus and sidebars
• Display breadcrumb paths for product browsing
• Implement category-based product filtering
• Create category landing pages and collections
• Sync category structure with external systems
• Display category metadata (images, descriptions, logos, banners)
• Support multi-language category content
• Show category hierarchy with children counts

This query supports full pagination with cursor-based navigation and includes complete SEO metadata and display settings for each category.

Arguments

Argument	Type	Required	Description
first	Int	❌ No	Number of categories to return (forward pagination). Max: 100.
after	String	❌ No	Pagination cursor for forward navigation. Use with first.
last	Int	❌ No	Number of categories for backward pagination. Max: 100.
before	String	❌ No	Pagination cursor for backward navigation. Use with last.

Possible Returns

Field	Type	Description
id	ID!	Unique category API identifier.
_id	Int!	Numeric category ID.
position	Int	Display position among siblings.
logoPath	String	File path to category logo.
logoUrl	String	Full URL to category logo image.
bannerPath	String	File path to category banner.
bannerUrl	String	Full URL to category banner image.
status	Int	Category status (0 = inactive, 1 = active).
displayMode	String	Display mode: products_only, category_and_products, products_and_description.
_lft	Int	Left value for nested set tree structure.
_rgt	Int	Right value for nested set tree structure.
additional	String	Additional metadata (JSON format).
translation	CategoryTranslation!	Default locale translation.
translation.id	ID!	Translation identifier.
translation._id	Int!	Numeric translation ID.
translation.categoryId	Int!	Associated category ID.
translation.name	String!	Category name in current language.
translation.slug	String!	URL slug for the category.
translation.urlPath	String!	Full URL path including hierarchy.
translation.description	String	Category description text.
translation.metaTitle	String	SEO meta title tag.
translation.metaDescription	String	SEO meta description.
translation.metaKeywords	String	SEO keywords.
translation.localeId	Int	Locale identifier.
translation.locale	String!	Language locale code (e.g., 'en', 'ar', 'fr').
translations	CategoryTranslationCollection!	All available translations.
translations.edges	[Edge!]!	Translation edges with cursors.
translations.pageInfo	PageInfo!	Pagination info for translations.
translations.totalCount	Int!	Total translations for this category.
createdAt	DateTime!	Category creation timestamp.
updatedAt	DateTime!	Last update timestamp.
url	String	Full category URL.
children	CategoryCollection!	Child categories.
children.edges	[Edge!]!	Child category edges.
children.totalCount	Int!	Total child categories.
pageInfo	PageInfo!	Pagination information.
pageInfo.hasNextPage	Boolean!	Whether more pages exist forward.
pageInfo.hasPreviousPage	Boolean!	Whether more pages exist backward.
pageInfo.startCursor	String	Cursor for first item in page.
pageInfo.endCursor	String	Cursor for last item in page.
totalCount	Int!	Total categories matching filters.

Use Cases

1. Main Navigation Menu

Use the "Optimized for Navigation" example for rendering dropdown category menus.

2. Multi-Language Support

Use the "With All Translations" example to display categories in multiple languages.

3. Category Listing Page

Use the "Complete Details" example for full category information with images.

4. Pagination

Use the "With Cursor Pagination" example for handling large category lists.

Best Practices

1. Request Only Needed Fields - Minimize data transfer by selecting only required fields
2. Use Pagination - Always use pagination for better performance with many categories
3. Cache Results - Categories change infrequently, cache the full list
4. Filter by Status - Only fetch active categories by default
5. Include SEO Data - Always fetch meta tags for search engine optimization
6. Use Translations - Fetch translations for multi-language support

Related Resources

• Tree Categories - Hierarchical category tree for navigation
• Get Products - Query products within a category
• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources