API Playground

Test the create attribute endpoint with your data.

Authentication Required

You need to Login to test the API playground

Create Attribute

Create a new custom attribute for products

This endpoint allows you to create a new custom attribute that can be used to enrich your product data. Attributes can be global (available for all products) or family-specific (only for certain product families).

You can define various attribute types including text, numbers, boolean values, rich text, and select options.

Note: This operation does not consume credits
Endpoint URL
POST https://api.commerceclarity.com/api/v1/attributes/create

Request Parameters

Parameter Type Required Description
name string Required Human-readable display name for the attribute
attribute_id string Required Unique identifier for the attribute (lowercase, no spaces). Must be unique across all user attributes
type string Required Attribute data type. Values: "text", "number", "boolean", "rich-text", "single-select", "multi-select"
scope string Required Attribute scope. Values: "global" (available for all products), "family" (specific to product families)
description string Optional Optional description explaining the purpose of this attribute
is_enabled boolean Optional Whether the attribute is enabled. Default: true
options array Conditional Required for single-select and multi-select types. Array of option objects — each must include action and value.
  options[].action string Required Must be "new" when creating an attribute.
  options[].value string Required The display label for the option (e.g. "Red"). A normalised key is derived automatically.
  options[].value_id string Optional Optional custom identifier for the option.
family_ids array Conditional Array of family IDs. Required when scope is "family"

Request Examples

Global Attribute Example 
curl -X POST "https://api.commerceclarity.com/api/v1/attributes/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Color",
    "attribute_id": "color",
    "type": "single-select",
    "scope": "global",
    "description": "Product color attribute",
    "options": [
      { "action": "new", "value": "Red" },
      { "action": "new", "value": "Blue" },
      { "action": "new", "value": "Green" },
      { "action": "new", "value": "Yellow" }
    ]
  }'
Family Attribute Example 
curl -X POST "https://api.commerceclarity.com/api/v1/attributes/create" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warranty Period",
    "attribute_id": "warranty_period",
    "type": "text",
    "scope": "family",
    "family_ids": ["507f1f77bcf86cd799439013"],
    "description": "Product warranty information",
    "is_enabled": true
  }'
PHP Example (Guzzle HTTP Client) 
$client = new \GuzzleHttp\Client();

$response = $client->post('https://api.commerceclarity.com/api/v1/attributes/create', [
    'headers' => [
        'Authorization' => 'Bearer ' . $apiToken,
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'name' => 'Color',
        'attribute_id' => 'color',
        'type' => 'single-select',
        'scope' => 'global',
        'description' => 'Product color attribute',
        'options' => [
            ['action' => 'new', 'value' => 'Red'],
            ['action' => 'new', 'value' => 'Blue'],
            ['action' => 'new', 'value' => 'Green'],
            ['action' => 'new', 'value' => 'Yellow'],
        ],
    ]
]);

$data = json_decode($response->getBody(), true);
JavaScript Example (Fetch API) 
const response = await fetch('https://api.commerceclarity.com/api/v1/attributes/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Color',
    attribute_id: 'color',
    type: 'single-select',
    scope: 'global',
    description: 'Product color attribute',
    options: [
      { action: 'new', value: 'Red' },
      { action: 'new', value: 'Blue' },
      { action: 'new', value: 'Green' },
      { action: 'new', value: 'Yellow' }
    ]
  })
});

const data = await response.json();

Response Example

Success Response 
{
  "success": true,
  "data": {
    "attribute": {
      "_id": "507f1f77bcf86cd799439011",
      "attribute_id": "color",
      "name": "Color",
      "type": "single-select",
      "scope": "global",
      "is_essential": false,
      "description": "Product color attribute",
      "options": {
        "red":    { "value": "Red" },
        "blue":   { "value": "Blue" },
        "green":  { "value": "Green" },
        "yellow": { "value": "Yellow" }
      },
      "family_ids": [],
      "families": [],
      "brand_id": "507f1f77bcf86cd799439010",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}
Error Response - Validation 
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "attribute_id": ["The attribute_id has already been taken."]
  }
}