WooCommerce

WooCommerce Developer Documentation: Product Tagging & Enrichment Pipeline

Welcome to the Helium Pulse developer documentation for WooCommerce integration. This guide walks you through the end-to-end setup required to enable automated product tagging and enrichment for WooCommerce stores. Brands using this integration will generate REST API keys, enabling our system to securely access their product data, enrich it using AI by flattening complex tag structures, and sync it back seamlessly as WooCommerce Product Meta Data and Tags.

1. API Client Configuration

1.1 Generating WooCommerce REST API Keys

To enable our integration, you will need to generate REST API keys from your WordPress admin dashboard where WooCommerce is installed. This is typically found under WooCommerce > Settings > Advanced > REST API.
Click "Add key" or "Create an API key."
Provide a Description (e.g., "Helium Pulse Integration").
Select the User this key will be associated with. This user should have sufficient permissions (typically an Administrator or Shop Manager role, or a custom role with necessary capabilities).
Set Permissions to Read/Write.
Click "Generate API key." WooCommerce will then display the Consumer Key and Consumer Secret. These are displayed once and should be securely copied and stored.
Helium Pulse will use the Consumer Key and Consumer Secret to authenticate with the WooCommerce REST API.

1.2 Required User Capabilities

The WordPress user associated with the API keys needs the following capabilities (typically included in "Administrator" or "Shop manager" roles):

read_products: To fetch product data.
edit_products: To create and update product information, including meta data and tags.
manage_woocommerce_webhooks: To create and manage webhook subscriptions for real-time product updates (if using webhook-based sync).

These permissions allow us to fetch products, create and update product meta data with AI-generated data, and manage native product tags.

2. Product Fetching

2.1 Fetch Products via WooCommerce REST API

We use the WooCommerce REST API (typically /wp-json/wc/v3/products) to fetch your store’s products. Products are retrieved in batches using pagination (page and per_page parameters).

GET /wp-json/wc/v3/products?per_page=100&page=1

2.2 Example Request (Conceptual Node.js using Basic Auth with API Keys)

const axios = require('axios');
const base64 = require('base-64'); // For Basic Auth encoding

async function fetchProducts(siteUrl, consumerKey, consumerSecret, page = 1, perPage = 100) {
  const url = `${siteUrl}/wp-json/wc/v3/products?per_page=${perPage}&page=${page}`;
  const credentials = base64.encode(`${consumerKey}:${consumerSecret}`);

  const response = await axios.get(url, {
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    }
  });
  // Product data is in response.data (an array of products)
  // Pagination info is in response.headers (e.g., 'x-wp-totalpages', 'x-wp-total')
  return response.data;
}

// Example usage:
// const products = await fetchProducts('https://yourstore.com', 'YOUR_CONSUMER_KEY', 'YOUR_CONSUMER_SECRET');

3. Change Detection & Sync Triggers

3.1 Webhook Support (Optional)

WooCommerce supports webhooks which can notify our system of product changes in near real-time. Webhooks can be configured under WooCommerce > Settings > Advanced > Webhooks.

Relevant webhook topics include:

product.created
product.updated
product.deleted (for maintaining data consistency)

Delivery URL will be provided by Helium Pulse. The secret will be used to verify the webhook payload.

If webhooks are configured, WooCommerce sends an HTTP POST notification with the product data (or ID). We then process this data.

3.2 Daily Sync Option (Filtering by Modification Date)

For stores not utilizing webhooks, or as a fallback, we perform a scheduled sync. We fetch products updated since the last successful sync using the modified_after or date_modified_gmt (depending on specific needs and server timezone configurations) filter in ISO8601 format.

GET /wp-json/wc/v3/products?modified_after=YYYY-MM-DDTHH:MM:SSZ&per_page=100

Alternatively, using date_modified_gmt:

GET /wp-json/wc/v3/products?after=YYYY-MM-DDTHH:MM:SSZ&per_page=100

