API Documentation

Read and update domain feature toggles (e.g. should_recommend_products, should_extract) for the domain identified by your access token. Use the same domain access token as for the products API (Authorization: Bearer <your_domain_access_token>).

GET /api/v3/domain/settings

Returns the six feature toggles for your domain. All keys are always present; nil is returned as false.

Response example:

{
  "should_similarize": false,
  "should_categorize": true,
  "should_recommend_products": false,
  "should_notify": true,
  "should_ascribe": false,
  "should_extract": true
}

PATCH /api/v3/domain/settings

Update any subset of the six toggles. Send a JSON body with the keys you want to change (boolean or "true"/"false"). Response is the same shape as GET (full settings after update).

Request example:

curl https://admin.sortillus.com/api/v3/domain/settings \
  -X PATCH \
  -H "Authorization: Bearer YOUR_DOMAIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"should_recommend_products": true, "should_extract": false}'

Errors: 401 Unauthorized if the token is missing or invalid; 422 Unprocessable Entity if validation fails (with errors in the response).

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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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,
  "improved_localized_description": null,
  "improved_localized_product_name": 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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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://admin.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"
}

Delete Shop Category

Deletes a shop category by its external identifier. You must use either external_id (integer) or full_external_id (string, e.g., "L1_123"). Internal IDs are not accepted for security reasons to prevent accidentally deleting the wrong category.

This operation will:

• Clear the category_id for all products in this category (products become uncategorized)
• Trigger automatic recategorization for canonical products (products without a canonical_product_id)
• Remove the category from the vector database (Qdrant)
• Delete the category record

Important: Categories with subcategories cannot be deleted. You must delete all subcategories first.

Example Usage

# Delete by external_id (numeric parameter)
curl https://admin.sortillus.com/api/v3/shop/categories/100 \
     -X DELETE \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

# Delete by full_external_id (string parameter)
curl https://admin.sortillus.com/api/v3/shop/categories/L1_100 \
     -X DELETE \
     -H "Authorization: Bearer " \
     -H "Content-Type: application/json"

Example Success Response

{
  "message": "Category 'Electronics' was successfully deleted.",
  "stats": {
    "total_products_count": 15,
    "canonical_products_count": 10,
    "recategorized_count": 10,
    "recategorization_errors_count": 0
  }
}

Example Error Response (Category has subcategories)

{
  "error": "Cannot delete category 'Electronics' because it has 3 subcategories. Please delete the subcategories first."
}

Example Error Response (Root category with subcategories)

{
  "error": "Cannot delete ROOT category 'Electronics' because it has 3 subcategories. Root categories with subcategories cannot be deleted as they form the foundation of your category hierarchy. Please delete all subcategories first."
}