REST API Reference
Flavor exposes its data and operations over the WordPress REST API. Endpoints are spread across three namespaces, one per product:
| Namespace | Base URL | Provided by | Covers |
|---|---|---|---|
ec/v1 | /wp-json/ec/v1/ | WP eCommerce Core plugin | The full commerce + ERP surface — products, cart, checkout, orders, customers, payments, shipping, tax, emails, marketplace, and the whole ERP (invoicing/myDATA, inventory, purchasing, accounting, CRM, HR, ΕΡΓΑΝΗ), plus store settings and role management. |
flavor/v1 | /wp-json/flavor/v1/ | Flavor Starter theme | Storefront + page-builder helpers — theme settings, menus, search, cart totals, wishlist, VAT validation, the visual builder API, and endpoints contributed by individual theme modules (points, bundles, promotions, B2B, quotes, …). |
flavor-core/v1 | /wp-json/flavor-core/v1/ | Flavor Core plugin | The unified Debug/logging API (admin-only): reading, filtering, exporting, and clearing log entries, plus the JS→PHP log bridge sink. |
A separate MCP endpoint at /wp-json/flavor/mcp exposes curated, read-only "abilities" to AI agents. It is not a conventional REST group — see Flavor AI below.
This is a first-party developer reference: it is accurate for building against your own store (admin tooling, headless frontends, integrations, internal automation). It is not a frozen public API contract — routes evolve between releases. For anything mission-critical, pin your integration to a store version and re-check against the OpenAPI spec after upgrades.
The OpenAPI spec (the authoritative endpoint list)
The plugin generates its own OpenAPI 3.0 specification covering the ec/v1 surface. This is the single source of truth for exact paths, methods, parameters, and schemas — always prefer it over any hand-written list (including this page).
1. Enable it (off by default). In the eCommerce admin, open Settings → Developer and turn on:
- API Documentation (
api_docs_enabled) — exposes the spec endpoint. - API Playground (
api_playground_enabled) — enables the interactive tester (optional).
2. Fetch the spec (admin-authenticated):
curl -u "admin:xxxx xxxx xxxx xxxx" \
https://your-site.com/wp-json/ec/v1/docs/openapi.json
The endpoint requires manage_options and the API Documentation toggle — if either is missing it returns 403.
3. Browse it in wp-admin. Two built-in viewers ship with the plugin (both are hidden pages reached by direct URL once enabled):
| Tool | URL | What it is |
|---|---|---|
| API Documentation | wp-admin/admin.php?page=wpec-api-docs | A rendered, browsable view of the OpenAPI spec. |
| API Playground | wp-admin/admin.php?page=wpec-api-playground | An interactive split-panel tester — pick an endpoint (grouped by tag), fill parameters, and send live requests against your store. |
4. Feed it to your tools. Because the spec is standard OpenAPI 3.0, you can point Swagger UI, Postman/Insomnia (import URL), or a client-generator (openapi-generator, orval, etc.) at openapi.json to get typed clients, request collections, or mock servers for free.
The OpenAPI spec currently describes the ec/v1 namespace. The theme (flavor/v1) and Core (flavor-core/v1) routes are documented on this page and in their respective sections, not (yet) in the generated spec.
Authentication
All three namespaces use native WordPress authentication — there is no separate token service or JWT layer in front of them. Which method you use depends on where the request comes from.
Same-origin (nonce)
Requests from the WordPress frontend or admin (the storefront React app, the admin app) authenticate with the standard REST nonce plus the logged-in cookie:
fetch('/wp-json/ec/v1/cart', {
headers: { 'X-WP-Nonce': window.wpApiSettings.nonce },
});
External (Application Passwords)
For integrations, scripts, mobile apps, or anything off-origin, use WordPress Application Passwords (Users → Profile → Application Passwords) with HTTP Basic auth:
curl -u "admin:xxxx xxxx xxxx xxxx" \
https://your-site.com/wp-json/ec/v1/orders
Permissions (what each route requires)
| Access level | Applies to | Enforced by |
|---|---|---|
| Public (no auth) | Catalog reads — GET /products, GET /categories, GET /search, product/brand/attribute reads, published reviews | permission_callback => __return_true |
| Session (any visitor) | Cart + checkout flows (/cart/*, /checkout/*) — tied to the cart session | Session cookie |
| Logged-in customer | Storefront account — /account/* (own orders, addresses, details) | Logged-in user (own data only) |
| Manager / staff | Admin operations under granular capabilities — e.g. wpec_manage_products, wpec_manage_orders, wpec_manage_managers | current_user_can( 'wpec_manage_*' ) |
| Administrator | Everything, plus settings, the OpenAPI spec, and the MCP endpoint | current_user_can( 'manage_options' ) |
The Manager / RBAC capabilities (wpec_manage_*) are granted through the plugin's role manager, so a store can give staff scoped REST access without full manage_options. Every admin route accepts manage_options as a superset. Enumerate the full capability set at GET /ec/v1/managers/capabilities.
ERP routes are license-gated. The ERP groups (invoicing, inventory, purchasing, accounting, CRM, HR) require an active Business-tier license in addition to the capability check — an unlicensed store receives 403 on those paths.
Response format
Response shapes are not globally uniform — treat each endpoint's shape as authoritative from the OpenAPI spec, not from a single envelope assumption. The common patterns are:
Collection endpoints return a data array plus pagination meta:
{
"data": [ { "id": 1, "title": "…" } ],
"meta": { "page": 1, "per_page": 20, "total": 137, "total_pages": 7 }
}
Single-resource reads typically return the resource object directly (no wrapper):
{ "id": 1, "title": "…", "price": 19.9, "variants": [] }
Action endpoints (apply coupon, cart totals, tests) often use a success wrapper:
{ "success": true, "message": "…", "data": { } }
Errors are standard WordPress WP_Error responses:
{ "code": "product_not_found", "message": "Product not found", "data": { "status": 404 } }
Always branch on the HTTP status code first; use code for machine-readable error handling.
ec/v1 — the commerce + ERP surface
The plugin registers 300+ routes across ~37 controllers in ec/v1. Below is a curated index of the endpoint groups — the OpenAPI spec is authoritative for the exact operations and payloads within each.
Storefront & catalog
| Group | Representative paths | Notes |
|---|---|---|
| Products | /products, /products/{id}, /products/slug/{slug}, /products/{id}/duplicate, /products/lookup, /search | CRUD + weighted search + barcode lookup. Rich query params (status, type, category, price, brand, attr_*, sale, rating). See Products. |
| Variants | /products/{id}/variants, /variants/{id}, /products/{id}/variants/reorder | Variable-product variants + drag-reorder. |
| Categories | /categories, /categories/tree, /categories/bulk, /categories/{id} | Hierarchical tree + bulk ops. |
| Attributes | /attributes, /attributes/{id}, /attributes-with-terms, /attributes/{id}/terms, /attributes/terms/{id} | Attributes + terms for filters and the product form. |
| Brands | /brands, /brands/{id}, /brands/search | Public read, admin write. |
| Reviews | /products/{id}/reviews, /products/{id}/rating, /reviews, /reviews/{id}, /reviews/{id}/helpful | Product reviews + ratings + helpful votes. |
Cart, checkout & orders
| Group | Representative paths | Notes |
|---|---|---|
| Cart | /cart, /cart/items, /cart/items/{id}, /cart/clear, /cart/shipping-address, /cart/shipping-method(s), /cart/summary | Session cart. See Cart. |
| Checkout | /checkout, /checkout/settings, /checkout/login, /checkout/create-account, /checkout/check-email, /checkout/payment-methods, /checkout/{id}, /checkout/{id}/complete, /checkout/{id}/validate | Full checkout flow incl. guest→account. |
| Coupons | /coupons/apply, /coupons/remove, /coupons/applied, /coupons/validate, /admin/coupons, /admin/coupons/{id} | Cart-facing apply/remove + admin CRUD. |
| Orders | /orders, /orders/stats, /orders/bulk, /orders/statuses, /orders/{id}, /order-received/{id}, /orders/{id}/status, /orders/{id}/payment-status, /orders/{id}/fulfillment-status | CRUD + bulk + status transitions. See Orders. |
| Order sub-resources | /orders/{id}/items, /orders/{id}/payments, /orders/{id}/shipments, /orders/{id}/courier/* | Line items, payments, shipments, and courier voucher/label/track per order. |
| Customers | /customers, /customers/{id}, /customers/stats, /customers/find-by-email, /customers-with-stats, /customers/{id}/orders|stats|profile|top-products|spending-history, /customers/{id}/addresses, /addresses/{id} | Admin customer records + analytics. |
| My Account | /account, /account/orders, /account/orders/{id}, /account/addresses, /account/addresses/{type}, /account/details, /account/password | Logged-in customer self-service (own data only). |
Payments, shipping & tax
| Group | Representative paths | Notes |
|---|---|---|
| Payments | /payment/methods, /payment/gateways, /payment/gateways/{id}, /payment/refund/{order_id}, /webhooks/payment/{gateway_id}, /payment/stripe/create-intent, /payment/paypal/create-order|capture-order, /payment/eurobank/redirect/{order_id}, /payment/callback/{gateway_id} | Gateway methods, gateway-specific intents, refunds, and inbound webhooks/callbacks. |
| Gateway config | /payment/gateway-config, /payment/gateway-config/{id}, /payment/gateway-config/{id}/test | Admin gateway configuration + connection test. |
| Shipping | /shipping/zones, /shipping/zones/{id}, /shipping/zones/reorder, /shipping/zones/{zone_id}/methods, /shipping/methods/{id}, /shipping/calculate, /shipping/countries, /shipping/stats, /shipping/method-types | Zones, methods, live rate calculation. |
| Courier | /courier/{provider}/test-connection|create-voucher|label/{voucher}|cancel/{voucher}|track/{voucher}, /courier/acs/pickup-list, /courier/settings | Raw courier-provider operations (Geniki / ELTA / ACS). |
| Tax | /tax/classes, /tax/rates, /tax/rates/{id}/toggle, /tax/calculate, /tax/stats, /tax/eu-vat-rates, /tax/countries | Tax classes + rates + calculation. |
Store operations
| Group | Representative paths | Notes |
|---|---|---|
| Emails | /emails/templates, /emails/templates/{type}, /emails/templates/{type}/preview, /emails/test, /emails/resend/{order_id}, /emails/settings | Transactional email templates + test/resend. |
| Dashboard | /dashboard/stats | Admin dashboard aggregates. |
| Settings | /settings, /settings/{section}, /settings/{section}/reset, /settings/options/currencies, /settings/options/countries | Store settings by section + option lists. |
| Marketplace | /marketplace/webhook/{marketplace}, /marketplace/orders, /marketplace/orders/{id}/…, /marketplace/settings, /marketplace/feeds/{marketplace}/…, /marketplace/categories/mapping/{marketplace} | Skroutz / BestPrice feeds + marketplace order sync. |
| Managers (RBAC) | /managers, /managers/{id}, /managers/roles, /managers/roles/{slug}, /managers/capabilities | Staff users, custom roles, and the capability reference. |
ERP (requires Business tier)
| Group | Representative paths | Controller |
|---|---|---|
| Invoicing & myDATA | /invoices, /invoices/{id}/issue|cancel|transmit|cancel-mydata|pdf, /invoices/from-order/{orderId}, /invoice-series, /invoices/mydata/test, /invoices/settings, /invoices/reference-data | InvoiceApiController |
| Inventory / WMS | /warehouses, /warehouses/{id}/set-default|activate|deactivate, /stock/levels, /stock/adjust, /stock/transfer, /stock/stocktake, /stock/movements, /stock/stats | WarehouseApiController + StockApiController |
| Purchasing | /suppliers, /suppliers/{id}/prices, /purchase-orders, /purchase-orders/{id}/send|receive, /purchase-orders/auto-reorder, /goods-received, /supplier-prices | SupplierApiController + PurchaseApiController |
| Accounting / GL | /accounts, /accounts/tree, /fiscal-years, /fiscal-years/{id}/close, /journal-entries, /journal-entries/{id}/post|reverse, /reports/trial-balance|profit-loss|balance-sheet|vat-return|accounts-receivable|accounts-payable | AccountingApiController |
| CRM | /contacts, /contacts/import-customers, /leads, /leads/pipeline, /leads/{id}/move-stage|convert, /activities, /activities/upcoming|overdue, /crm/dashboard|segments|rfm | CrmApiController |
| HR | /employees, /departments, /leave-types, /leave-requests, /leave-requests/{id}/approve|reject|cancel, /time-entries, /employee-documents, /hr/dashboard|who-is-out, /hr/me/* (employee self-service) | HrApiController |
| ΕΡΓΑΝΗ | /ergani/settings, /ergani/test-connection, /ergani/submissions, /ergani/submissions/{id}/retry | ErganiApiController |
| ERP config | /erp/status|activate|deactivate, /erp/users, /erp/roles, /erp/migrate-data/*, /erp/inventory/backfill/*, /erp/onboarding/checklist, /erp/portal-settings | ErpConfigApiController |
flavor/v1 — theme & page-builder surface
The theme registers into flavor/v1 from its core files and from individual modules — module endpoints only exist when that module is active.
Always present (theme core):
| Group | Paths |
|---|---|
| Site | /settings (currency, pages, feature flags), /menus/{location}, /search (products/posts/pages), /cart/totals (with promotions applied) |
| Wishlist | /wishlist, /wishlist/{product_id} |
| VAT validation | /validate-vat — Greek AFMs → AADE, others → VIES; returns { valid, name, address, … } |
| Page builder | /builder/layout/{id} (GET/POST), /builder/preview/{id}, /builder/blocks, /builder/render, /builder/templates, /builder/templates/{id} |
| Presets & assets | /presets, /presets/{category}/{slug}, /icons, /newsletter/subscribe |
Module-contributed (only when the module is active): /recently-viewed, /bundles, /points/balance, /points/transactions, /promotions, /promotions/cart, /quotes, /products/names, /labels/product/{id}, /b2b/groups, /b2b/my-group, /recover-cart/{token}.
Builder endpoints require edit_posts / edit_post; storefront reads are generally public.
flavor-core/v1 — Debug API
The Flavor Core plugin exposes the unified logging/debug system over flavor-core/v1 (all admin-only):
/debug/entries · /debug/stats · /debug/settings · /debug/clear · /debug/download · /debug/diagnostics · /debug/test · /debug/opcache-reset · /debug/js-log (the JS→PHP log bridge sink).
This is the API behind the in-admin Debug Viewer — the same unified log store that the flavor_log(), wpec_log(), flavor_core_log() and window.flavorLog() helpers write to.
AI / MCP endpoint
Flavor Core stands up a custom MCP (Model Context Protocol) server at:
/wp-json/flavor/mcp
It exposes a curated, read-only set of "abilities" to AI agents (Phase 1). It is transport-level admin-gated (manage_options) and authenticated with WordPress Application Passwords; abilities are additionally license- and capability-checked, PII-redacted, and rate-limited per user. This is not a conventional REST group — see the Flavor AI (Abilities & MCP) developer guide for the ability contract and client setup.
Rate limiting & CORS
- Commerce endpoints (
ec/v1/flavor/v1) have no built-in global rate limit by default. - The MCP/AI surface enforces per-user limits (per-minute and per-day) at the ability layer — see the AI guide.
- CORS is handled by WordPress. For headless setups on a different origin, set the allowed origins/headers in your server config or via the
rest_pre_serve_requestfilter (includeX-WP-NonceandAuthorizationinAccess-Control-Allow-Headers).
Where to go next
- Products · Orders · Cart — worked examples for the core commerce resources.
- Authentication — nonce, cookie, and Application Password details.
- The OpenAPI spec — the authoritative, machine-readable list of every
ec/v1operation.