(Note: after queries products published after a certain date. For modifications, modified_after is more common if available, or a manual check of date_modified_gmt post-fetch is needed if direct filtering isn't robust for all setups). The WooCommerce REST API supports modified_after for products.

4. Enrichment Pipeline & Data Flattening

Once products are fetched, our AI pipeline:

Analyzes product name, short description, description, categories, tags, attributes, and images.
Generates a rich, structured JSON object containing tags related to persona, usage, functional aspects, and visual details (see example below).
Flattens this JSON object: Nested keys are combined with underscores, and a prefix h_ is added to create unique meta data keys. For example, tags.visual.color.primary.value becomes h_tags_visual_color_primary_value.

Example AI-Generated Tag Object:

{
    "sector": "apparel",
    "subcategory": "kurta",
    "category": "tops",
    "tags": {
        "persona": {
            "age_group": ["young adults", "adults"],
            "price_range": "mid-range",
            "gender": ["female"]
        },
        "usage": {
            "season": ["spring", "summer"],
            "occasions": ["everyday", "casual"]
        },
        "functional": {
            "eco_friendly": false
        },
        "visual": {
            "pattern": "checked",
            "material": ["viscose"],
            "color": {
                "primary": {
                    "value": "green",
                    "shade": "medium"
                }
            }
        }
    }
}

Flattened Attributes Ready for WooCommerce Meta Data:

h_sector: "apparel"
h_subcategory: "kurta"
h_category: "tops"
h_tags_persona_age_group: ["young adults", "adults"] (Arrays can be stored directly)
h_tags_persona_price_range: "mid-range"
h_tags_persona_gender: ["female"]
h_tags_usage_season: ["spring", "summer"]
h_tags_usage_occasions: ["everyday", "casual"]
h_tags_functional_eco_friendly: "false" (Boolean converted to string, or stored as boolean if preferred and consistently handled)
h_tags_visual_pattern: "checked"
h_tags_visual_material: ["viscose"]
h_tags_visual_color_primary_value: "green"
h_tags_visual_color_primary_shade: "medium"

5. Sync to WooCommerce (Product Meta Data)

Enriched data, after flattening, is stored as Product Meta Data in WooCommerce. Each flattened key-value pair is added to the meta_data array of the product.

5.1 Managing Product Meta Data

When updating a product, we include a meta_data array. Each item in the array is an object with key and value.

Fetching Existing Meta Data: Product meta data is typically included when a product is fetched.
Creating or Updating Meta Data: We send the complete list of Helium-managed meta data. If a meta key (e.g., h_tags_visual_color_primary_value) already exists for the product from a previous Helium sync, its value is updated. If it doesn't exist, it's created.

PUT /wp-json/wc/v3/products/{product_id}

{
  // ... other product fields if being updated simultaneously ...
  "meta_data": [
    {
      "key": "h_sector",
      "value": "apparel"
    },
    {
      "key": "h_subcategory",
      "value": "kurta"
    },
    {
      "key": "h_tags_persona_age_group",
      "value": ["young adults", "adults"] // WooCommerce stores this as a serialized array
    },
    {
      "key": "h_tags_persona_price_range",
      "value": "mid-range"
    },
    {
      "key": "h_tags_functional_eco_friendly",
      "value": "false" // Or `false` (boolean), API handles serialization
    },
    {
      "key": "h_tags_visual_color_primary_value",
      "value": "green"
    }
    // ... other Helium-generated meta data items
  ]
}

To avoid overwriting meta data managed by other plugins or users, Helium Pulse specifically manages meta keys prefixed with h_.

6. Native Tag Injection (WooCommerce Product Tags)

WooCommerce has a built-in taxonomy for "Product Tags." We can push the top 2-3 most salient keywords from our enrichment into this native tagging system.

This is done by updating the tags array in the product payload. Each tag is an object containing name or id. If sending name, WooCommerce will create the tag if it doesn't exist or use the existing one.

PUT /wp-json/wc/v3/products/{product_id}

{
  // ... other product fields and meta_data ...
  "tags": [
    {"name": "kurta"},
    {"name": "green top"},
    {"name": "casual wear"},
    {"name": "apparel"}
    // These tags will be added to the product. Existing tags managed by the user should be preserved if possible by fetching them first and merging.
  ]
}

Important: When updating tags, it's crucial to fetch the product's existing tags first and merge them with the Helium-generated tags to avoid inadvertently removing tags manually added by the store owner, unless the strategy is to fully overwrite tags from Helium.

7. Daily Enrichment Summary

7.1 Delta CSV & Summary Report

Every enrichment cycle generates a CSV file detailing the changes made (Product ID/SKU, updated meta data keys (flattened codes), new values, new tags, timestamp).
A summary report is also created.

7.2 Email Notification

An automated summary email is sent daily to your brand team.
It includes the number of products enriched and a link to download the CSV report.

8. Best Practices

Rate Limits: While WordPress/WooCommerce don't have hard rate limits by default like SaaS platforms, server performance and hosting limitations act as de facto limits. We implement request throttling and process updates in manageable batches. Some security plugins or hosting providers might impose rate limits.
Efficient Updates:
- Use the ?_fields= parameter when fetching data to retrieve only necessary product fields, reducing payload size.
- Update products in batches using the /wp-json/wc/v3/products/batch endpoint where appropriate for bulk creation/update/deletion to reduce HTTP request overhead.
Meta Data Management: The h_ prefix for meta keys ensures that Helium Pulse only manages its own data, preventing conflicts.
Tag Management: Be cautious when updating native product tags. Always fetch existing tags and merge unless the explicit goal is to overwrite.
Error Resilience: Robust error handling and retry mechanisms are implemented for transient API issues or server errors.
Security: Ensure the WordPress site uses HTTPS. API keys should be stored securely and have the minimum necessary permissions.
Testing: All integrations are thoroughly tested on staging/development WooCommerce sites before deployment to production.

9. Technical References

This documentation can be extended to include:

Detailed strategies for merging native product tags.
Handling product variations and their specific meta data.
Client-side SDK integration for deeper brand-side observability.
Webhook signature verification using the webhook secret.
Advanced error logging and structured retry handling.

For any questions, please contact your Helium Pulse onboarding engineer.

PreviousAkeneo

Last updated 14 days ago