Menus

Create, read, update, and delete navigation menus and their item trees — including the atomic whole-menu save — through the Store API.

Menus are named trees of navigation items. Reads require read_menus; writes require write_menus. Only documented request fields are accepted.

Start with GET /menus/{menuId}?include_items=false to obtain metadata, item_count and the current revision at any menu size. Full menu requests and responses are limited to 4 MiB of serialized JSON; larger documents return HTTP 413 MENU_PAGE_ITEMS_REQUIRED. Page root items and children through GET /menus/{menuId}/items, using parent_id, page and limit. Read live limits from /menus/limits; supported stored capacity and transport size are separate limits. Numeric resource IDs, including EU IDs starting at 281474976710656, are decimal strings in link_value.

Save with the revision you edited. Send exactly one of a complete items tree or ordered ops; keep item IDs to preserve translations. Use before_id or after_id to move relative to a sibling, including on later pages. Never send a visible page index as a global position or coalesce interleaved moves. child_count and subtree_count include unloaded descendants. Empty operations preserve items; an empty full tree deletes them. Revision conflicts retain local edits until you choose how to reconcile.

Canvas header/mobile navigation renders three levels; its footer renders only roots. Labels have no destination. Menu item images and promotion slots are not supported; /menus/limits declares placement capabilities. Resource links resolve current published slugs and hide unavailable leaves; surviving children keep a heading. Custom URLs do not follow destination renames or deletion.

Renaming reserves the old handle for the same menu. Up to 20 historical handles are retained; another menu cannot claim them. handle_aliases and backend-resolved handle_history expose reservations. Existing references never expire blindly.

CSV imports add or update items in existing menus. They do not create menu definitions or preserve empty menus and are not a complete backup. A staged preview expires after 24 hours or relevant source-version changes; diagnostics are paginated in a results dialog and operation feedback is backend-resolved. Menu import/export outcomes reach owners and staff with menus:read.

Only item titles translate. Use Menu item translations with item IDs and the corresponding menu and translation scopes. Menu names, handles, destinations and structure do not translate.

Endpoints#

Menu limits

GET read_menus

Fetch Menu limits, tree caps, and the link-type vocabulary.

Returns field maximum lengths, tree-shape caps (total items, children per parent, nesting depth), pagination caps, and the full link-type vocabulary with per-type value requirements. Build item forms from link_types — the set is server-owned. max_per_store is this store's plan cap, count is how many exist now, and usage is the localized label.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

