API Documentation

Update Product

PATCH /api/v3/products/:id

Update an existing product by its external ID. Only the provided fields will be updated.

Note: Parameters can be sent either wrapped in a product object or directly at the root level. Both formats are supported for backward compatibility.

Example Usage (Basic Update - with product wrapper)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "name": "Updated product name",
    "description": "Updated product description",
    "active": true,
    "category_id": "L4_2345"
  }
}'

Example Usage (Basic Update - without product wrapper)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Updated product name",
  "description": "Updated product description",
  "active": true,
  "category_id": "L4_2345"
}'

Example Usage (Update GTINs)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "gtin": "1234567890123",
    "gtins": ["1234567890123", "9876543210987"]
  }
}'

Example Usage (Clear GTINs)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "gtin": "",
    "gtins": []
  }
}'

Example Usage (Clear Image)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "image": ""
  }
}'

Example Usage (Make Product Canonical)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "canonical": true
  }
}'

Example Usage (Assign to External Canonical)

curl https://mcp.sortillus.com/api/v3/products/6 \
     -X PATCH \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product": {
    "external_canonical_product_id": "123"
  }
}'

Example Response

The endpoint returns an empty response body (200 OK) since updates are processed asynchronously.

(empty response body)

Verifying the Update

To verify the update was successful, query the product after a short delay:

curl https://mcp.sortillus.com/api/v3/products/6 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example response after update:

{
  "sortillus_id": 101,
  "external_id": 6,
  "name": "Updated product name",
  "description": "Updated product description",
  "image": "https://some.com/productid.image.jpg",
  "canonical_id": null,
  "category_external_id": "L4_2345",
  "sortillus_category_id": 123,
  "active": true,
  "state": "ready",
  "updated_at": "2025-06-12T18:08:59Z",
  "created_at": "2025-06-12T18:08:58Z",
  "recommendations": [],
  "recommended_at": null
}

Note: The updated_at timestamp shown above is the original timestamp - it will not change when updating product attributes.

Retrieve detailed information about a specific product by its external ID.

Example Usage

curl https://mcp.sortillus.com/api/v3/products/6 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Response (without recommendations)

{
  "sortillus_id": 101,
  "external_id": 6,
  "name": "your product name",
  "description": "long product description",
  "image": "https://some.com/productid.image.jpg",
  "canonical_id": null,
  "category_external_id": null,
  "active": true,
  "in_stock": true,
  "state": "new",
  "updated_at": "2025-06-12T18:08:59Z",
  "created_at": "2025-06-12T18:08:58Z",
  "recommendations": [],
  "recommended_at": null,
  "suggest_new_leaf_category": null,
  "suggest_category_branch_id": null,
  "external_similar_product_id": null,
  "similarity": null,
  "stats": {
    "processed_products": 150,
    "free_tier_limit": 1000,
    "limit_reached": false,
    "limit_warning": null
  }
}

Example Response (with recommendations)

{
  "sortillus_id": 101,
  "external_id": 6,
  "name": "your product name",
  "description": "long product description",
  "image": "https://some.com/productid.image.jpg",
  "canonical_id": null,
  "category_external_id": "L4_2345",
  "active": true,
  "in_stock": true,
  "state": "recommended_products",
  "updated_at": "2025-06-12T18:08:59Z",
  "created_at": "2025-06-12T18:08:58Z",
  "recommendations": [
    {
      "product_id": 789,
      "explanation": "Same model; different color.",
      "reason_json": {"source": "embedding", "score": 0.92}
    },
    {
      "product_id": 456,
      "explanation": "Bundle frequently bought together."
    },
    {
      "product_id": 123,
      "explanation": "Complementary product"
    }
  ],
  "recommended_at": "2025-06-12T18:10:00Z",
  "suggest_new_leaf_category": null,
  "suggest_category_branch_id": null,
  "external_similar_product_id": null,
  "similarity": null,
  "stats": {
    "processed_products": 150,
    "free_tier_limit": 1000,
    "limit_reached": false,
    "limit_warning": null
  }
}

Trigger Product Recommendations

POST /api/v3/products/:id/recommend

Trigger the product recommendation process for a specific product identified by its internal product ID (sortillus_id). The domain_id is automatically determined from the access token provided in the Authorization header. This endpoint initiates the AASM state machine transition to start generating product recommendations asynchronously.

Example Usage

Note: The ID in the URL must be the internal sortillus_id, not the external_id. In this example, 12345 is the sortillus_id.

curl https://mcp.sortillus.com/api/v3/products/12345/recommend \
     -X POST \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Success Response

{
  "message": "Recommendation process triggered successfully",
  "product_id": 12345,
  "external_id": 6,
  "state": "recommending_products",
  "extraction_triggered": false,
  "stats": {
    "processed_products": 150,
    "free_tier_limit": 1000,
    "limit_reached": false,
    "limit_warning": null
  }
}

Example Error Response (Product Not Found)

{
  "error": "Product not found"
}

Example Error Response (Invalid Token)

{
  "error": "Invalid access token"
}

Example Error Response (Failed to Trigger)

{
  "error": "Failed to trigger recommendations",
  "message": "Detailed error message"
}

Retrieve a paginated list of products for your domain. Each product includes its current processing state.

Example Usage

curl https://mcp.sortillus.com/api/v3/products?per_page=100&aasm_states=ready,error \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Usage (time-capped page)

