Skip to content

REST API ​

The sprcm/v1 namespace: 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.

RouteMethodsPurposeCapability
/recommendationsGET POSTList Recommendations (page, per_page up to 100, status, search, orderby, order) and create onesprcm_manage_recommendations
/recommendations/<id>GET PUT DELETERead, update and delete onesprcm_manage_recommendations
/recommendations/bulk-deletePOSTDelete several (ids, 1–100) with a single republishsprcm_manage_recommendations
/catalog/searchGETProduct and term search for the builder's pickerssprcm_manage_recommendations
/publishPOSTRebuild and republish the snapshotsprcm_manage_recommendations
/recommendation-managerGET PUTCoordination settings and the priority ordersprcm_manage_recommendations
/settingsGET PUTThe Settings screen's valuessprcm_manage_recommendations
/exportGETThe configuration file out (scope: all or specific, with ids)sprcm_manage_recommendations
/importPOSTThe configuration file insprcm_manage_recommendations
/previewPOSTRun a document through the real engine (name, document)sprcm_manage_recommendations
/dashboardGETEverything the Dashboard screen showssprcm_manage_recommendations
/analytics/summaryGETThe Analytics screen's figures for one range (range, plus from + to for a custom one)sprcm_view_analytics
/analytics/ordersGETThe Revenue by Order report, paged (range, from, to, rec, page) Prosprcm_view_analytics
/licenseGETThe License panel's state Prosprcm_manage_recommendations
/license/activatePOSTActivate a license key on this site Prosprcm_manage_recommendations + manage_options
/license/deactivatePOSTRelease this site's activation Prosprcm_manage_recommendations + manage_options
/license/refreshPOSTRe-check the stored license now (at most once a minute) Prosprcm_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.

RouteMethodPurposeDefault limit
/hydratePOSTFills every recommendation slot on one page, for this shopper, in one call60 / min
/eventsPOSTReceives view, click and add-to-cart beacons120 / min
/dismissPOSTRecords that a shopper closed a popup, so it stays closed for the rest of the day. Only Pro's popup display uses it Pro20 / min
  • /hydrate takes 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.
  • /events and /dismiss take the signed reference printed on the block they belong to (data-sprcm-ref), so nobody can forge events or dismissals for arbitrary Recommendations. /dismiss never 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:

php
$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 ​

CapabilityWho has it by defaultWhat it unlocks
sprcm_manage_recommendationsAdministrator, Shop managerEvery authoring route, plus the Dashboard and the license panel
sprcm_view_analyticsAdministrator, Shop managerThe two /analytics/ routes
manage_optionsAdministratorStore-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:

bash
wp eval 'print_r( ShapedPlugin\ShapedRecommend\Admin\App::payload()["builder"] );' --user=1

Or, on any Shaped Recommend admin screen, from the browser console:

js
window.sprcmAdmin.builder

Contexts 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:

KeyTypeNotes
hide_nativeobject: related, upsells, crosssells → booleanHides WooCommerce's own sections. See slot replacement
delete_data_on_uninstallboolean, default falseThe Clean-up Data on Deletion toggle. Needs manage_options. Only Free's uninstall reads it. Deleting Pro never removes Free's data
stats_cache_hoursinteger 1–168, default 24No 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:

php
$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.

php
$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:

CodeStatusMeaning
sprcm_forbidden401 / 403Missing capability
sprcm_invalid_nonce403Missing or expired nonce
sprcm_invalid_document400A Recommendation failed validation
sprcm_invalid_settings400A settings write failed validation
sprcm_import_rejected400 / 403The import file was refused (403 for a replace without manage_options)
sprcm_not_found404No Recommendation with that ID
sprcm_locked403The report isn't available on this plan
sprcm_range_locked403The analytics range is past this plan's ceiling
sprcm_rate_limited429A public route's limit was reached
sprcm_invalid_token403/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 ​