curl 'https://api-store.tringify.com/api/2025-01/menus/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/menus/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "bulk_max": 500,
    "count": 1,
    "custom_url_max_length": 2048,
    "full_menu_max_bytes": 4194304,
    "handle_max_length": 255,
    "item_title_max_length": 255,
    "link_types": [
      {
        "label": "Home",
        "requires_value": false,
        "value": "home"
      },
      {
        "label": "Shop",
        "requires_value": false,
        "value": "shop"
      },
      {
        "label": "Product",
        "requires_value": true,
        "search_resource": "product",
        "value": "product"
      },
      {
        "label": "Category",
        "requires_value": true,
        "search_resource": "category",
        "value": "category"
      },
      {
        "label": "All Categories",
        "requires_value": false,
        "value": "category_list"
      },
      {
        "label": "Collection",
        "requires_value": true,
        "search_resource": "collection",
        "value": "collection"
      },
      {
        "label": "All Collections",
        "requires_value": false,
        "value": "collection_list"
      },
      {
        "label": "Blog Post",
        "requires_value": true,
        "search_resource": "blog_post",
        "value": "blog_post"
      },
      {
        "label": "All Blog Posts",
        "requires_value": false,
        "value": "blog_list"
      },
      {
        "label": "Vendor",
        "requires_value": true,
        "search_resource": "vendor",
        "value": "vendor"
      },
      {
        "label": "All Vendors",
        "requires_value": false,
        "value": "vendor_list"
      },
      {
        "label": "Brand",
        "requires_value": true,
        "search_resource": "brand",
        "value": "brand"
      },
      {
        "label": "All Brands",
        "requires_value": false,
        "value": "brand_list"
      },
      {
        "label": "Page",
        "requires_value": true,
        "search_resource": "page",
        "value": "page"
      },
      {
        "label": "Policy",
        "requires_value": true,
        "search_resource": "policy",
        "value": "policy"
      },
      {
        "label": "Blog Category",
        "requires_value": true,
        "search_resource": "blog_category",
        "value": "blog_category"
      },
      {
        "label": "Wishlist",
        "requires_value": false,
        "value": "wishlist"
      },
      {
        "label": "Cart",
        "requires_value": false,
        "value": "cart"
      },
      {
        "label": "My Account",
        "requires_value": false,
        "value": "account"
      },
      {
        "label": "Search",
        "requires_value": false,
        "value": "search"
      },
      {
        "label": "Track Order",
        "requires_value": false,
        "value": "track_order"
      },
      {
        "label": "Label (no link)",
        "requires_value": false,
        "value": "label"
      },
      {
        "label": "Custom URL",
        "requires_value": true,
        "value": "custom_url"
      }
    ],
    "list_max_limit": 100,
    "list_page_size": 20,
    "max_children_per_parent": 500,
    "max_handle_aliases": 20,
    "max_items": 10000,
    "max_nesting_depth": 3,
    "max_per_store": 3,
    "name_max_length": 255,
    "page_size_options": [
      20,
      50,
      100
    ],
    "placements": [
      {
        "theme": "canvas",
        "placement": "header",
        "max_depth": 3,
        "labels": true,
        "new_tab": true,
        "images": false,
        "promotions": false
      },
      {
        "theme": "canvas",
        "placement": "mobile",
        "max_depth": 3,
        "labels": true,
        "new_tab": true,
        "images": false,
        "promotions": false
      },
      {
        "theme": "canvas",
        "placement": "footer",
        "max_depth": 1,
        "labels": true,
        "new_tab": true,
        "images": false,
        "promotions": false
      }
    ],
    "rendering_guidance": "Canvas header and mobile navigation support 3 levels; its footer shows top-level items only. Menu images and promotions are not supported. Custom URLs do not follow destination changes. Translate item titles in Translations.",
    "search_max_length": 100,
    "sort_columns": [
      "name",
      "created_at",
      "updated_at"
    ],
    "usage": "Menus 1 of 3"
  },
  "success": true
}

List menus

GET read_menus

List menus for the store.

Returns paginated menus with item counts. Use search to filter by name or handle. total counts matching menus; store_total counts all menus in the store and can be compared with max_per_store from the limits response. Invalid sort parameters are rejected instead of silently defaulted.

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Example: `1`
`limit`	`integer`	Page size, capped by `list_max_limit`. Example: `20`
`search`	`string`	Search menus by name or handle. Example: `main`
`sort_by`	`string`	Sort column: name, created_at, or updated_at. Allowed values `namecreated_atupdated_at` Example: `created_at`
`sort_direction`	`string`	asc or desc. Allowed values `ascdesc` Example: `asc`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 MENU_SEARCH_TOO_LONG
Search exceeds the Menu contract max length.
400 MENU_LIST_INVALID_SORT_BY
Sort column is not in the Menu sort vocabulary.
400 MENU_LIST_INVALID_SORT_DIRECTION
Sort direction is not asc or desc.

curl 'https://api-store.tringify.com/api/2025-01/menus?limit=20&page=1&search=main&sort_by=created_at&sort_direction=asc' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus?limit=20&page=1&search=main&sort_by=created_at&sort_direction=asc", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/menus?limit=20&page=1&search=main&sort_by=created_at&sort_direction=asc",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "limit": 20,
    "menus": [
      {
        "created_at": "2026-01-05T12:00:00+05:30",
        "handle": "main-menu",
        "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
        "item_count": 4,
        "name": "Main Menu",
        "updated_at": "2026-01-05T12:00:00+05:30"
      }
    ],
    "page": 1,
    "sort_by": "created_at",
    "sort_direction": "asc",
    "store_total": 1,
    "total": 1
  },
  "success": true
}

Get a menu

GET read_menus

Fetch one menu with its full item tree.

Returns the menu, its revision (send it back when saving), and its nested item tree. An item whose linked resource shoppers cannot open carries link_status: unpublished (storefronts leave it out until it is published) or missing (deleted; the link is cleaned up shortly). Use include_items=false for metadata and a revision at any stored size. Full reads are limited to 4 MiB of serialized JSON; larger reads return MENU_PAGE_ITEMS_REQUIRED. Page one level at a time using the items endpoint.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Query parameters

