--- updatedAt: 2026-09-21T13:01:52.000Z agentTools: projectIndex: https://docs.tweakwise.com/llms.txt --- # Backend API While many Tweakwise users rely on feed imports (XML/CSV) to synchronize their catalog, there are scenarios where real-time updates or direct integrations are necessary. The Tweakwise Backend API (Navigator API) allows you to manage your products and categories programmatically, offering fine-grained control over your catalog without waiting for full feed processing. Check out the full [Backend API reference](https://docs.tweakwise.com/reference/backend-api-introduction) solutions. # # Example This guide explains how to: 1. Create and update **Categories**, including hierarchy management. 2. Create and update **Products** (using the `/item` endpoint). **Note:** This method interacts directly with the Tweakwise database. Changes are immediate but may require a "Publish" task to be visible in the frontend search results. ## Prerequisites Before you begin, ensure you have: * **Authentication:** Requests must include the correct authentication headers. Refer to the [Authentication documentation](https://docs.tweakwise.com/reference/backend-api-authentication) for generating your keys. * **Base URL:** The standard base URL for the Backend API is `https://navigator-api.tweakwise.com`. ## 1. Managing Categories (`/category`) The category structure defines the navigation tree of your shop. You can create new categories or update existing ones using the `/category` endpoint. ### Create a Category To create a new category, send a `POST` request. You must define a unique `CategoryId` (or `Key` if alphanumeric IDs are enabled) and specify its position in the tree using `Parents`. **Endpoint:** `POST /category` #### Request Body ```json { "CategoryId": 1001, "Name": "Sneakers", "Rank": 1, "Status": "Active", "Parents": [ 20 // ID of the parent category (e.g., 'Shoes') ], "Url": "[https://myshop.com/shoes/sneakers](https://myshop.com/shoes/sneakers)" } ``` #### Code Example (cURL) ```bash curl --request POST \ --url [https://navigator-api.tweakwise.com/category](https://navigator-api.tweakwise.com/category) \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'instance-key: YOUR_INSTANCE_KEY' \ --data '{ "CategoryId": 1001, "Name": "Sneakers", "Rank": 1, "Status": "Active", "Parents": [20], "Url": "[https://myshop.com/shoes/sneakers](https://myshop.com/shoes/sneakers)" }' ``` ### Defining Category Hierarchy Building a category tree is done using the `Parents` field in the payload. You do not need a separate endpoint to move categories; you simply define their parentage upon creation or update. * **Root Category:** To create a top-level category (Main Menu item), leave the `Parents` array empty. * **Sub-Category:** To nest a category, add the `CategoryId` of the parent into the `Parents` array. #### Example: Creating a Sub-Category If "Sneakers" has ID `1001`, you can create a "High-tops" sub-category inside it like this: ```json { "CategoryId": 1002, "Name": "High-tops", "Parents": [1001], "Status": "Active" } ``` | Parameter | Type | Required | Description | | :----------- | :----- | :------- | :--------------------------------------------------------- | | `CategoryId` | int64 | Yes | The unique numeric identifier for the category. | | `Key` | string | No | Alphanumeric identifier (if feature is enabled). | | `Name` | string | Yes | The display name of the category. | | `Parents` | array | Yes | List of parent Category IDs. Use `[]` for root categories. | | `Rank` | int64 | No | Sorting weight (lower numbers often appear first). | | `Status` | string | Yes | `Active` or `Inactive`. | ## 2. Managing Products (`/item`) To manage your product catalog, you must use the `/item` endpoint. **Important:** The `/product` endpoint is **deprecated**. Please ensure all integration logic uses `/item`. ### Create an Item To add a product, use the `POST` method. The `ArticleNumber` is the unique key that links this product to your external systems (ERP, PIM). **Endpoint:** `POST /item` #### Request Body ```json { "ArticleNumber": "SNKR-001-RED", "Name": "Red High-Top Sneaker", "Price": 89.95, "Brand": "StreetWalkers", "Stock": 150, "GroupCode": "SNKR-001", "Image": "[https://myshop.com/images/snkr-red.jpg](https://myshop.com/images/snkr-red.jpg)", "Url": "[https://myshop.com/products/snkr-red](https://myshop.com/products/snkr-red)", "Categories": [ 1001 // Links to the 'Sneakers' category we created above ], "Status": "Active" } ``` #### Code Example (cURL) ```bash curl --request POST \ --url [https://navigator-api.tweakwise.com/item](https://navigator-api.tweakwise.com/item) \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'instance-key: YOUR_INSTANCE_KEY' \ --data '{ "ArticleNumber": "SNKR-001-RED", "Name": "Red High-Top Sneaker", "Price": 89.95, "Brand": "StreetWalkers", "Categories": [1001], "Status": "Active" }' ``` | Parameter | Type | Required | Description | | :-------------- | :----- | :------- | :--------------------------------------------------------------- | | `ArticleNumber` | string | Yes | Unique SKU or ID of the product. | | `Name` | string | Yes | Product title. | | `Price` | double | No | Current selling price. | | `GroupCode` | string | No | Used to group variants (e.g., different sizes) under one parent. | | `Categories` | array | No | Array of Category IDs this product belongs to. | | `Image` | string | No | Absolute URL to the product image. | ## Important Considerations * **Publication:** Creating an item via the API adds it to the catalog, but it might not appear in search results immediately. You often need to trigger a **Publish Task** (or wait for the scheduled one) to index these changes for the frontend. * **Rate Limits:** While the API is robust, avoid sending thousands of individual `POST` requests in a tight loop. For bulk updates, consider using the Feed Import or batching if supported. * **Validation:** The API will return a `400 Bad Request` if you try to create a Category with a duplicate ID or an Item with an existing ArticleNumber (use `PUT` or `PATCH` to update instead). * **Open API**: use [our OpenAPI specification](https://docs.tweakwise.com/reference/backend-api-introduction#openapi) to automatically generate client libraries or server stubs in the programming language of your choice. ## FAQ **Q: I created an item successfully, but I can't find it in the search bar. Why?** **A:** The search index is separate from the catalog. After modifying data via the API, you must ensure a "Publish" task runs. You can trigger this manually in the Tweakwise App or via the `/task/trigger` endpoint. **Q: Can I use alphanumeric IDs for categories?** **A:** Yes, but you must enable the "Use alphanumeric category IDs" feature in your Tweakwise instance settings first. Once enabled, use the `Key` field in your payload instead of just `CategoryId`. **Q: I see references to **`/product`** in old documentation. Should I use it?** **A:** No, `/product` is deprecated. You should strictly use the `/item` endpoint for all product-related operations (Create, Update, Delete) to ensure future compatibility.