REST API | StoreCrafted

Integrators and custom admin tooling can drive Store Maintenance Checklist through the WordPress REST API. Merchants normally use the React UI under WooCommerce > Maintenance Checklist; this page documents the same stmc/v1 surface that UI uses.

Conventions

Item	Value
Base path	`/wp-json/stmc/v1`
Capability	`manage_woocommerce` on every route
CSRF	Cookie authentication plus WordPress REST nonce (`X-WP-Nonce`)
Errors	Standard `WP_Error` JSON: `code`, `message`, `data.status`
Datetimes	ISO 8601 UTC strings

HTTPS: Use HTTPS on production. Application Passwords or cookie+nonce over HTTPS are appropriate for remote tools.

Authentication

Log in as a user with manage_woocommerce.
Send X-WP-Nonce: {wp_rest nonce} with requests (the plugin admin shell uses apiFetch with a localized nonce).

Application Passwords

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  https://example.com/wp-json/stmc/v1/scan

Replace USERNAME and APPLICATION_PASSWORD with a WordPress Application Password for a shop manager or administrator.

Permissions: Users without manage_woocommerce receive 401 / 403. There is no public read of scan or export data.

Capability matrix

Group	Methods and paths
Scan	`GET /scan` · `POST /scan` · `GET /scan/status` · `POST /scan/cancel` · `POST /scan/retry`
Ignores	`POST /checks/{id}/ignore` · `DELETE /checks/{id}/ignore`
History	`GET /history` · `DELETE /history`
Settings	`GET /settings` · `PUT /settings`
Export	`GET /export/csv`

All require manage_woocommerce.

Response envelope patterns

Success responses return JSON objects described below (except CSV export, which returns raw CSV).

Error example:

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": { "status": 403 }
}

Conflict when a scan is already running:

{
  "code": "stmc_scan_in_progress",
  "message": "A scan is already in progress.",
  "data": { "status": 409 }
}

Exact error codes may vary by handler (stmc_scan_in_progress, cancel/retry conflicts, stmc_unknown_check); treat HTTP status as authoritative for client branching (409 busy / nothing to cancel, 404 unknown check id).

Scan

`GET /scan`

Latest results plus status for Checklist bootstrap.

Response 200: status, summary, environment, findings (open/ignored), passed, last_completed_at.

When never scanned: status.state is idle, empty findings, null or zero summary, last_completed_at null.

`POST /scan`

Start a scan. Body {} or omitted.

Response 202: { "status": { "state": "running", … } }

409 if a scan is already running.

`GET /scan/status`

Lightweight polling for progress. Suggested client poll: about 2.5s while running and not stalled; about 10s when stalled.

`POST /scan/cancel`

Stop further Action Scheduler batches; keep last completed partial results; may write history if progress occurred.

409 if nothing to cancel.

`POST /scan/retry`

After a stalled run, re-queue remaining catalog work; clear stalled; keep findings already collected.

Response 202. 409 if not in a retryable stalled/running state.

Finding shape

{
  "id": "payments.gateway_test_mode",
  "title": "Payment gateway in test / sandbox mode",
  "severity": "critical",
  "area": "payments",
  "status": "open",
  "why": "Live customers may not be charged…",
  "evidence": {
    "summary": "Enabled gateway stripe reports test mode.",
    "count": 1,
    "samples": [{ "label": "stripe", "url": "https://example.com/wp-admin/…" }]
  },
  "primary_action": {
    "label": "Open Payments settings",
    "url": "https://example.com/wp-admin/admin.php?page=wc-settings&tab=checkout"
  },
  "further_tools": [],
  "ignore_reason": null,
  "score_excluded": false,
  "change": "unchanged"
}

Field	Notes
`severity`	`critical` \| `warning` \| `info` \| `passed`
`status`	`open` \| `ignored` \| `passed`
`change`	`new` \| `resolved` \| `unchanged` \| `worsened` \| `null`
`further_tools`	Empty when disabled in settings or none mapped
`score_excluded`	True when ignored or always-unscored link-out

Ignore / restore

`POST /checks/{id}/ignore`

{ "reason": "Expected for this store" }

reason optional, max 200 UTF-8 characters.

404 stmc_unknown_check if {id} is not a registered check id.

`DELETE /checks/{id}/ignore`

Restore a previously ignored check. Same 404 for unknown ids.

History

`GET /history`

Query: environment (optional), search (optional), per_page (default 10, max 10).

Returns { "items": [ … ] } with score, counts, environment, provisional, terminal state, and change markers.

`DELETE /history`

Clears history summaries only. Response { "deleted": true }. Does not clear live findings or ignores.

Settings

`GET /settings`

{
  "force_production_severity": false,
  "show_further_tools": true,
  "max_products": 1000,
  "max_variations": 2000,
  "ignored_count": 1,
  "constants": {
    "force_production_defined": false
  }
}

`PUT /settings`

Partial or full body. Products/variations are clamped to allowed bounds (100–10000 / 100–20000, step 100). Returns the full settings object.

See Settings for merchant meanings.

CSV export

`GET /export/csv`

Raw CSV download (no JSON wrapper):

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="store-maintenance-checklist-findings.csv"

Includes open + ignored findings only. Cells that look like spreadsheet formulas are prefixed with ' for safety.

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  -o findings.csv 
  https://example.com/wp-json/stmc/v1/export/csv

cURL quick start

Read latest scan:

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  https://example.com/wp-json/stmc/v1/scan

Use a WordPress Application Password for a user with manage_woocommerce. WooCommerce REST consumer keys alone are not enough unless they authenticate as such a user.

Start scan:

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  -X POST 
  https://example.com/wp-json/stmc/v1/scan

Ignore a check:

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  -X POST 
  -H 'Content-Type: application/json' 
  -d '{"reason":"Staging sandbox"}' 
  https://example.com/wp-json/stmc/v1/checks/payments.gateway_test_mode/ignore

Action Scheduler (internal)

Not part of the public REST surface, but useful for ops:

Hook / group	Purpose
Group `stmc`	All plugin actions
`stmc/scan/catalog_batch`	Product chunk
`stmc/scan/variation_batch`	Variation chunk
`stmc/scan/finalize`	Score, history, completed

Inspect under WooCommerce > Status > Scheduled Actions.

Conventions

Authentication

Cookie + nonce (same as wp-admin)

Application Passwords

Capability matrix

Response envelope patterns

Scan

GET /scan

POST /scan

GET /scan/status

POST /scan/cancel

POST /scan/retry