Overview
Woo Visibility Sync Mattrs extends WooCommerce with advanced control over product and category visibility through the REST API.
It was built to solve a common problem for store owners and developers: managing how products appear across different contexts, integrations, and visibility layers without losing sync between frontend, admin, and API data.
With this plugin, you can:
- Dynamically toggle product visibility across REST endpoints and the WooCommerce store.
- Ensure category visibility logic behaves predictably – visible categories automatically expose their products unless specifically overridden.
- Expose and manage visibility states programmatically via custom REST API routes.
- Maintain full compatibility with WooCommerce core and third-party integrations.
It’s ideal for projects where data visibility needs to be automated, filtered, or synchronised with external systems – such as mobile apps, headless stores, or custom dashboards.
Key Features
- REST-Driven Control
Manage product and category visibility directly through WooCommerce’s REST API or via custom endpoints introduced by the plugin. - Granular Visibility Rules
Define visibility per product and per category with smart fallback logic that avoids conflicts and redundancy. - Intelligent Category Overrides
When a category’s visibility is set to “visible”, its products follow automatically unless explicitly excluded. - Lightweight, Native Integration
Built entirely within WooCommerce and WordPress standards, no external dependencies or bloat. - Developer-Friendly Architecture
Hookable filters, modular PHP classes, and a clean JS admin layer designed for extensibility. - Consistent Data via API
Visibility states are exposed in REST responses for seamless integration with headless apps or 3rd-party clients. - Uses JWT Auth if available with graceful fallback
Integration and Internal Logic
The WVSM REST Products Control plugin extends WooCommerce’s REST API to deliver clean, filtered product data that respects user roles, pricing tiers, and visibility rules already defined within WordPress.
The plugin centralises all filtering in the backend – ensuring that relevant, authenticated users receive the correct data via REST endpoints.
Integrated Plugins
The system internally integrates and respects the following third-party plugins:
- Products Visibility by User Roles – by Addify
Filters products based on user role access, ensuring restricted products remain hidden from unauthorised API requests. - Role Based Pricing for WooCommerce – by Addify
Delivers accurate role-specific pricing in REST responses without exposing internal pricing logic client-side. - User Roles Editor for WooCommerce – by FME Addons
Handles flexible role creation and assignment, extending how user roles interact with REST access permissions. - Hide Variations by User Roles – by Addify
Allows selective exposure of product variations within the REST API, improving control for wholesale catalogues.
All logic from these plugins is applied server-side, ensuring data exposed through /wvsm/v1/ remains consistent with WooCommerce’s internal visibility and pricing settings.
Architecture
The plugin follows a modular, namespaced structure under WVSM\ADMIN and WVSM\API namespaces.
Core Components
- Admin UI – Adds a clear visibility selector in the product and category edit screens.
- REST Layer – Registers custom REST endpoints and fields to expose and update visibility status.
- Logic Layer – Synchronises product and category rules, ensuring consistency across frontend, backend, and API.
- Data Layer – Uses product meta and taxonomy terms to store visibility states efficiently.
Example: Custom REST Endpoint
GET /wp-json/wvsm/v1/products
Returns a structured response with visibility data:
[
{
"id": 1524,
"name": "Organic Black Pudding Rings",
"category_visibility": "parent_visible"
},
{
"id": 1525,
"name": "Vegan Haggis"
}
]
Example: Update Visibility via API
(API currently inactive)
POST /wp-json/wvsm/v1/visibility/products/1525
Request body:
{ "visibility": "visible" }
Response:
{ "success": true, "message": "Product visibility updated." }
Authentication System
Authentication Overview
Woo REST Products Visibility is built with flexible, layered authentication that adapts to your environment:
- JWT Auth (preferred) – If a JWT authentication plugin is installed, the system detects it dynamically using either the
JWT_AUTH_PLUGIN_FILEconstant or thejwt_auth_validate_token()function. This ensures compatibility with the official JWT Authentication for WP REST API plugin and its forks. - WordPress Auth (fallback) – If JWT is unavailable, it automatically falls back to native WordPress authentication methods such as cookies, Application Passwords, or OAuth.
- Server Token (optional) – For internal or cron-based integrations, an optional token can be defined in
wp_optionsaswvsm_api_token. This provides secure automated access without requiring user login. - Secure Failure Handling – If authentication fails, WordPress responds with the standard REST error:
{ "code": "rest_forbidden", "message": "Sorry, you are not allowed to do that.", "data": { "status": 401 } }
In practice, the authentication flow ensures that endpoints remain protected without introducing additional dependencies or breaking compatibility with existing REST workflows.
Example: Authenticating API Requests
Using JWT Token
If a valid JWT plugin is active and a token has been obtained via /wp-json/jwt-auth/v1/token, include it in the header of your request:
curl -X GET "https://example.com/wp-json/wvsm/v1/products" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi..." \
-H "Content-Type: application/json"
Response:
[
{
"id": 1541,
"name": "Organic Black Pudding Rings"
}
]
Using WordPress Auth (Fallback)
If JWT is unavailable, you can rely on Application Passwords or Cookie Auth.
Example with Application Passwords:
curl -X POST "https://example.com/wp-json/wvsm/v1/products/1525" \
-u "admin:abcd efgh ijkl mnop" \
-H "Content-Type: application/json"
Using Server Token (Internal Integrations)
If your integration runs internally (e.g. via cron or local service), you can configure an optional server token.
Set it in WordPress options:
update_option('wvsm_api_token', 'your-secret-token');
Then include it in your API call:
curl -X GET "https://example.com/wp-json/wvsm/v1/products" \
-H "X-WVSM-Server-Token: your-secret-token"
This provides secure, minimal authentication for scheduled jobs or trusted internal scripts.
Admin Integration
The admin UI uses a modular jQuery script that dynamically renders visibility options and synchronizes them with backend values.
A Thickbox modal component provides context-sensitive info and settings (debugged extensively during development to ensure consistent rendering even on plugin screens with query strings).
Development Process
Phase 1 – Requirements Clarification
The client’s initial brief centered on simplifying visibility management for complex product catalogs.
Through iterative clarification, the key insight emerged: category visibility should logically override product visibility, ensuring predictable hierarchy behavior.
This required balancing usability (for store managers) with API accuracy (for developers).
Phase 2 – Core Development
The plugin was developed using an object-oriented approach.
Early prototypes focused on exposing visibility states through WooCommerce’s REST layer, followed by admin UI integration.
Refactoring involved:
- Consolidating data logic into distinct classes (
ProductVisibility,CategoryVisibility). - Introducing
PluginInfofor metadata display and structured documentation within the WordPress admin. - Simplifying REST registration to improve extensibility for future channels (like per-role or per-storefront visibility).
Phase 3 – Testing & Tools
A lightweight Python-based test application was built to simulate REST API requests and validate data integrity.
This test app allowed rapid iteration over visibility states, ensuring predictable outcomes across dozens of product–category combinations.
The app’s key functions included:
- GET and POST requests against
/wp-json/wvsm/v1/...routes - Automated validation of response structure and propagation rules
- Regression checks during refactors
This streamlined the QA phase and provided a reusable framework for future REST integrations.
Testing Authentication
The Python test app also includes authentication tests for both JWT and fallback modes.
It validates token handling and fallback to WordPress auth, ensuring consistent 401 rest_forbidden responses when invalid credentials are supplied.
Challenges & Solutions
Category–Product Logic Complexity
Challenge: Ensuring intuitive yet deterministic visibility behavior when both product and category have conflicting visibility states.
Solution: Implemented a rule engine that prioritises explicit product-level visibility, with category-level fallback.
Modal Content Rendering
Challenge: Thickbox modal content failing to load when WordPress admin screens used query strings.
Solution: Rewrote the JS logic to detect and relocate hidden modal content dynamically, ensuring consistent behaviour across all admin contexts.
Data Sync Across REST and Admin
Challenge: Avoiding stale data when updates occurred through either the admin UI or API.
Solution: Introduced hooks that trigger cross-layer synchronization and invalidate caches as needed.
Outcome
The final plugin delivers a robust, developer-friendly system for managing WooCommerce product visibility via REST.
It provides a clean user interface for admins while exposing a stable, extensible API layer for developers and integrations.
It’s now used internally and available as a reference architecture for more complex WooCommerce integrations.
Future Roadmap
- Role-based and channel-based visibility layers
- Integration with custom post types beyond products
- Webhooks for visibility change events
- Improved UI with React-based controls
About Web Design Mattrs
At Web Design Mattrs, we craft digital products that balance creativity and technical depth.
From custom WordPress development to API-driven integrations, we believe in focusing on what mattrs: usability, performance, and maintainability.
We built this plugin as part of our ongoing mission to make WooCommerce more flexible for developers and store owners alike.