curl https://mcp.sortillus.com/api/v3/products?updated_before=2025-09-15T00:00:00Z&per_page=1000 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Batch Create/Update Products

POST /api/v3/products/batch

Import multiple products or process existing products in a single request. This endpoint allows you to control which processing steps run during import, making it ideal for initial bulk imports where you may want to skip certain steps like similarity matching or recommendations. You can also use it to trigger processing steps on existing products by their sortillus IDs.

Example Usage (Limited Steps)

curl https://mcp.sortillus.com/api/v3/products/batch \
     -X POST \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "products": [
    {
      "id": 1001,
      "name": "Product 1",
      "description": "Description 1",
      "image": "https://example.com/image1.jpg"
    },
    {
      "id": 1002,
      "name": "Product 2",
      "description": "Description 2",
      "image": "https://example.com/image2.jpg"
    }
  ],
  "allow": ["extract", "notify"]
}'

Example Usage (Normal Processing)

curl https://mcp.sortillus.com/api/v3/products/batch \
     -X POST \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "products": [
    {
      "id": 1001,
      "name": "Product 1",
      "description": "Description 1",
      "image": "https://example.com/image1.jpg"
    }
  ],
  "allow": ["allow_all"]
}'

Example Usage (Process Existing Products by ID)

curl https://mcp.sortillus.com/api/v3/products/batch \
     -X POST \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "product_ids": [234, 55, 33],
  "allow": ["recommend", "notify"]
}'

Note: product_ids are sortillus IDs (internal database IDs), not external IDs. Use this to trigger processing steps on existing products. The system will intelligently advance each product through the allowed steps based on its current state. You can find sortillus IDs by calling GET /api/v3/products and looking at the id field in the response.

Example Response

{
  "message": "Batch import queued for 2 products",
  "job_status": "queued",
  "batch_settings": {
    "length": 2,
    "allow": ["extract", "notify"]
  }
}

Example Usage (time range)

curl https://mcp.sortillus.com/api/v3/products?updated_after=2025-09-01T00:00:00Z&updated_before=2025-09-15T00:00:00Z&per_page=1000 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Response

{
  "products": [
    {
      "id": 101,
      "external_id": 6,
      "state": "ready",
      "updated_at": "2025-06-12T18:08:59Z",
      "created_at": "2025-06-12T18:08:58Z",
      "category_external_id": "L4_2345",
      "external_canonical_id": null
    },
    {
      "id": 102,
      "external_id": 7,
      "state": "error",
      "updated_at": "2025-06-12T17:00:00Z",
      "created_at": "2025-06-12T16:50:00Z",
      "category_external_id": null,
      "external_canonical_id": 6
    }
  ],
  "meta": {
    "current_page": 1
  }
}

Retrieve a paginated list of shop categories for your domain. By default, returns all categories (including those without attributes). Use the with_attributes parameter to filter to only categories that have attributes assigned. Categories are ordered by the most recently created attribute, with categories without attributes appearing last.

Example Usage

# Get all categories
curl https://mcp.sortillus.com/api/v3/shop/categories?page=1&level=1 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

# Get only categories with attributes
curl https://mcp.sortillus.com/api/v3/shop/categories?with_attributes=true \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Response

{
  "categories": [
    {
      "id": 1,
      "external_id": 2345,
      "full_external_id": "L4_2345",
      "level": 4,
      "name": "Electronics",
      "en_name": "Electronics",
      "en_description": "Electronic devices and components",
      "updated_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "last_attribute_created_at": "2024-01-15T10:30:00Z",
      "attributes": [
        {
          "id": 1,
          "name": "Color",
          "external_id": 100,
          "measurement": null,
          "description": "Product color",
          "options": [
            {
              "id": 1,
              "name": "Red",
              "external_id": 101,
              "measurement": "free_text"
            },
            {
              "id": 2,
              "name": "Blue",
              "external_id": 102,
              "measurement": "free_text"
            }
          ]
        },
        {
          "id": 2,
          "name": "Size",
          "external_id": 200,
          "measurement": "cm",
          "description": "Product size",
          "options": [
            {
              "id": 3,
              "name": "25",
              "external_id": 201,
              "measurement": "cm"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1
  }
}

Retrieve detailed information about a specific shop category by its internal ID.

Example Usage

curl https://mcp.sortillus.com/api/v3/shop/categories/123 \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Response

{
  "id": 123,
  "full_external_id": "L4_2345",
  "name": "Electronics",
  "en_name": "Electronics",
  "en_description": "Electronic devices and components"
}

Create or Update Shop Category

Creates a new category or updates an existing one. The endpoint matches or initializes by external_id within your domain. All required fields must be provided.

Example Usage (create/update category)

curl https://mcp.sortillus.com/api/v3/shop/categories \
     -X POST \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json" \
     -d '{
  "category": {
    "external_id": 456,
    "name": "Electronics",
    "en_name": "Electronics",
    "en_description": "Electronic devices and components",
    "description": "Long category description",
    "external_parent_id": 20
  }
}'

Example Response

{
  "id": 123,
  "external_id": 456,
  "name": "Electronics",
  "description": "Long category description",
  "en_name": "Electronics",
  "en_description": "Electronic devices and components",
  "parent_id": 20,
  "full_external_id": "L2_456",
  "level": 2,
  "created_at": "2025-06-12T18:08:58Z",
  "updated_at": "2025-06-12T18:08:59Z"
}