API Playground

Test the publication state update endpoint.

Authentication Required

You need to Login to test the API playground

Publication State Update Endpoint

Update the publication state of one or more products in your inventory

PUT

This endpoint allows you to update the publication state of one or more products in your inventory. The publication state indicates the lifecycle stage of the product in your catalog, such as whether it is under review, ready to be published, or already published online.

The update can be applied to multiple products simultaneously by providing a comma-separated list of IDs.

Endpoint URL
PUT https://api.commerceclarity.com/inventories/set-publication-state

Request Parameters

Parameter Type Required Description
ids string Required Comma-separated list of product IDs. Can be product code (EAN, ASIN, MINSAN) or SKU
publication_state string Required The new publication state to assign to the products. Accepted values: pending_review, ready, online

Publication States

State Description
pending_review The product is awaiting review before being approved for publication
ready The product has been reviewed and is ready to be published
online The product is currently published and visible online

Response

Success Response
{
  "status": "success",
  "message": "Inventory statuses set"
}
Error Response - Validation
{
  "status": "error",
  "message": "Invalid publication state",
  "errors": [
    "The publication state field is required.",
    "The selected publication state is invalid."
  ]
}

Code Examples

PHP Example (Guzzle HTTP Client)
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.commerceclarity.com',
    'timeout'  => 10.0,
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ]
]);

// Comma-separated list of product IDs
$productIds = '8004120057724,8004120061721,NS-CRIO-001';

// Publication state to set
$publicationState = 'online'; // Possible values: pending_review, ready, online

$requestData = [
    'ids' => $productIds,
    'publication_state' => $publicationState
];

try {
    $response = $client->put('/inventories/set-publication-state', [
        'json' => $requestData
    ]);
    
    $result = json_decode($response->getBody()->getContents(), true);
    
    echo "Status: " . $result['status'] . "\n";
    echo "Message: " . $result['message'] . "\n";
    
} catch (RequestException $e) {
    echo "Error: " . $e->getMessage() . "\n";
    
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        
        echo "Status: " . ($errorResponse['status'] ?? 'unknown') . "\n";
        echo "Message: " . ($errorResponse['message'] ?? 'no message') . "\n";
        
        if (isset($errorResponse['errors'])) {
            echo "Validation errors:\n";
            foreach ($errorResponse['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
}
JavaScript Example (Fetch API)
// Request configuration
const apiUrl = 'https://api.commerceclarity.com/inventories/set-publication-state';
const token = 'YOUR_API_TOKEN';

// Request data
const requestData = {
  ids: '8004120057724,8004120061721,NS-CRIO-001', // Comma-separated list of product IDs
  publication_state: 'online' // Possible values: pending_review, ready, online
};

// Request options
const requestOptions = {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(requestData)
};

// Make the API request
fetch(apiUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      return response.json().then(errorData => {
        throw new Error(errorData.message || `Status: ${response.status}`);
      });
    }
    return response.json();
  })
  .then(data => {
    console.log('Response:', data);
    console.log(`Status: ${data.status}`);
    console.log(`Message: ${data.message}`);
    
    // Example: update the user interface to reflect the updated state
    if (data.status === 'success') {
      // Update the UI with the new publication states
      const productIds = requestData.ids.split(',');
      productIds.forEach(productId => {
        const productElement = document.querySelector(`[data-product-id="${productId}"]`);
        if (productElement) {
          // Update the publication state badge
          const statusBadge = productElement.querySelector('.publication-state-badge');
          if (statusBadge) {
            statusBadge.textContent = requestData.publication_state;
            
            // Update the CSS class based on state
            statusBadge.classList.remove('badge-pending', 'badge-ready', 'badge-online');
            
            switch (requestData.publication_state) {
              case 'pending_review':
                statusBadge.classList.add('badge-pending');
                break;
              case 'ready':
                statusBadge.classList.add('badge-ready');
                break;
              case 'online':
                statusBadge.classList.add('badge-online');
                break;
            }
          }
        }
      });
      
      // Show a confirmation message
      showNotification('Publication state updated successfully', 'success');
    }
  })
  .catch(error => {
    console.error('Error during publication state update:', error.message);
    
    // Example: show an error message to the user
    showNotification(`error: ${error.message}`, 'error');
  });

// Utility function to show notifications
function showNotification(message, type) {
  // Implementation of your notification function
  console.log(`[${type.toUpperCase()}] ${message}`);
}
Python Example (Requests)
import requests
import json

# API Configuration
api_url = 'https://api.commerceclarity.com/inventories/set-publication-state'
token = 'YOUR_API_TOKEN'

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

# Request data
request_data = {
    'ids': '8004120057724,8004120061721,NS-CRIO-001',  # Comma-separated list of product IDs
    'publication_state': 'online'  # Possible values: pending_review, ready, online
}

try:
    # Make the PUT request
    response = requests.put(
        api_url,
        headers=headers,
        json=request_data
    )
    
    # Raise exception for HTTP errors
    response.raise_for_status()
    
    # Extract data from the response
    result = response.json()
    
    print(f"Status: {result['status']}")
    print(f"Message: {result['message']}")
    
    # Example: update a local product registry
    if result['status'] == 'success':
        product_ids = request_data['ids'].split(',')
        
        # Example of updating a local database
        def update_product_publication_state(product_id, state):
            print(f"Updating publication state for product {product_id} to '{state}'")
            # Insert here the logic to update a local database
            # For example: db.execute("UPDATE products SET publication_state = ? WHERE id = ?", (state, product_id))
        
        # Update publication state for each product
        for product_id in product_ids:
            update_product_publication_state(product_id, request_data['publication_state'])
            
        print(f"\nPublication state successfully updated for {len(product_ids)} products")
    
except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")
    if response.text:
        error_data = response.json()
        print(f"Status: {error_data.get('status', 'unknown')}")
        print(f"Message: {error_data.get('message', 'no message')}")
        
        if 'errors' in error_data:
            print("Validation errors:")
            for error in error_data['errors']:
                print(f"- {error}")
        
except requests.exceptions.RequestException as err:
    print(f"Request error: {err}")
cURL Example
curl -X PUT "https://api.commerceclarity.com/inventories/set-publication-state" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
       "ids": "8004120057724,8004120061721,NS-CRIO-001",
       "publication_state": "online"
     }'

Use Cases

Product Approval

Useful for managing a product approval workflow before publication, setting products from pending_review to ready after verification.

Batch Publication

Allows simultaneous online publication of a group of products that have passed the quality control phase.

Temporary Removal

Allows products to be moved from online to pending_review to temporarily remove them from the online catalog without deletion.

Related Resources

Authentication

Learn how to authenticate your API requests with access tokens.

Go to Authentication
Product Analysis

Add new products to your inventory to be able to retrieve their details.

View Endpoint
Product Details

Check the current status of a specific product in your inventory.

View Endpoint