# WakeMyCart integration reference — 0.13

The current normal engine uses the v2 routes below. Legacy cloud shopper APIs are not for new integrations; migrated stores reject them.

Recovery in Free 0.13.0 and later runs entirely through the local WordPress API without a WakeMyCart account or monthly contact quota. Account endpoints below remain authenticated and serve optional account services and Pro licensing.

## Account service

| Route | Method | Access and behavior |
| --- | --- | --- |
| `/api/workspace` | GET | Account session. Local-mode account, registration, grants, aggregate usage and coarse health. No shopper/cart records. All-legacy accounts retain their legacy workspace until migration. |
| `/api/stores` | POST | Verified owner. Register `{name,url}` and return a connection code. New registrations use the local engine. |
| `/api/stores/:id/registry` | PUT | Owner password/MFA. Edit name/URL; URL changes require reconnection. |
| `/api/stores/:id/connection-code` | POST | Owner password/MFA. Obtain the current connection code. |
| `/api/stores/:id/disconnect` / `reconnect` | POST | Owner password/MFA. Revoke/renew account connection. Local Free continues independently; cached Pro grants can remain valid until expiry. Pause WordPress locally to stop sending. |
| `/api/stores/:id/delete` | POST | Owner password/MFA and exact name. Remove a disconnected registration while preserving issued capacity. Unexpired legacy compatibility blocks removal. |
| `/api/account/download/pro` | GET | Eligible paid account session. Private Pro ZIP; no public Pro static path. |
| `/api/control/allocations/:period` | PUT | Agency owner. Monotonic per-store monthly allocation; issued capacity cannot move mid-month. |

Account signup, verification, login, password/email change, MFA and billing endpoints retain their documented account authorization. Check the account and pricing pages for current registration and payment availability.

## Store control protocol

`POST /api/v2/pair` accepts the connection code, exact store URL, installation UUID, protocol and plugin versions. Subsequent requests bind HMAC-SHA256 to protocol, store, installation, key ID, HTTP method, exact path, timestamp, nonce and SHA-256 of raw JSON, joined with newlines. Send `X-WMC-Store`, `X-WMC-Installation`, `X-WMC-Key-ID`, `X-WMC-Time`, `X-WMC-Nonce`, and `X-WMC-Signature`. Replayed, stale, mismatched or disconnected requests are rejected.

| Suffix under `/api/v2/stores/:id/` | Method | Contract |
| --- | --- | --- |
| `entitlements` | GET | RSA publisher-signed plan, capabilities, store/installation/epoch and expiry |
| `quota` | POST | `{period,allocation_revision,unlimited_contacts?,free_unlimited_contacts?}`; signed grant with carried usage and additional capacity. Updated Free does not need a grant. |
| `usage` | PUT | `{period,grant_id,report_seq,contacts_used}`; monotonic aggregate only |
| `health` | PUT | `{engine_protocol,plugin_versions,engine_state,attention_codes}`; fixed coarse codes only |
| `updates/free` / `updates/pro` | GET | Publisher-signed manifest; Pro requires an eligible plan |
| `download-ticket` | POST | `{edition,version}`; short-lived bearer ticket for the exact package path |
| `disconnect` | POST | Empty body; revoke this connection |
| `migration/prepare`, `manifest`, `page`, `refresh`, `ack` | POST | Reviewed legacy handover; bounded encrypted export pages and verified counts/digest |

`GET /api/v2/packages/:edition/:version` requires the ticket in `Authorization: Bearer …`. Package bytes must match the signed SHA-256; never put ticket secrets in URLs. Normal control payloads reject added shopper fields. Normal controls and migration page requests have separate per-store rate limits.

Updated clients advertise `X-WMC-Free-Unlimited: 1`. Pre-update Free clients keep their historical 100-contact compatibility grant; this negotiation never unlocks Pro. The retired hosted sender retains its historical cap until migration.

## Merchant WordPress REST

The local workspace uses `/wp-json/recoverkit/v2/ui/…` or equivalent `?rest_route=` paths. Every UI request requires the WordPress login, current `X-WP-Nonce`, and the appropriate local recovery capability. Pro gates are rechecked server-side. Basic sequences and the reminder-frequency setting are available in both editions. `monthlyReminderLimit` accepts 1–100 and starts at 3 on new installations; saved shopper permission can impose a lower limit.

| Suffix | Purpose |
| --- | --- |
| `workspace`, `capture`, `pause` | Local view and explicit capture/sending switches |
| `provider`, `test-email`, `email-branding`, `email-design`, `sequence` | Merchant sender, own-user test, branding, editable basic sequences and the shared `monthlyReminderLimit` setting |
| `flows`, `flows/:id`, `flows/simulate`, `offers`, `coupon-safeguards` | Versioned flow edits, simulation and local offers |
| `reports/flows`, `reports/orders`, `reports/products`, `reports/experiments`, `reports/client` | Detailed local reporting and Agency branded HTML download |
| `health`, `queue`, `queue/:id/resolve` | Guided checks and explicit uncertain-delivery review |
| `migration/…` | CartFlows settings preview and local-engine legacy import |
| `advanced-settings`, `connection`, `disconnect`, `refresh` | Compatibility allowlists, uninstall choice and account binding |
| `agency/…` | WordPress staff/client permissions, templates, target credentials and reviewed rollout |

`POST disconnect` pauses local recovery, removes local account credentials and cached current/future grants, and preserves usage/frequency/history even if the remote service is unavailable. Its `remoteCleanupConfirmed` and `message` fields distinguish successful remote removal from local-only detachment. Re-enabling Free remains an explicit merchant action.

`PUT email-branding` accepts only `logoUrl` (HTTPS or empty), `accentColor` (six-digit hex) and `useBrandColors` (boolean). It is available to Free and Pro and merges those basic fields while preserving saved paid settings. `PUT email-design` retains its Pro gate. Free previews, tests and delivery project saved designs to those basic fields; premium layouts and translations remain gated.

`/recoverkit/v2/email-webhook/:revision` verifies the provider signature over the raw request with that provider revision’s secret. `/recoverkit/v2/agency/flow` requires HTTPS, authenticated WordPress application-password access and local flow permission. Temporary `/recoverkit/v2/legacy-link` verifies the old shared secret, timestamp and single-use nonce. Public local recovery/unsubscribe links use opaque purpose-bound tokens and confirmation; they never require a paid license to unsubscribe.


## Browser account requests

Account actions require the signed-in user and the relevant store or owner permission. Mutations use the same HTTPS origin, JSON Content-Type and X-RecoverKit-Client: dashboard. Sensitive changes require password confirmation and MFA when enabled. Never place connection codes, session cookies, application passwords or download tickets in public scripts, URLs or support messages.

## Legacy integrations and troubleshooting

Older cloud installations can use signed v1 compatibility routes until migration is complete. Do not send shopper data to those routes from a new local installation. Follow https://wakemycart.com/docs/migration before changing an existing integration.

A failed authentication or integrity check must not be bypassed. Check the store connection, current plugin version and request timestamp. Contact support with the operation, time and redacted error; exclude shopper records and credentials. Protocol and data-flow guidance: https://wakemycart.com/docs/developer-api and https://wakemycart.com/docs/data-privacy.