Name	Type	Description
`include_items`	`boolean`	Set false to read metadata, item_count and revision without the tree. Example: `false`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
404 NOT_FOUND
Menu (or item) does not exist in this store.
413 MENU_PAGE_ITEMS_REQUIRED
Full menu exceeds the serialized byte budget; read metadata and page items.

curl 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10?include_items=false' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10?include_items=false", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10?include_items=false",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "created_at": "2026-01-05T12:00:00+05:30",
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 1,
    "items": [
      {
        "children": [],
        "created_at": "2026-01-05T12:00:00+05:30",
        "id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
        "link_type": "shop",
        "open_in_new_tab": false,
        "sort_order": 0,
        "title": "Shop"
      }
    ],
    "name": "Main Menu",
    "revision": "2026-01-05T06:30:00.123456Z",
    "updated_at": "2026-01-05T12:00:00+05:30"
  },
  "success": true
}

List menu items

GET read_menus

List one level of a menu's item tree.

Returns one paginated level — root items, or the children of parent_id. Each node carries child_count and exact subtree_count, including unloaded descendants. Use sibling IDs (before_id/after_id) for positional moves; page indexes are not global ranks. Fetch the next page only when has_more is true.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Query parameters

Name	Type	Description
`parent_id`	`uuid`	Parent item id. Omit for root items. Example: `1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0`
`page`	`integer`	Page number within the sibling level. Example: `1`
`limit`	`integer`	Page size, capped by `list_max_limit`. Example: `20`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
404 NOT_FOUND
Menu (or item) does not exist in this store.

curl 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items?limit=20&page=1&parent_id=1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items?limit=20&page=1&parent_id=1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items?limit=20&page=1&parent_id=1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "has_more": false,
    "items": [
      {
        "child_count": 0,
        "created_at": "2026-01-05T12:05:00+05:30",
        "id": "706044d9-8f58-4ce8-ac03-01e6a90ef52d",
        "link_label": "Blue shirt",
        "link_type": "product",
        "link_value": "42",
        "open_in_new_tab": false,
        "parent_id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
        "sort_order": 0,
        "subtree_count": 1,
        "title": "Blue shirt"
      }
    ],
    "total": 1
  },
  "success": true
}

Search menu items

GET read_menus

Search items across the whole menu.

Finds items by title or link label anywhere in the tree. Each hit includes its root-to-parent ancestor_ids and ancestor_titles so clients can expand-to-reveal without walking the tree.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Query parameters

Name	Type	Description
`q`	`string`	Search query over item titles and link labels. An empty query returns an empty list. Example: `shop`
`page`	`integer`	Page number. Example: `1`
`limit`	`integer`	Page size, capped by `list_max_limit`. Example: `20`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
404 NOT_FOUND
Menu (or item) does not exist in this store.

curl 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/search?limit=20&page=1&q=shop' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/search?limit=20&page=1&q=shop", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/search?limit=20&page=1&q=shop",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "has_more": false,
    "items": [
      {
        "ancestor_ids": [],
        "ancestor_titles": [],
        "child_count": 0,
        "id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
        "link_type": "shop",
        "open_in_new_tab": false,
        "sort_order": 0,
        "subtree_count": 1,
        "title": "Shop"
      }
    ],
    "total": 1
  },
  "success": true
}

Create a menu

POST write_menus

Create a menu (name + optional handle).

Creates an empty menu. handle is optional — when omitted it is generated from the name and auto-uniquified; a provided handle that collides is rejected. Fires menus/create.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Menu name. Example: `Main Menu`
`handle`	`string`	Optional handle. Omit to generate from the name (auto-uniquified). A provided duplicate is rejected. Example: `main-menu`

Errors

400 MENU_NAME_REQUIRED
Name is empty after normalization.
400 MENU_NAME_TOO_LONG
Name exceeds the Menu contract max length.
400 MENU_HANDLE_INVALID_FORMAT
Handle is not slug-shaped (lowercase words joined by hyphens).
400 MENU_HANDLE_TOO_LONG
Handle exceeds the Menu contract max length.
400 MENU_PLAN_LIMIT_REACHED
This store is at its plan menu cap.
404 NOT_FOUND
Menu does not exist in this store.
409 MENU_HANDLE_DUPLICATE
Handle already exists in this store.
409 MENU_HANDLE_RESERVED
Another menu reserves this historical handle.
409 MENU_HANDLE_ALIAS_LIMIT
Menu has 20 historical handles; retain its handle or reuse one of its own reservations.

