Inventory & Products | Taxonomy | Set Taxonomy (Batch)

Taxonomy Management API (Categories, Brands)

This document outlines the API endpoints for managing taxonomy data (categories and brands) through the EasyCMS public API.

Overview

The taxonomy API endpoints allow you to create and update:

  • Categories (/set_category/)
  • Brands (/set_brand/)

For managing product tags, see Set Product Tags and Get Product Tags.

Each endpoint follows the same authentication and response patterns.

Authentication

All requests require proper authentication:

Headers

  • Authorization1: {TOKEN} - Your API token

Body Parameters (Required for Authentication)

  • username: Your API username
  • password: Your API password
  • account: Your account domain/ID

See How to Create API Credentials for setting up API access.



Set Category Endpoint

Endpoint and Method

  • Endpoint: https://easycms.fi/public_api/set_category/
  • Method: POST
  • Content-Type: application/json (recommended) or application/x-www-form-urlencoded

Operation Modes

1. Update Mode (cid provided)

When cid is provided, the API updates the existing category. Only provided fields are updated.

2. Create Mode (cid NOT provided)

When cid is NOT provided, the API creates a new category.

Category Fields

Field Type Required (Create) Description
cid int No Category ID (required for update)
category_name string/array Yes Category name (JSON array for multi-language or string)
parent_id int No Parent category ID (0 for root)
description string/array No Category description
status int No Status (1=active, 0=inactive)
visible int No Visibility (1=visible, 0=hidden)
sort_order int No Sort order
meta_title string No SEO meta title
meta_desc string No SEO meta description
image object No Image data (see Image Handling)

Category Examples

Create Category (cURL)

curl -X POST 'https://easycms.fi/public_api/set_category/' \
-H 'Authorization1: YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "account": "YOUR_ACCOUNT",
    "category_name": {"en_GB": "Electronics", "fi_FI": "Elektroniikka"},
    "parent_id": 0,
    "description": {"en_GB": "Electronic devices and accessories"},
    "status": 1,
    "visible": 1
}'

Update Category (PHP)

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://easycms.fi/public_api/set_category/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    'username' => 'YOUR_USERNAME',
    'password' => 'YOUR_PASSWORD',
    'account' => 'YOUR_ACCOUNT',
    'cid' => 5,
    'category_name' => ['en_GB' => 'Updated Category Name', 'fi_FI' => 'Päivitetty Kategoria'],
    'status' => 1
  ]),
  CURLOPT_HTTPHEADER => array(
    "Authorization1: YOUR_TOKEN",
    "Content-Type: application/json"
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;


Set Brand Endpoint

Endpoint and Method

  • Endpoint: https://easycms.fi/public_api/set_brand/
  • Method: POST
  • Content-Type: application/json (recommended) or application/x-www-form-urlencoded

Operation Modes

1. Update Mode (bid provided)

When bid is provided, the API updates the existing brand. Only provided fields are updated.

2. Create Mode (bid NOT provided)

When bid is NOT provided, the API creates a new brand.

Brand Fields

Field Type Required (Create) Description
bid int No Brand ID (required for update)
brand_name string/array Yes Brand name (JSON array for multi-language or string)
description string/array No Brand description
status int No Status (1=active, 0=inactive)
visible int No Visibility (1=visible, 0=hidden)
sort_order int No Sort order
meta_title string No SEO meta title
meta_desc string No SEO meta description
image object No Image data (see Image Handling)

Brand Examples

Create Brand (cURL)

curl -X POST 'https://easycms.fi/public_api/set_brand/' \
-H 'Authorization1: YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "account": "YOUR_ACCOUNT",
    "brand_name": {"en_GB": "Apple", "fi_FI": "Apple"},
    "description": {"en_GB": "Apple Inc. products"},
    "status": 1,
    "visible": 1
}'

Update Brand (PHP)

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://easycms.fi/public_api/set_brand/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    'username' => 'YOUR_USERNAME',
    'password' => 'YOUR_PASSWORD',
    'account' => 'YOUR_ACCOUNT',
    'bid' => 10,
    'brand_name' => ['en_GB' => 'Updated Brand Name'],
    'status' => 1
  ]),
  CURLOPT_HTTPHEADER => array(
    "Authorization1: YOUR_TOKEN",
    "Content-Type: application/json"
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;



Image Handling

All taxonomy endpoints support image operations through the image parameter.

Adding/Updating Image

"image": {
    "filename": "category_image.jpg",
    "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Image Fields

Field Type Description
filename string Desired filename (optional, auto-generated if omitted)
base64 string Required - Base64 encoded image data (with or without data URI prefix)

Image Example (Category with Image)

{
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD",
    "account": "YOUR_ACCOUNT",
    "category_name": {"en_GB": "Electronics"},
    "image": {
        "filename": "electronics_category.jpg",
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }
}



Response Format

Success Response (Create)

{
    "status": "success",
    "message": "Category created successfully",
    "data": {
        "cid": 15,
        "category": {
            "cid": 15,
            "category_name": {"en_GB": "Electronics", "fi_FI": "Elektroniikka"},
            "parent_id": 0,
            "status": 1
        }
    }
}

Success Response (Update)

{
    "status": "success",
    "message": "Category updated successfully",
    "data": {
        "cid": 5,
        "category": { /* full category data */ }
    },
    "changes": {
        "category_name": {"old": "Old Name", "new": "Updated Name"},
        "status": {"old": "0", "new": "1"}
    }
}

Error Response

{
    "status": "error",
    "error_code": "MISSING_REQUIRED_FIELDS",
    "message": "Missing required field: category_name",
    "missing_fields": ["category_name"]
}

Error Codes

Code HTTP Status Description
METHOD_NOT_ALLOWED 405 Only POST method is allowed
UNAUTHORIZED 401 Invalid credentials or token
CATEGORY_NOT_FOUND 404 Category with specified cid not found
BRAND_NOT_FOUND 404 Brand with specified bid not found
MISSING_REQUIRED_FIELDS 400 Required fields missing
UPDATE_FAILED 500 Failed to update
CREATE_FAILED 500 Failed to create



Multi-Language Support

All name and description fields support multi-language values. You can pass either:

Option 1: JSON Object (Recommended)

{
    "category_name": {
        "en_GB": "Electronics",
        "fi_FI": "Elektroniikka",
        "sv_SE": "Elektronik"
    }
}

Option 2: Simple String

{
    "category_name": "Electronics"
}

When a simple string is provided, it's automatically converted to the default language (en_GB).

Available Language Codes

  • en_GB - English (Great Britain)
  • fi_FI - Finnish
  • sv_SE - Swedish
  • es_ES - Spanish
  • de_DE - German
  • fr_FR - French
  • ru_RU - Russian
  • zh_CN - Chinese (Simplified)
  • ja_JP - Japanese

Check /get_languages endpoint for the full list of available languages.



Best Practices

  1. Use multi-language format: Always use JSON object format for names to ensure multi-language support
  2. Check parent_id validity: When creating categories, ensure parent_id exists (use 0 for root categories)
  3. Handle errors gracefully: Check the status field and handle error codes appropriately
  4. Test with small data: Before bulk operations, test with single entries
  5. Keep sort_order consistent: Use logical sort order values (10, 20, 30) to allow easy insertion later



Related Documentation

$md_file_name = "docs/set_taxonomy.md"; $page_title = "ProLasku.fi API Guide for Taxonomy Data Management (Categories, Brands, Tags)"; require_once("includes/index.php"); ?>