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.

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 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

{
  "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)

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:

{
  "CategoryId": 1002,
  "Name": "High-tops",
  "Parents": [1001], 
  "Status": "Active"
}

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

{
  "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)

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"
}'

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 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.