curl -X POST 'https://api-store.tringify.com/api/2025-01/menus' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "main-menu",
  "name": "Main Menu"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "handle": "main-menu",
    "name": "Main Menu"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/menus",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "handle": "main-menu",
        "name": "Main Menu",
    },
)
data = res.json()

Response

201

Sample response

{
  "code": "MENU_CREATED",
  "data": {
    "created_at": "2026-01-05T12:00:00+05:30",
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 0,
    "items": [],
    "name": "Main Menu",
    "revision": "2026-01-05T06:30:00.123456Z",
    "updated_at": "2026-01-05T12:00:00+05:30"
  },
  "message": "Menu 'Main Menu' created.",
  "success": true
}

Update a menu

PUT write_menus

Rename a menu or change its handle.

Updates provided fields; omitted fields are unchanged. A handle change is validated and checked for uniqueness. This metadata response includes the new revision and items: null. Read the menu to retrieve its tree. Emits menus/update.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name`	`string`	New menu name. Example: `Footer Menu`
`handle`	`string`	New handle. Must be unique and slug-shaped. Example: `footer-menu`

Errors

400 MENU_NAME_REQUIRED
Name is empty after normalization.
400 MENU_NAME_TOO_LONG
Name exceeds the Menu contract max length.
400 MENU_HANDLE_INVALID_FORMAT
Handle is not slug-shaped (lowercase words joined by hyphens).
400 MENU_HANDLE_TOO_LONG
Handle exceeds the Menu contract max length.
400 MENU_PLAN_LIMIT_REACHED
This store is at its plan menu cap.
404 NOT_FOUND
Menu does not exist in this store.
409 MENU_HANDLE_DUPLICATE
Handle already exists in this store.
409 MENU_HANDLE_RESERVED
Another menu reserves this historical handle.
409 MENU_HANDLE_ALIAS_LIMIT
Menu has 20 historical handles; retain its handle or reuse one of its own reservations.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "footer-menu",
  "name": "Footer Menu"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "handle": "footer-menu",
    "name": "Footer Menu"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "handle": "footer-menu",
        "name": "Footer Menu",
    },
)
data = res.json()

Response

200

Sample response

{
  "code": "MENU_UPDATED",
  "data": {
    "created_at": "2026-01-05T12:00:00+05:30",
    "handle": "footer-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 1,
    "items": null,
    "name": "Footer Menu",
    "revision": "2026-01-05T06:35:00.123456Z",
    "updated_at": "2026-01-05T12:05:00+05:30"
  },
  "message": "Menu 'Footer Menu' updated.",
  "success": true
}

Save a menu atomically

PUT write_menus

Save name, handle, and item changes as one atomic batch.

Save metadata and item changes together, all or nothing. Send the revision from the menu you edited; if the menu changed since, the save is rejected with MENU_SAVE_CONFLICT so nobody's changes are overwritten — fetch it again and reapply. Send exactly one of items or ops. With items, send the complete tree: keep existing item IDs to preserve translations, omit items to delete them, and omit IDs for new items. An empty items array clears the tree. Full request/response JSON has a 4 MiB limit. With ops, send ordered create, update, delete, and move operations; an empty array preserves every item. Create a parent before referencing its unique temp_id in a later operation. Linked resources must belong to the store. Cycles and changes that exceed tree limits are rejected. A tree save returns the saved tree; an operations save returns items: null, so read the menu when you need the resulting items. Emits menus/update.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Menu name. Example: `Main Menu`
`handle` required	`string`	Menu handle — required on save. Example: `main-menu`
`revision` required	`string`	The `revision` returned when you read the menu. A save from an older revision is rejected. Example: `2026-01-05T06:30:00.123456Z`
`items`	`array<object>`	The FULL item tree. Each node: optional `id` (existing item), `title`, `link_type`, optional `link_value`/`link_label`, `open_in_new_tab`, `children`. Existing ids update in place; ids missing from the tree are deleted; nodes without ids are created. Example: `[{"title": "Shop", "link_type": "shop", "children": []}]`
`ops`	`array<object>`	Ordered operations instead of `items`. Each object has `kind` (create, update, delete, or move), `id` or a unique create `temp_id`, placement fields, and the editable item fields at the top level. Moves accept one of `before_id` or `after_id` in the destination sibling group, or an explicit absolute `sort_order`. Omit position when changing parent to append. Preserve operation order, including repeated moves of one item. There is no nested fields object. Create a parent before using its `temp_id` as a later operation’s `parent_temp_id`.

Errors

400 MENU_NAME_REQUIRED
Name is empty after normalization.
400 MENU_NAME_TOO_LONG
Name exceeds the Menu contract max length.
400 MENU_HANDLE_INVALID_FORMAT
Handle is not slug-shaped (lowercase words joined by hyphens).
400 MENU_HANDLE_TOO_LONG
Handle exceeds the Menu contract max length.
400 MENU_PLAN_LIMIT_REACHED
This store is at its plan menu cap.
404 NOT_FOUND
Menu does not exist in this store.
409 MENU_HANDLE_DUPLICATE
Handle already exists in this store.
409 MENU_HANDLE_RESERVED
Another menu reserves this historical handle.
409 MENU_HANDLE_ALIAS_LIMIT
Menu has 20 historical handles; retain its handle or reuse one of its own reservations.
413 MENU_PAGE_ITEMS_REQUIRED
Full menu exceeds the serialized byte budget; use paginated reads and smaller operation batches.
400 MENU_HANDLE_REQUIRED
Handle is required on the save path.
400 MENU_REVISION_REQUIRED
The save did not send the revision it was edited from.
409 MENU_SAVE_CONFLICT
The menu changed after the given revision; fetch it again and reapply the changes.
400 MENU_TOO_MANY_ITEMS
The tree exceeds the total item cap.
400 MENU_TOO_MANY_CHILDREN
A sibling group exceeds the children-per-parent cap.
400 MENU_ITEM_NESTING_DEPTH_REACHED
The tree exceeds the nesting-depth cap.
400 MENU_LINK_PRODUCT_NOT_FOUND
A product link references an id that does not exist (each linkable resource has matching *_ID_INVALID and *_NOT_FOUND codes: product, category, vendor, brand, collection, blog post, blog category, page).
400 MENU_LINK_POLICY_TYPE_INVALID
A policy link's value is not a valid policy type.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/save' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "main-menu",
  "items": [
    {
      "children": [],
      "link_type": "shop",
      "title": "Shop"
    }
  ],
  "name": "Main Menu",
  "revision": "2026-01-05T06:30:00.123456Z"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/save", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "handle": "main-menu",
    "items": [
      {
        "children": [],
        "link_type": "shop",
        "title": "Shop"
      }
    ],
    "name": "Main Menu",
    "revision": "2026-01-05T06:30:00.123456Z"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/save",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "handle": "main-menu",
        "items": [{
            "children": [],
            "link_type": "shop",
            "title": "Shop",
        }],
        "name": "Main Menu",
        "revision": "2026-01-05T06:30:00.123456Z",
    },
)
data = res.json()

Response

200

Sample response

{
  "code": "MENU_UPDATED",
  "data": {
    "created_at": "2026-01-05T12:00:00+05:30",
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 1,
    "items": [
      {
        "children": [],
        "created_at": "2026-01-05T12:05:00+05:30",
        "id": "706044d9-8f58-4ce8-ac03-01e6a90ef52d",
        "link_type": "shop",
        "open_in_new_tab": false,
        "sort_order": 0,
        "title": "Shop"
      }
    ],
    "name": "Main Menu",
    "revision": "2026-01-05T06:35:00.123456Z",
    "updated_at": "2026-01-05T12:05:00+05:30"
  },
  "message": "Menu 'Main Menu' updated.",
  "success": true
}

Create a menu item

POST write_menus

Add one item to a menu.

Creates one item. link_type comes from the limits vocabulary; types with a target require link_value (ids are existence-validated). parent_id places it in the tree, subject to the nesting-depth cap. Fires menus/update.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`title` required	`string`	Item title. Example: `Blue shirt`
`link_type` required	`string`	Link type from the limits vocabulary. Example: `product`
`link_value`	`string`	Target reference for types that require one — a resource id, policy type, or custom URL. Existence-validated. Example: `42`
`link_label`	`string`	Display label for the linked resource. Example: `Blue shirt`
`parent_id`	`uuid`	Parent item id. Omit for a root item. Subject to the nesting-depth cap. Example: `1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0`
`open_in_new_tab`	`boolean`	Open the link in a new tab. Example: `false`
`sort_order`	`integer`	Position within the sibling group. Omit to append. Example: `0`

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
400 MENU_ITEM_TITLE_REQUIRED
Item title is empty after normalization.
400 MENU_ITEM_TITLE_TOO_LONG
Item title exceeds the contract max length.
400 MENU_ITEM_LINK_TYPE_INVALID
Link type is not in the server vocabulary.
400 MENU_ITEM_LINK_VALUE_REQUIRED
The link type requires a link_value.
400 MENU_ITEM_LIMIT_REACHED
The menu is at its total item cap.
400 MENU_ITEM_PARENT_NOT_FOUND
Parent_id does not exist in this menu.
400 MENU_ITEM_NESTING_DEPTH_REACHED
Placement exceeds the nesting-depth cap.
400 MENU_ITEM_DESCENDANT_PARENT
An item cannot be moved under itself or its own descendant.
400 MENU_TOO_MANY_CHILDREN
The sibling group exceeds the children-per-parent cap.
404 NOT_FOUND
Menu or item does not exist in this store.
400 MENU_LINK_PRODUCT_NOT_FOUND
A product link references an id that does not exist (each linkable resource has matching *_ID_INVALID and *_NOT_FOUND codes: product, category, vendor, brand, collection, blog post, blog category, page).
400 MENU_LINK_POLICY_TYPE_INVALID
A policy link's value is not a valid policy type.

curl -X POST 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "link_label": "Blue shirt",
  "link_type": "product",
  "link_value": "42",
  "open_in_new_tab": false,
  "parent_id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
  "sort_order": 0,
  "title": "Blue shirt"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "link_label": "Blue shirt",
    "link_type": "product",
    "link_value": "42",
    "open_in_new_tab": false,
    "parent_id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    "sort_order": 0,
    "title": "Blue shirt"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "link_label": "Blue shirt",
        "link_type": "product",
        "link_value": "42",
        "open_in_new_tab": False,
        "parent_id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
        "sort_order": 0,
        "title": "Blue shirt",
    },
)
data = res.json()

Response

201

Sample response

{
  "code": "MENU_ITEM_CREATED",
  "data": {
    "children": [],
    "created_at": "2026-01-05T12:00:00+05:30",
    "id": "706044d9-8f58-4ce8-ac03-01e6a90ef52d",
    "link_label": "Blue shirt",
    "link_type": "product",
    "link_value": "42",
    "open_in_new_tab": false,
    "parent_id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    "sort_order": 0,
    "title": "Blue shirt"
  },
  "message": "Menu item 'Blue shirt' created.",
  "success": true
}

Update a menu item

PUT write_menus

Update one item's fields or placement.

Updates provided fields. Switching to a link type without a target clears link_value. parent_id reparents the item (cycle- and depth-guarded); an empty string moves it to the root. Fires menus/update.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`
`itemId` required	`uuid`	Menu item id. Example: `1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`title`	`string`	New item title. Example: `Shop all`
`link_type`	`string`	New link type. Switching to a type without a target clears `link_value`. Example: `collection_list`
`link_value`	`string`	New target reference. Existence-validated.
`link_label`	`string`	New display label.
`parent_id`	`string`	New parent item id; empty string moves the item to the root. Cycle- and depth-guarded.
`open_in_new_tab`	`boolean`	Open the link in a new tab. Example: `true`

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
400 MENU_ITEM_TITLE_REQUIRED
Item title is empty after normalization.
400 MENU_ITEM_TITLE_TOO_LONG
Item title exceeds the contract max length.
400 MENU_ITEM_LINK_TYPE_INVALID
Link type is not in the server vocabulary.
400 MENU_ITEM_LINK_VALUE_REQUIRED
The link type requires a link_value.
400 MENU_ITEM_LIMIT_REACHED
The menu is at its total item cap.
400 MENU_ITEM_PARENT_NOT_FOUND
Parent_id does not exist in this menu.
400 MENU_ITEM_NESTING_DEPTH_REACHED
Placement exceeds the nesting-depth cap.
400 MENU_ITEM_DESCENDANT_PARENT
An item cannot be moved under itself or its own descendant.
400 MENU_TOO_MANY_CHILDREN
The sibling group exceeds the children-per-parent cap.
404 NOT_FOUND
Menu or item does not exist in this store.
400 MENU_LINK_PRODUCT_NOT_FOUND
A product link references an id that does not exist (each linkable resource has matching *_ID_INVALID and *_NOT_FOUND codes: product, category, vendor, brand, collection, blog post, blog category, page).
400 MENU_LINK_POLICY_TYPE_INVALID
A policy link's value is not a valid policy type.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "link_type": "collection_list",
  "open_in_new_tab": true,
  "title": "Shop all"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "link_type": "collection_list",
    "open_in_new_tab": true,
    "title": "Shop all"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "link_type": "collection_list",
        "open_in_new_tab": True,
        "title": "Shop all",
    },
)
data = res.json()

Response

200

Sample response

{
  "code": "MENU_ITEM_UPDATED",
  "data": {
    "children": [],
    "created_at": "2026-01-05T12:00:00+05:30",
    "id": "1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    "link_type": "collection_list",
    "open_in_new_tab": true,
    "sort_order": 0,
    "title": "Shop all"
  },
  "message": "Menu item 'Shop all' updated.",
  "success": true
}

Delete a menu item

DELETE write_menus

Delete one item and its descendants.

Deletes the item and all of its children. Fires menus/update.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`
`itemId` required	`uuid`	Menu item id. Example: `1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
404 NOT_FOUND
Menu (or item) does not exist in this store.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10/items/1d2b7c44-93cf-4f2f-9f6a-5f4a1e2ce8d0",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "code": "MENU_ITEM_DELETED",
  "message": "Menu item deleted.",
  "success": true
}

Delete a menu

DELETE write_menus

Delete a menu and all of its items.

Deletes the menu and all of its items. Fires menus/delete.

Path parameters

Name	Type	Description
`menuId` required	`uuid`	Menu ID. Example: `9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_MENU_ID
Menu id is not a valid UUID.
404 NOT_FOUND
Menu (or item) does not exist in this store.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/menus/9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "code": "MENU_DELETED",
  "message": "Menu deleted.",
  "success": true
}

