Getting all categories
Endpoints: GET /categories & GET /admin/categories
Purpose
The GET /categories API retrieves a list of product categories available for customers, ensuring they can browse and explore relevant product groupings based on their access level. This endpoint filters categories based on visibility settings, user permissions, and availability status, ensuring customers only see publicly accessible categories. In contrast, the GET /admin/categories API provides administrators with full access to all categories, including hidden, restricted, or password-protected categories. This allows businesses to manage category structures efficiently, control visibility, and optimize the browsing experience for different customer segments. Both endpoints support pagination, sorting, and filtering for seamless navigation of large category lists.
Path Parameters
No path parameters for this endpoint.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | Integer | Number of products per request. |
offset | Integer | Starting point for pagination. |
order_by | String | Field to sort results by. |
direction | String | Sort order by ascending or descending. |
Use Case
Customers rely on GET /categories to explore product groupings tailored to their interests and eligibility. This ensures they only see categories that contain products they can purchase, supporting a smooth shopping experience. Businesses can use this endpoint to enforce visibility rules, schedule category availability, and manage restricted access for exclusive sales or memberships. Meanwhile, GET /admin/categories allows administrators to view and manage all categories, even those hidden from regular users. This is essential for organizing inventory, updating category metadata, and maintaining an efficient e-commerce structure without affecting the customer-facing catalog.
Request Body
No data is required for the request body.
Response
The API returns a list of categories with essential details, including category name, SKU, availability status, visibility settings, parent category relationships, SEO metadata, and associated products. For customers, GET /categories only includes publicly visible categories they are authorized to access. In contrast, GET /admin/categories provides administrators with a comprehensive view of all categories, including restricted and password-protected ones. The response supports pagination to ensure efficient data retrieval, particularly for large catalogs. Additionally, category details such as layout configurations, product associations, and metadata enhance e-commerce functionality by enabling precise category management and SEO optimization.
{
"categories": [
{
"id": CATEGORY_ID,
"name": "CATEGORY_NAME",
"sku": "CATEGORY_SKU",
"title": "CATEGORY_TITLE",
"heading": "CATEGORY_HEADING",
"url": "CATEGORY_URL",
"available": CATEGORY_AVAILABLE,
"visible": CATEGORY_VISIBLE,
"parent_category": {
"id": PARENT_CATEGORY_ID,
"name": "PARENT_CATEGORY_NAME",
"is_in_trash": PARENT_CATEGORY_IS_IN_TRASH,
"is_parent_in_trash": PARENT_CATEGORY_IS_PARENT_IN_TRASH,
"is_disposable": PARENT_CATEGORY_IS_DISPOSABLE
},
"layout": {},
"product_page": {
"id": PRODUCT_PAGE_ID,
"name": "PRODUCT_PAGE_NAME"
},
"product_layout": {
"id": PRODUCT_LAYOUT_ID,
"name": "PRODUCT_LAYOUT_NAME"
},
"available_on_date_range": AVAILABLE_ON_DATE_RANGE,
"available_from_date": "AVAILABLE_FROM_DATE",
"available_to_date": "AVAILABLE_TO_DATE",
"available_for": "AVAILABLE_FOR",
"selected_categories": [],
"password_protected": PASSWORD_PROTECTED,
"password": "PASSWORD",
"image_url": IMAGE_URL,
"background_image_url": BACKGROUND_IMAGE_URL,
"summary": "CATEGORY_SUMMARY",
"description": "CATEGORY_DESCRIPTION",
"products": [
{
"id": PRODUCT_ID,
"name": "PRODUCT_NAME"
}
],
"shipping_profile": {},
"tax_profile": {},
"disable_tracking": DISABLE_TRACKING,
"seo_configs": [],
"transaction_no": TRANSACTION_NO,
"is_disposable": IS_DISPOSABLE,
"is_in_trash": IS_IN_TRASH,
"is_parent_in_trash": IS_PARENT_IN_TRASH,
"created_by": {},
"created_on": "CREATED_ON_TIMESTAMP",
"updated_on": "UPDATED_ON_TIMESTAMP"
}
],
"pagination": {
"records": PAGINATION_RECORDS,
"limit": PAGINATION_LIMIT,
"offset": PAGINATION_OFFSET,
"previous_page": "PREVIOUS_PAGE_URL",
"next_page": "NEXT_PAGE_URL"
}
}Getting specific categories
Endpoints: GET /categories/{id} & GET /admin/categories/{id}
Purpose
The GET /categories/{id} API retrieves detailed information about a specific category that is visible to customers. It allows users to access category-related data such as its name, availability, associated products, and basic metadata. The GET /admin/categories/{id} API, on the other hand, provides administrators with complete details of any category, including hidden, restricted, or password-protected categories. This helps in category management, updating information, and maintaining store organization.
Path Parameters
/admin/categories/{id}
| Field | Type | Description |
|---|---|---|
| id | integer | The unique identifier of the categories |
Query Parameters
This endpoint does not have any query parameters.
Use Case
Customers use GET /categories/{id} to view details of a specific category they have access to, helping them explore relevant product groups. This is useful for navigating the store and discovering available products. GET /admin/categories/{id} allows administrators to access all category details, including those not visible to customers. This helps in managing category settings, updating metadata, and organizing product listings effectively.
Request Body
No data is required for the request body.
Response
The API returns category details such as name, SKU, availability, parent category information, associated products, and metadata. GET /categories/{id} only includes publicly available data for customers, while GET /admin/categories/{id} provides administrators with full category information, including hidden settings, password protection, and internal management fields.
{
"category": {
"id": CATEGORY_ID,
"name": "CATEGORY_NAME",
"sku": "CATEGORY_SKU",
"title": "CATEGORY_TITLE",
"heading": "CATEGORY_HEADING",
"url": "CATEGORY_URL",
"available": CATEGORY_AVAILABLE,
"visible": CATEGORY_VISIBLE,
"parent_category": {
"id": PARENT_CATEGORY_ID,
"name": "PARENT_CATEGORY_NAME",
"is_in_trash": PARENT_CATEGORY_IS_IN_TRASH,
"is_parent_in_trash": PARENT_CATEGORY_IS_PARENT_IN_TRASH,
"is_disposable": PARENT_CATEGORY_IS_DISPOSABLE
},
"layout": {},
"product_page": {
"id": PRODUCT_PAGE_ID,
"name": "PRODUCT_PAGE_NAME"
},
"product_layout": {
"id": PRODUCT_LAYOUT_ID,
"name": "PRODUCT_LAYOUT_NAME"
},
"available_on_date_range": AVAILABLE_ON_DATE_RANGE,
"available_from_date": "AVAILABLE_FROM_DATE",
"available_to_date": "AVAILABLE_TO_DATE",
"available_for": "AVAILABLE_FOR",
"selected_categories": [],
"password_protected": PASSWORD_PROTECTED,
"password": "PASSWORD",
"image_url": IMAGE_URL,
"background_image_url": BACKGROUND_IMAGE_URL,
"summary": "CATEGORY_SUMMARY",
"description": "CATEGORY_DESCRIPTION",
"products": [
{
"id": PRODUCT_ID,
"name": "PRODUCT_NAME"
}
],
"shipping_profile": {},
"tax_profile": {},
"disable_tracking": DISABLE_TRACKING,
"seo_configs": [],
"transaction_no": TRANSACTION_NO,
"is_disposable": IS_DISPOSABLE,
"is_in_trash": IS_IN_TRASH,
"is_parent_in_trash": IS_PARENT_IN_TRASH,
"created_by": {},
"created_on": "CREATED_ON_TIMESTAMP",
"updated_on": "UPDATED_ON_TIMESTAMP"
}
}
