REST API
The
sprcm/v1namespace: every route, who can call it, and the three public endpoints the storefront uses.
Everything the admin screens do goes through REST, so you can script anything a merchant can click. This page lists the routes, then covers the things that trip people up when they call them from code.
The namespace
/wp-json/sprcm/v1/One namespace, registered by Free. It's identical on a Free-only store and a Free + Pro store. Pro adds only its license routes.
That's deliberate. If Pro owned a route, deactivating Pro would take away either the authoring screens or the merchant's own numbers, so reads and writes both belong to Free. If you're building an add-on, register your routes under the same namespace with sprcm_rest_namespace().
Admin routes
Every admin route needs a logged-in user with the right capability and a valid REST nonce, on reads as well as writes. Where the table says PUT, WordPress also accepts POST and PATCH for the same handler.
| Route | Methods | Purpose | Capability |
|---|---|---|---|
/recommendations | GET POST | List Recommendations (page, per_page up to 100, status, search, orderby, order) and create one | sprcm_manage_recommendations |
/recommendations/<id> | GET PUT DELETE | Read, update and delete one | sprcm_manage_recommendations |
/recommendations/bulk-delete | POST | Delete several (ids, 1–100) with a single republish | sprcm_manage_recommendations |
/catalog/search | GET | Product and term search for the builder's pickers | sprcm_manage_recommendations |
/publish | POST | Rebuild and republish the snapshot | sprcm_manage_recommendations |
/recommendation-manager | GET PUT | Coordination settings and the priority order | sprcm_manage_recommendations |
/settings | GET PUT | The Settings screen's values | sprcm_manage_recommendations |
/export | GET | The configuration file out (scope: all or specific, with ids) | sprcm_manage_recommendations |
/import | POST | The configuration file in | sprcm_manage_recommendations |
/preview | POST | Run a document through the real engine (name, document) | sprcm_manage_recommendations |
/dashboard | GET | Everything the Dashboard screen shows | sprcm_manage_recommendations |
/analytics/summary | GET | The Analytics screen's figures for one range (range, plus from + to for a custom one) | sprcm_view_analytics |
/analytics/orders | GET | The Revenue by Order report, paged (range, from, to, rec, page) Pro | sprcm_view_analytics |
/license | GET | The License panel's state Pro | sprcm_manage_recommendations |
/license/activate | POST | Activate a license key on this site Pro | sprcm_manage_recommendations + manage_options |
/license/deactivate | POST | Release this site's activation Pro | sprcm_manage_recommendations + manage_options |
/license/refresh | POST | Re-check the stored license now (at most once a minute) Pro | sprcm_manage_recommendations + manage_options |
A user without sprcm_view_analytics can still load /dashboard. They get the structure (counts, the list of Recommendations) with the measured figures left out.
/analytics/orders exists on every install, but on a store without Pro it answers 403 sprcm_locked. The route stays in Free so the report can't vanish with Pro. What's gated is the report behind it.
Public routes
Three, all used by the storefront's script. They're open to guests, so each one is hardened with a signed credential and a rate limit instead of a login.
| Route | Method | Purpose | Default limit |
|---|---|---|---|
/hydrate | POST | Fills every recommendation slot on one page, for this shopper, in one call | 60 / min |
/events | POST | Receives view, click and add-to-cart beacons | 120 / min |
/dismiss | POST | Records that a shopper closed a popup, so it stays closed for the rest of the day. Only Pro's popup display uses it Pro | 20 / min |
/hydratetakes a signed page token issued with the page's HTML. It resolves the whole page in one request (one per page, not one per block) and accepts up to 20 slots./eventsand/dismisstake the signed reference printed on the block they belong to (data-sprcm-ref), so nobody can forge events or dismissals for arbitrary Recommendations./dismissnever takes the shopper's word for what was dismissed. It reads that from the reference.
Limits are per client, per minute. Tune them with sprcm_rate_limit. If your store is behind a CDN or load balancer, declare its client-IP header with sprcm_trusted_proxy_headers, or every shopper shares one bucket.
Authentication
Admin routes need a logged-in user with the right capability and a valid wp_rest nonce, sent as an X-WP-Nonce header (or a _wpnonce query parameter). From JavaScript in wp-admin, wp.apiFetch handles it. From PHP or WP-CLI, send it yourself:
$request = new WP_REST_Request( 'GET', '/sprcm/v1/settings' );
$request->set_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) );
$response = rest_do_request( $request );A missing nonce looks exactly like a broken setting
Without the nonce, every call (reads included) comes back 403 sprcm_invalid_nonce with the message "Your session expired. Reload the page and try again." If you're scripting against these routes and everything fails, check the nonce first.
Capabilities
| Capability | Who has it by default | What it unlocks |
|---|---|---|
sprcm_manage_recommendations | Administrator, Shop manager | Every authoring route, plus the Dashboard and the license panel |
sprcm_view_analytics | Administrator, Shop manager | The two /analytics/ routes |
manage_options | Administrator | Store-wide operations on top of the above: a replace import, the Clean-up Data on Deletion setting, and changing the license (activate, deactivate, refresh) |
Because sprcm_view_analytics is separate, you can give someone a role that sees the numbers without letting them change what renders.
The manage_options operations live on routes shop managers can otherwise use, so they're refused per operation rather than per route. A shop manager who saves Settings with delete_data_on_uninstall in the body gets a normal 200, and the key comes back in a skipped list instead of being written. A shop manager who tries a replace import gets a 403.
Working with the routes
Read the registries from the server
Don't hardcode the valid tokens for contexts, filters, sorts, displays or locations. They depend on the tier and on what's installed, so a hardcoded list drifts. Read them from the server instead:
wp eval 'print_r( ShapedPlugin\ShapedRecommend\Admin\App::payload()["builder"] );' --user=1Or, on any Shaped Recommend admin screen, from the browser console:
window.sprcmAdmin.builderContexts and locations are scoped to each other
If you change a document's context and leave a product_* location on it, that placement gets pruned, and every token you're testing then looks dead for a reason that has nothing to do with the token. Pair each context with a location that can actually serve it.
Omit status to keep it
On PUT /recommendations/<id>, leave status out and the Recommendation keeps the status it has. There are only two values: live, shown on screen as Active, and paused, shown as Inactive. There's no draft state. A create with no status asks for live.
/preview is the real engine
POST /preview runs your document through the same resolver, gate map and templates the storefront uses, against a sample request. It's the honest way to check whether a configuration produces anything, and it's what the builder's Live Preview pane calls. It writes no events.
Settings
GET /settings returns the stored values, plus may_elevate (whether you hold manage_options) and the list of elevated keys. PUT writes them. Three keys are writable:
| Key | Type | Notes |
|---|---|---|
hide_native | object: related, upsells, crosssells → boolean | Hides WooCommerce's own sections. See slot replacement |
delete_data_on_uninstall | boolean, default false | The Clean-up Data on Deletion toggle. Needs manage_options. Only Free's uninstall reads it. Deleting Pro never removes Free's data |
stats_cache_hours | integer 1–168, default 24 | No control in the admin screens. REST is the only way to change it |
Any other key fails the whole write with 400 sprcm_invalid_settings. Nothing is applied unless everything validates.
stats_cache_hours sets how long the plugin trusts a figure derived from orders: how long a windowed popularity ranking is cached, and how often Pro consolidates its mined Store Statistics data. To store a different value:
$request = new WP_REST_Request( 'PUT', '/sprcm/v1/settings' );
$request->set_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) );
$request->set_header( 'Content-Type', 'application/json' );
$request->set_body( wp_json_encode( [ 'stats_cache_hours' => 12 ] ) );
rest_do_request( $request );Two things to know before you rely on this
Send a JSON body. The handler reads only the JSON body. set_body_params() doesn't reach it, so you get a cheerful 200 with skipped: [] and the value unchanged, which reads exactly like a refused write.
Pro's mining schedule doesn't move on its own. Pro The popularity cache picks up a new value as soon as each ranking expires. Pro's recurring consolidation job, though, is scheduled once, with the value in force at the time, and writing a new one doesn't reschedule it. To pick it up, deactivate and reactivate Pro, or run a pass yourself with wp sprcm stats rebuild.
Export returns an envelope
GET /export returns { filename, envelope }. The filename looks like sprcm-config-2026-10-07.json, and the envelope is the file's contents. Recommendations are listed in priority order, so importing them elsewhere keeps your ordering.
Import takes file contents, not an upload
POST /import's file parameter is the file's contents as a string, not a multipart upload.
$request = new WP_REST_Request( 'POST', '/sprcm/v1/import' );
$request->set_header( 'X-WP-Nonce', wp_create_nonce( 'wp_rest' ) );
$request->set_body_params( [
'file' => file_get_contents( '/path/to/sprcm-config-2026-10-07.json' ),
'mode' => 'merge', // or 'replace'
] );
rest_do_request( $request );merge (the default) adds the file's Recommendations alongside yours. replace wipes the existing configuration first and needs manage_options. Both answer with the mode, the imported count and a report of anything that didn't come across. Files larger than 1 MB are refused unless you raise sprcm_import_max_bytes.
Analytics ranges are enforced server-side
range takes a preset: 7d, 14d or 30d on Free, plus 90d, 12mo and all with Pro Pro. For a custom range, send range=custom with from and to (Y-m-d, site time). With no range at all you get 30d.
The ceiling applies to the window that resolves, not to the token that asked for it. On Free, a 31-day custom range is refused rather than quietly cut to 30. A range past the ceiling comes back 403 sprcm_range_locked, naming the ceiling. A range that can't be read (say, a start date after the end date) comes back 400 sprcm_invalid_range.
Errors
Standard WordPress REST error shapes, with sprcm_-prefixed codes. The ones you'll meet most:
| Code | Status | Meaning |
|---|---|---|
sprcm_forbidden | 401 / 403 | Missing capability |
sprcm_invalid_nonce | 403 | Missing or expired nonce |
sprcm_invalid_document | 400 | A Recommendation failed validation |
sprcm_invalid_settings | 400 | A settings write failed validation |
sprcm_import_rejected | 400 / 403 | The import file was refused (403 for a replace without manage_options) |
sprcm_not_found | 404 | No Recommendation with that ID |
sprcm_locked | 403 | The report isn't available on this plan |
sprcm_range_locked | 403 | The analytics range is past this plan's ceiling |
sprcm_rate_limited | 429 | A public route's limit was reached |
sprcm_invalid_token | 403 | /hydrate got a missing or tampered page token |
Validation failures return a report rather than a partial write: nothing is applied unless all of it validates. The error's data carries the first problem and the full list.
Extending
If you want to contribute recommendations rather than read them, don't call these routes. Register a source with sprcm_register_source(). A source goes through the Recommendation Manager like every other candidate producer, which the REST layer deliberately can't do for you. To adjust an existing pool, filter sprcm_candidates.
Next
- Hooks: the extension seam.
- WP-CLI
- Performance: where
/hydratefits in the request lifecycle.