Fields#

Field	Type	Create	Update	Required	Translatable
`name`	string	Yes	Yes	create	No
`handle`	string	Yes	Yes		No
`item_count`	integer	No	No		No
`created_at`	string (RFC 3339)	No	No		No
`updated_at`	string (RFC 3339)	No	No		No

Webhook events#

Subscribe to these events to keep your integration in sync with menus. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.

Menu created

EVENT menus/create App scope: read_menus Staff permission: menus:write

Fired when a navigation menu is created.

Payload fields

Field	Type	Description
`menu.id`	`string`	Always present
`menu.name`	`string`	Selectable in the Payload builder
`menu.handle`	`string`	Selectable in the Payload builder
`menu.item_count`	`integer`	Selectable in the Payload builder
`menu.created_at`	`string`	Selectable in the Payload builder
`menu.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "menu": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 5,
    "name": "Main menu",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Menu updated

EVENT menus/update App scope: read_menus Staff permission: menus:write

Fired when a navigation menu or one of its items is updated.

Payload fields

Field	Type	Description
`menu.id`	`string`	Always present
`menu.name`	`string`	Selectable in the Payload builder
`menu.handle`	`string`	Selectable in the Payload builder
`menu.item_count`	`integer`	Selectable in the Payload builder
`menu.created_at`	`string`	Selectable in the Payload builder
`menu.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "menu": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "item_count": 5,
    "name": "Main menu",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Menu deleted

EVENT menus/delete App scope: read_menus Staff permission: menus:write

Fired when a navigation menu is deleted.

Payload fields

Field	Type	Description
`menu.id`	`string`	Always present
`menu.name`	`string`	Selectable in the Payload builder
`menu.handle`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "menu": {
    "handle": "main-menu",
    "id": "9a7f04c2-6f3e-4b58-a2ce-b9d3f43f6f10",
    "name": "Main menu"
  }
}