Status: v1 (2026-09-30). The public specification of how any e-commerce platform connects to Spaidoo.
1 What a connector is
Spaidoo gives an online shop a widget (save for later, lists, price-drop alerts, search) and a set of communication actions (mailing, push, posts). The widget works on any site with a single <script> tag. A connector is the piece of software that lives inside a shop platform (a module, an app, a plugin, a headless backend…) and lets Spaidoo do the things a script alone cannot:
| Capability | What it adds |
|---|---|
catalog.feed | Spaidoo knows the shop's products (price, stock, images) — required |
catalog.changes | Price and stock changes reach Spaidoo in seconds instead of on the next daily read |
storefront.saveAnchors | The connector prints the save buttons in the theme (§7); Spaidoo's admin tells the merchant they come from the connector |
identity | A customer signed in to the shop keeps their saved products on every device, without a Spaidoo account |
customers | Spaidoo can ask the shop for the email (and marketing consent) of an identified customer when the merchant needs it |
customerLookup | The customers route also answers by email: the merchant can import lists from a file exported from another wishlist app |
marketingConsent | When a customer signed in to the shop says yes, in the widget, to the shop's emails, Spaidoo asks the shop to turn their email-marketing consent on |
customerErase | Deleting a customer in the shop deletes their Spaidoo data for that shop |
wishlistImport | Lists from a previous wishlist extension are brought into Spaidoo |
push | Web push notifications are served from the shop's own domain |
domainVerification | The shop proves it owns its domain without DNS changes |
billing.platform | The platform bills the shop's Spaidoo plan and tells Spaidoo which plan it is (§4.12). Only for apps Spaidoo has enabled for it |
panel.widget | The connector has its own panel in the platform's admin (install, appearance, status, import): Spaidoo's admin sends the merchant there instead of repeating those screens |
Rule of the contract: Spaidoo decides what to do from the capabilities a connector declares, never from the name of its platform. Any platform can build a connector; the platform field is informative only.
A connector may implement any subset, as long as catalog.feed is present.
2 Conventions
- Base URL for connector → Spaidoo calls:
https://api-plugin.spaidoo.com/connector/v1 - JSON in and out, UTF-8.
Content-Type: application/json. - Times are Unix seconds (integers) unless a field says otherwise.
- Ids of the shop (customer id, product id) are strings, even if the platform uses numbers.
- Money is a decimal string with a dot (
"19.90") plus an ISO 4217 code. - Languages are ISO 639-1 codes (
es,ca,en); currencies ISO 4217 (EUR). - Forward compatibility: both sides MUST ignore fields they do not know. New optional fields and new capabilities may appear within v1. Anything that breaks an existing connector goes to
/connector/v2. - Errors from Spaidoo: HTTP status + body
{ "errorCode": "SOME_CODE", "message": "human text" }. A body that does not match the route is400 VALIDATION_ERROR, withdetails: [ { field, message } ]. Only401means the API key is not valid any more (the shop disconnected, or its key was replaced): the connector must show "disconnected". A403is about that one call, never about the key: itserrorCodesays why (INTEGRATION_REQUIRES_PLAN, a plan the shop does not have, §4.19;SHOP_NOT_VERIFIED, a domain not proven yet, §4.10), and the connector stays connected. The401'serrorCodeisAPI_KEY_MISSING(noAuthorization: Bearerheader) orAPI_KEY_INVALID(a key Spaidoo does not know); its body also keepsvalid: falseanderrorfor older readers.429carriesRetry-After; the API's general rate limit answerserrorCode: "RATE_LIMITED", a route's own limit its own code (CATALOG_CHANGES_RATE_LIMIT…). Any5xxor network failure means "try later": a connector MUST keep working (the shop must never break) when Spaidoo does not answer.
2.1 The two secrets
| Secret | What it is | Used for |
|---|---|---|
| API key | Opaque string issued at pairing | Authorization: Bearer <apiKey> on every connector → Spaidoo call |
| Identity secret | 32 random bytes, base64url, issued by Spaidoo | HMAC signatures: identity assertions (§5) and verifying Spaidoo → shop calls (§6) |
Both are secrets of the shop. They MUST be stored server-side and never printed in pages.
3 Pairing
A shop connects with OAuth 2 and PKCE (RFC 6749, RFC 7636), as a registered connector app. The API key never goes through a browser or a URL.
3.1 Register your connector
Register the connector once in the partners' area of developers.spaidoo.com (My connectors) and you get its client_id (sc_…, public). There are two kinds of app:
redirectMode | For | Callback (redirect_uri) |
|---|---|---|
fixed | A connector hosted by you or by the platform (the merchant's admin is not on the shop's domain) | One of the redirectUris you register, exact match |
shop | A connector installed in each shop (a module, a plugin) | An https URL on the domain of the shop being connected (or a subdomain of it); nothing to register |
serverDomains: the domains where your server routes (urls.customers) may live besides the shop's domains (§4.1).
adminDomains and billingPlatform are set by Spaidoo, not by you: ask for them when your platform bills its apps itself (an app marketplace with its own billing). billingPlatform: true (only for fixed apps) lets your connector declare billing.platform; adminDomains are the domains of the platform's admin where urls.billing and urls.panel may live (§4.1, §4.12).
platform is free text matching ^[a-z0-9-]{2,32}$ (my-platform, my-headless-shop, acme-commerce…). A suspended app connects no new shop; the shops already connected keep working.
A fixed app also gets a client_secret (scs_…), shown once when you create it; you can rotate it from My connectors (the old one stops working at once). Keep it on your server: it is what lets your connector sign shops up itself (§3.4).
3.2 The flow
- Your server generates a random
stateand acode_verifier(43–128 characters of[A-Za-z0-9-._~]), keeps both, and computescode_challenge = base64url(SHA-256(code_verifier))without padding. - Your admin page opens a popup (
window.open, about 460×780, from the merchant's click) at:https://admin.spaidoo.com/connect?client_id=sc_…&redirect_uri=…&state=… &code_challenge=…&code_challenge_method=S256 &domain=shop.example.com&name=<shop name>&email=<merchant email> &mode=signup|login&verify=<urls.verify>&lang=<iso>domainis required;name,email,mode(the tab that opens first),verify(only withdomainVerification) andlangare optional. - Spaidoo checks the
client_idand theredirect_uri. If either is wrong it shows the error and never redirects. - The merchant signs up or signs in and accepts the terms. A shop that already exists in Spaidoo's directory is only handed over once its domain is proven (§3.3).
- Spaidoo sends the popup to
redirect_uri?code=…&state=…. If the merchant cancels:redirect_uri?error=access_denied&state=…; a malformed request:error=invalid_request. - Your server checks
stateand trades the code within 60 seconds (a code is good for one exchange):
POST /pairing/token — the only call without an API key:
{ "client_id": "sc_…", "code": "…", "code_verifier": "…", "redirect_uri": "<the same one>" }→ 200 { "apiKey": "…", "shopId": "…" }. Errors: 400 OAUTH_INVALID_GRANT (unknown, expired or used code, or client_id, redirect_uri or code_verifier do not match), 403 CONNECTOR_APP_SUSPENDED.
- Store the key server-side and call
POST /handshake(§4.1). Theredirect_uripage then tells your admin page (postMessagetowindow.opener, your own origin only, never the key) and closes the popup; your admin page shows the shop connected.
3.3 A shop of Spaidoo's directory
When the domain already belongs to a shop in Spaidoo's directory and the request carries verify, Spaidoo first sends the popup to:
redirect_uri?state=…&verification_code=spaidoo-verify-…&resume=https://admin.spaidoo.com/connect?…Your callback checks state, stores the code so urls.verify serves it (§4.9), keeps the code_verifier, and sends the popup to resume exactly as it came. Spaidoo reads the code at urls.verify and carries on; the code arrives later on the same callback, with the same state. Without verify, the merchant proves the domain by hand with a file (§4.9).
A new shop connects straight away; its connector proves the domain afterwards, with its key, before publishing (§4.9).
3.4 Provisioning: your server signs the shop up (hosted apps)
When the platform's admin must not send the merchant to sign in somewhere else, a fixed app can sign the shop up from its server, with the data the platform already vouches for. The account it creates has no password: the merchant comes into Spaidoo's admin through POST /sso (§4.11) and accepts Spaidoo's terms there before changing anything.
POST /pairing/provision (no API key):
{ "client_id": "sc_…", "client_secret": "scs_…", "domain": "shop.example.com", "name": "<shop name>", "email": "<merchant email>",
"verify": "https://shop.example.com/…/verify", "lang": "es", "panel_url": "https://admin.platform.example/store/my-shop/apps/spaidoo" }→ 201 { "provisionToken": "…", "state": "new" | "claim" | "ready", "verificationCode": "spaidoo-verify-…" | null }
lang(optional): the shop's own language, a short tag:xx,xx-YYorxx-Yyyy(es,pt-BR,zh-Hant;_works too). Spaidoo keeps its two letters. A shop created now takes it as its own: the language it writes its texts in (primaryLanguage, §4.14–§4.17) when the alerts speak it, and the one of the emails Spaidoo sends the merchant. Without it, the request's language. It does not change a shop that already exists.panel_url(optional,https, up to 500): where the merchant manages Spaidoo inside the platform's admin; the button of the welcome email Spaidoo sends leads there. Only for Spaidoo's own apps (below); a partner app's is ignored.resend_confirmation(optional, boolean): the merchant asked for the email ofSHOP_LINK_CONFIRMATION_REQUIREDagain (below). Send it only on their click.claim: the domain belongs to a shop of Spaidoo's directory. ServeverificationCodeatverify(§4.9) before completing.ready: a shop your app connected before (the app reinstalled) comes back as it was, in its account. A shop of the account that the merchant connected through another app is not yours to take: it goes throughSHOP_LINK_CONFIRMATION_REQUIREDlike a new one, and once the account says yes your app gets a new key (the other app's stops working).409 SHOP_LINK_CONFIRMATION_REQUIRED: the email has an account your app created, and this shop is not in it (another shop of the same merchant, or someone who typed that email in their own shop). The platform vouches for the shop, not for the email, so the shop is not added: Spaidoo emails that account a link, valid for 24 hours, that adds it once the inbox's owner clicks. Nothing is created until then. Tell the merchant to check their inbox and callPOST /pairing/provisionagain every few seconds while they look: once they click, it answers201and the flow goes on. Asking again does not send another email;resend_confirmation: truedoes, at most once a minute and three times per request. An account gets at most five such requests a day, and after it answers «not mine» from the link, your app gets no new email for that domain for 30 days.409 SHOP_LINK_UNAVAILABLE: as above, but no email could go now (that «not mine», or the account's share of the day): tell the merchant so, not «check your inbox», and ask again much later (an hour).- Spaidoo's own apps (the ones Spaidoo itself publishes in a platform's app marketplace, not a partner's): the platform hands over the domain and only the shop's owner can install the app, so that is the proof. A directory shop is handed over at once:
state: "ready",verificationCode: null, nothing to serve. A partner's app always proves the domain. 409 EMAIL_ALREADY_REGISTERED(the email has an account your app did not create) or409 SHOP_HAS_OWNER(the domain has an owner): nothing is created; send the merchant through the flow of §3.2 to sign in.400 DOMAIN_NOT_VERIFIABLE:domainis not a bare host name that can be proven (a port, an IP address, credentials).429 CLAIM_RATE_LIMIT_EXCEEDED: too many proofs asked for that domain; try later.401 OAUTH_INVALID_CLIENT: unknown app, wrong secret, or not afixedapp.403 CONNECTOR_APP_SUSPENDED.
POST /pairing/provision/complete { "client_id", "client_secret", "provision_token" } → 200 { "apiKey": "…", "shopId": "…" }. The token is valid for one hour, once, and only for the app that asked for it: 401 ONBOARDING_EXPIRED otherwise (start again with POST /pairing/provision). For claim, Spaidoo reads the code at verify first: 403 SHOP_NOT_VERIFIED while it is not there.
Then store the key and call POST /handshake (§4.1), as after §3.2.
3.5 POST /shop-redact — erase what an uninstalled connector brought (hosted apps)
Some platforms tell their apps, a while after a shop uninstalls them, to erase that shop's customer data (a compliance webhook that arrives, say, 48 hours after the uninstall). By then the connector may have dropped the shop's API key, so a fixed app proves itself with its client secret (§3.1), like in §3.4. No API key:
{
"client_id": "sc_my_platform_app",
"client_secret": "scs_Q2xpZW50U2VjcmV0T2ZUaGVIb3N0ZWRBcHA",
"shopId": "7f3c2a10-5b1e-4c8a-9f0d-2e6b8a4c1d90"
}→ 200 {"customersErased": 42, "contactsErased": 7, "pushDevicesErased": 12, "productsErased": 398, "productsKept": 14, "eventsErased": 9120}
- Only for a shop connected through that app and uninstalled (
POST /uninstall, §4.4):409 SHOP_STILL_CONNECTEDotherwise.404 NOT_FOUNDif the app never connected that shop.401 OAUTH_INVALID_CLIENT,403 CONNECTOR_APP_SUSPENDEDas in §3.4. - Erased, everything the connector brought: the catalogue, every figure of the shop (events, daily counters, read history), every customer of the shop known to Spaidoo with their lists and their link to a Spaidoo account (what
POST /customers/erasedoes for one, §4.7), the anonymous visitors' saves of the shop, the emails given to the shop for its alerts, and the browsers subscribed to its push notifications. - Kept: the shop in Spaidoo (it is public from Spaidoo), and always a Spaidoo account's lists: a broken link leaves the account its products, and a product an account keeps stays, out of sale (
productsKept). - Re-runnable: a call cut halfway is finished by the next one; repeating it erases nothing more.
4 Connector → Spaidoo
All calls: Authorization: Bearer <apiKey>.
4.1 POST /handshake — declare what the connector can do
Call it after pairing, after every connector update, and whenever an URL or capability changes. It is idempotent.
{
"contractVersion": 1,
"platform": { "id": "my-platform", "version": "3.2.0", "name": "My Platform" },
"connector": { "version": "2.0.0" },
"storeUrl": "https://shop.example.com",
"storeName": "My Shop",
"testShop": false,
"capabilities": {
"catalog.feed": true,
"catalog.changes": true,
"identity": true,
"customers": true,
"customerLookup": true,
"marketingConsent": true,
"customerErase": true,
"wishlistImport": false,
"push": true,
"domainVerification": true,
"storefront.saveAnchors": true,
"billing.platform": true,
"panel.widget": true
},
"urls": {
"identity": "https://shop.example.com/spaidoo/identity",
"login": "https://shop.example.com/login?back={back}",
"customers": "https://shop.example.com/spaidoo/customers",
"marketingConsent": "https://shop.example.com/spaidoo/marketing-consent",
"verify": "https://shop.example.com/spaidoo/verify",
"pushWorker": "https://shop.example.com/spaidoo/push-sw.js",
"billing": "https://admin.platform.example/store/my-shop/apps/spaidoo/plans",
"panel": "https://admin.platform.example/store/my-shop/apps/spaidoo"
},
"storefront": {
"pushScope": "/spaidoo-push/",
"domains": ["shop.example.com", "my-shop.platform.example"],
"excludePaths": ["^/checkout", "^/cart"]
},
"identitySecretFingerprint": "<sha256 hex of the identity secret it holds, or null>"
}- Every URL MUST be
https. Storefront URLs (identity,login,pushWorker), which the widget calls from the customer's page, andverify, which proves the domain, MUST be on one of the shop's domains. Server URLs (customers,marketingConsent), which Spaidoo calls signed, MAY also be on one of theserverDomainsof the app the shop connected with (§3.1). An URL is required only for a declared capability that needs it. storeName(optional, up to 100 characters): the shop's name on the platform, as its customers see it. Spaidoo renames the shop when it changes there, so the widget's texts follow a rename («My Shop will email you»). A name the merchant set in Spaidoo's admin stays until the platform's name changes again. Send it on every handshake; send the handshake again when the shop is renamed.testShop:truewhen the platform says this is a development or test shop (a partner development store, a staging install). It stays out of Spaidoo's figures, and once uninstalled for 30 days without its domain ever verified, Spaidoo deletes it with its data. Omitted meansfalse.storefront.domains: other domains the storefront is served on (a platform subdomain and the shop's own domain, say), bare host names. The widget works on all of them; publishing still needs the proof of thestoreUrldomain (§4.9).loginMUST contain the literal, unencoded marker{back}; the widget replaces it with the page to return to.storefront.excludePaths: regular expressions (case-insensitive) over the path + query where the widget must never run. The widget never loads on the cart, the checkout or the payment pages: list them all (as in the example). The connector SHOULD also not print the script there (§7); this list is the safety net. Spaidoo's loader also skips the usual cart and checkout paths on its own (/cart/,/checkout/,/carrito/…), but a platform's own paths may differ.storefront.pushScope(withpush): the push worker's scope (§7.1). Absent:/spaidoo-push/.- Connecting is not publishing. A shop connecting now (its first handshake, or the first after
POST /uninstall) starts with the widget inpreview(§4.10), unless it was alreadylive: reconnecting a public shop does not take the widget away from its customers. A connector update changes nothing. - A declared domain (
storeUrlorstorefront.domains) that already belongs to another shop of Spaidoo with a proven owner is left out of the widget's domains, without an error; Spaidoo's support looks into it. The rest of the handshake applies. identitySecretFingerprint: lets a connector that lost its secret (reinstalled, restored from a backup) get a new one on its own.null= it holds none.platform.name(optional, up to 50 characters): the platform's name as merchants know it. Spaidoo's admin uses it in its texts («your plan is billed by …»);platform.idstays the technical, informative id.panel.widgetandurls.panel: the connector has its own panel in the platform's admin, where the merchant installs and sets the widget up, sees its state and imports lists. Spaidoo's admin then hides the screens that would repeat it and links tourls.panelinstead. Likeurls.billing,urls.panelMUST behttpson one of the app'sadminDomains; without them the capability is refused (left out). Any platform with a panel may declare it.billing.platformandurls.billing: the platform bills the shop's Spaidoo plan (§4.12).urls.billingis the admin page where the merchant picks or changes the plan; Spaidoo's admin sends the merchant there instead of offering its own checkout. It MUST behttpson one of theadminDomainsof the app the shop connected with (§3.1). The capability is accepted only when that app hasbillingPlatformenabled by Spaidoo; otherwise it is refused like any switched-off capability (left out, not an error).
Response 200:
{
"shopId": "7f3c…",
"contractVersion": 1,
"capabilities": { "catalog.changes": true, "identity": true, "…": "…" },
"identitySecret": "b64url…"
}capabilitiesare the ones Spaidoo accepted. The connector must behave according to this list. A capability is refused (left out, not an error) when Spaidoo has it switched off;customers,customerLookup,marketingConsentandwishlistImportare refused withoutidentity;billing.platformis refused unless the app hasbillingPlatform.customerLookupusesurls.customers.identitySecretis present when the connector must store a new one (§4.2).
Errors: 400 CONNECTOR_CATALOG_REQUIRED (no catalog.feed), 400 CONNECTOR_URL_INVALID with field (a declared capability's URL missing, not https on an allowed domain, or login without the unencoded {back}; for billing.platform, only when the app has billingPlatform), 400 CONNECTOR_EXCLUDE_PATH_INVALID.
4.2 Identity secret delivery and rotation
- Spaidoo issues the secret at handshake time and returns it in
/handshakeand/statusresponses until the connector confirms it. POST /identity-secret/ack{ "fingerprint": "<sha256 hex of the secret>" }→200 { "acknowledged": true }(falseif it is not the current secret). The connector MUST ack every secret it receives, after storing it.POST /identity-secret/rotate→200 { "shopId": "…", "identitySecret": "…" }: the merchant asks for a new one.409 CONNECTOR_NOT_CONFIGUREDwhen Spaidoo did not acceptidentityfor this shop.- While Spaidoo has the identity switched off,
ackandrotateanswer404 NOT_FOUND. - Grace period: after a rotation, Spaidoo keeps accepting assertions signed with the previous secret and keeps signing its own calls with the previous secret until the new one is acked, and for 10 minutes after the ack. A connector that loses a response keeps working.
4.3 GET /status — heartbeat and state
Call it when the merchant opens the connector's panel (and at most every few minutes otherwise).
{
"shopId": "7f3c…",
"identitySecret": "b64url…",
"connector": { "contractVersion": 1, "platform": "my-platform", "version": "2.0.0", "capabilities": { "catalog.feed": true }, "urls": {}, "storefront": { "excludePaths": [] } },
"store": {
"name": "Mi tienda", "plan": "growth", "status": "active", "verified": true, "identityOn": true,
"scriptUrl": "https://widget.spaidoo.com/loaders/7f3c….js",
"adminUrl": "https://admin.spaidoo.com",
"billing": { "provider": "platform", "plan": "growth", "status": "trialing" },
"termsAccepted": true, "termsVersion": "2026-09-10",
"termsUrls": { "es": "https://…/es/", "en": "https://…/en/" },
"stats": { "savedProducts": 1840, "widgetOpens": 9120, "historyProducts": 15230, "catalogueProducts": 412, "productVisits": 318,
"audience": { "total": 640, "shopIdentified": 210, "spaidooAccount": 95, "anonymous": 335 }, "followers": 0,
"alertsSent": 96, "alertClicks": 21 },
"feeds": [ { "language": "es", "url": "https://shop.example.com/spaidoo/feed?lang=es", "type": "url", "source": "plugin" } ],
"feedHistory": [ { "initProcess": "2026-10-04T06:00:00.000Z", "endProcess": "2026-10-04T06:00:41.000Z", "results": [ { "language": "es", "type": "url" } ] } ],
"pluginConfig": {
"mode": "live", "domains": ["shop.example.com"],
"desktop": { "showButton": true, "position": "bottom-right", "orientation": "vertical", "chatAI": false, "showSearchButton": false },
"mobile": { "showButton": true, "position": "custom", "offsets": { "bottom": 96, "right": 16 }, "orientation": "vertical", "chatAI": false, "showSearchButton": false },
"theme": "dark", "accent": "#0A0A0A", "icon": "bookmark", "productCircle": true,
"saveAnchors": { "position": "top-right", "product": true, "list": true, "header": true },
"searchProvider": { "type": "none" }, "aiProvider": { "type": "none" }
}
}
}| Field | What it is |
|---|---|
identitySecret | Present only while there is a secret to deliver (§4.2) |
connector | What Spaidoo holds from the last handshake (below) |
store.plan | The plan the shop uses now: starter · growth · pro. It can be higher than the billed one (a trial or a grant from Spaidoo) |
store.status | active (the shop is listed in Spaidoo's portal) or pending_review. It does not stop the widget |
store.verified | The domain is proven (§4.9): needed to publish (live) |
store.identityOn | The identity (§5) works for this shop right now |
store.billing | { provider, plan, status }: who bills the plan (platform · stripe · internal), the billed plan, and its status in the vocabulary of §4.12 (active · trialing · frozen · cancelled). The details: GET /billing (§4.12) |
store.termsAccepted | The shop accepted the version of Spaidoo's terms in force. While false, the writes of §4.10 and the imports (§4.8) answer 409 TERMS_NOT_ACCEPTED (§4.13) |
store.termsVersion | The version of the terms in force (YYYY-MM-DD). A new version turns termsAccepted back to false |
store.termsUrls | The text of the terms, by language (es, en): link it next to the acceptance |
store.stats | Totals for the panel (below) |
store.feeds | The catalogue feeds Spaidoo holds, by language: { language, url, type: "url" | "upload", source?: "plugin" }. source: "plugin" = published by the connector (§4.5) |
store.feedHistory | The last 10 catalogue reads, newest first: { initProcess, endProcess, results: [ { language, type, error?, notReady?, … } ], retryAt? }. Times are ISO 8601 strings here. Informative: more fields may appear |
store.catalogSetup | How the shop's first catalogue is going: { state, products? }, see §4.5 |
store.pluginConfig | The widget's settings: mode (off · preview · live), domains, desktop / mobile (the floating button, below), theme, accent, iconColor?, satelliteColor?, satelliteIconColor?, icon, productCircle, saveButton? (below), customCss? (the shop's own styles per part, §4.10.1), librarySelector? (the shop's own element that opens the list, §4.10), searchHeader and searchSelector? (opening the search from the header, and the shop's own element that opens it, §4.10), saveAnchors (below), hints (the widget's texts the shop changed, §4.10; a part left out says the widget's own), hintLanguages ({ languages, primary }: the languages the shop writes those texts in, its own first), searchProvider? / aiProvider?, productAnchor? / actionsAnchor?, brand? (all below). A field marked ? is absent when not set |
store.stats:
| Field | What it counts |
|---|---|
savedProducts | Products saved in the shop's lists, now |
widgetOpens | Times the widget was opened, ever |
historyProducts | Products in the customers' browsing history |
catalogueProducts | Active products of the catalogue Spaidoo holds |
productVisits | Visits Spaidoo sent to the shop's products in the last 30 days (widget, alerts, carousels, search, push) |
audience | { total, shopIdentified, spaidooAccount, anonymous }: the people with saved products, by how they are known |
alertsSent | Alerts (price drop, back in stock, reminders) sent to the shop's customers in the last 30 days |
alertClicks | Alerts the customer clicked (each alert counts once), last 30 days |
followers | Deprecated (always kept for old connectors). Do not show it |
scriptUrl is what the connector prints on the storefront (§7). It may change: always use the latest one.
store.pluginConfig.saveAnchors is where the merchant wants the save icon over the product photos, set in Spaidoo's admin. Only a connector that places the anchors itself over the photos (§7) needs it:
"saveAnchors": { "position": "top-right", "product": true, "list": true, "header": true, "listPhoto": ".card__media", "productPhoto": ".product__media" }position: the photo's corner,top-right·top-left·bottom-right·bottom-left.product/list: whether the icon shows on the product page and on product cards. The widget already draws nothing where it is off; a connector may also skip printing those anchors.header: whether the connector puts an icon in the shop's header, next to the cart, that opens the customer's list (spaidoo:show-sectionwith{ section: "library" }). It takes the look of the theme's own header icons; where it cannot find the cart, it puts none.listPhoto/productPhoto(optional): the CSS selector of the element holding the photo, for themes the connector cannot read. Absent: the connector finds the photo itself.productSize/listSize(optional): the button's diameter in px on the product page and on listings (28–80). Absent: the widget's own (34).productStrokeWidth/listStrokeWidth(optional): the symbol's stroke on the product page and on listings, in its 24-unit box (1–3, in steps of 0.25). Absent: the widget's own (2).
The icon's design (pluginConfig.saveButton, when the merchant has one of their own) and its size are applied by the widget too: the connector does not style the icon. A connector can change all of this from its own panel with POST /widget/save-buttons (§4.10).
The rest of store.pluginConfig:
| Field | What it is |
|---|---|
desktop / mobile | The floating button per device: { showButton, position, orientation, offsets?, chatAI, showSearchButton }. position: bottom-left · bottom-right · bottom-center (mobile only) · custom. With custom, offsets are its pixels from the screen's edges, only the sides set: { top | bottom, left | right } (a side missing: 20 px from the bottom / the right). chatAI / showSearchButton: the assistant's and the search's buttons. Changed with POST /widget/placement and POST /widget/search (§4.10) |
saveButton | The save button's own design, when the merchant set one: { idle?, saved? }, each { background?, icon?, fill? } as in POST /widget/save-buttons (§4.10). Absent: the floating button's colours |
searchProvider / aiProvider | The search and the assistant the widget uses now: { type, customSelector? }, type none · spaidoo (Spaidoo's own) · custom (the shop's own, opened by customSelector) · doofinder · kimera (third-party engines). Spaidoo's search is on every plan, with no quotas. Spaidoo offers no assistant of its own for now: aiProvider only carries a linked one. Absent: never set |
productAnchor / actionsAnchor | Spaidoo's own buttons placed in the shop's page by a selector (a save button next to the buy button; fixed icons for the list, the search and the assistant), set in Spaidoo's admin; present only when on. Informative: show that they are on and link to Spaidoo's admin to change them (POST /sso, widget-setup). Their shape may grow |
brand | Deprecated: old colour overrides the widget no longer uses. Ignore it |
connector is what Spaidoo holds from the last handshake (contractVersion, platform, platformName when declared, version, accepted capabilities, urls, storefront), or null before one. Never the secret.
4.3.1 GET /stats — the panel's figures by period
GET /stats?period=7d|30d|90d (default 30d) — what the shop got from the widget over the last 7, 30 or 90 days, compared with the period before, for the connector's home screen.
GET /stats?from=YYYY-MM-DD&to=YYYY-MM-DD — any range of UTC days, both included: today, yesterday, this month, last month, the last 12 months or whatever the merchant picks. It answers period: "custom" and compares it with as many days just before. from and to go together and win over period; to no later than today, at most 366 days. Otherwise, 400 STATS_RANGE_INVALID. Kept 5 minutes per range.
{
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"totals": {
"saves": 412,
"savers": 133,
"widgetOpens": 2210,
"productVisits": 318,
"alertsSent": 96,
"alertClicks": 21
},
"previous": {
"saves": 350,
"savers": 120,
"widgetOpens": 1980,
"productVisits": 270,
"alertsSent": 80,
"alertClicks": 15
},
"series": [
{
"date": "2026-09-04",
"saves": 12,
"productVisits": 9
},
{
"date": "2026-09-05",
"saves": 15,
"productVisits": 11
}
],
"topProducts": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"saves": 31
},
{
"productId": "111",
"product": null,
"saves": 24
}
],
"topViewed": [
{
"productId": "111",
"viewers": 58
},
{
"productId": "987",
"viewers": 41
}
],
"updatedAt": 1759500000
}| Field | |
|---|---|
period | 7d, 30d, 90d, or custom when asked by from/to |
from / to | The period, Unix seconds: whole UTC days (to is the end of the last day; for the fixed periods, today's). Days are UTC because Spaidoo keeps its daily counters that way |
totals | saves (products saved), savers (people who saved), widgetOpens, productVisits (visits Spaidoo sent to the shop's products), alertsSent, alertClicks (as in §4.3) |
previous | The same totals for the period just before, of the same length |
series | One row per day of the period, the days without activity included: { date: "YYYY-MM-DD", saves, productVisits } |
topProducts | The 5 products saved most in the period: { productId, product, saves }, the feed's product id. product: { name, image, url } from Spaidoo's catalogue, in the shop's own language (image may be null), the same card as GET /events (§4.18); null when the product is no longer in the catalogue |
topViewed | The 5 products viewed most in the period, from the history the widget keeps for each customer: { productId, product, viewers }, the people who viewed the product page (one per person, their last view in the period) |
updatedAt | When the figures were computed. They are kept 5 minutes: asking more often returns the same answer |
The same events as the reports in Spaidoo's admin: both show the same numbers. The full reports: POST /sso with intent: "reports" (§4.11).
4.3.2 GET /analytics — the analytics page
?period=7d|30d|90d (default 30d), or ?from=YYYY-MM-DD&to=YYYY-MM-DD as in /stats (§4.3.1). What the connector's analytics page needs besides /stats: the previous period day by day, the opportunities, who the shop can reach, how people come back and where they save from.
{
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"previousSeries": [
{
"date": "2026-08-05",
"saves": 9,
"productVisits": 7
},
{
"date": "2026-08-06",
"saves": 11,
"productVisits": 10
}
],
"topProducts": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"saves": 31
},
{
"productId": "111",
"product": null,
"saves": 24
}
],
"topViewed": [
{
"productId": "111",
"viewers": 58
},
{
"productId": "987",
"viewers": 41
}
],
"opportunities": {
"viewedNotSaved": {
"total": 2,
"products": [
{
"productId": "555",
"viewers": 40,
"savers": 3
},
{
"productId": "222",
"viewers": 17,
"savers": 1
}
]
},
"priceDropped": {
"people": 38,
"products": [
{
"productId": "987",
"savers": 21
},
{
"productId": "333",
"savers": 17
}
]
},
"dormant": {
"people": 54,
"days": 15
},
"savedNotClicked": {
"total": 12,
"products": [
{
"productId": "444",
"savers": 6
},
{
"productId": "111",
"savers": 4
}
]
},
"revisited": {
"people": 27,
"products": [
{
"productId": "987",
"people": 11
},
{
"productId": "111",
"people": 6
}
]
},
"removed": {
"total": 5,
"products": [
{
"productId": "222",
"removals": 9
},
{
"productId": "555",
"removals": 4
}
]
},
"topClients": {
"people": 12,
"minSaves": 3
},
"unavailable": {
"people": 7,
"soldOutPeople": 5,
"removedPeople": 2,
"products": [
{
"productId": "333",
"savers": 5,
"reason": "sold_out"
}
]
},
"sharedLists": {
"total": 4,
"products": [
{
"productId": "987",
"lists": 3
},
{
"productId": "111",
"lists": 1
}
]
}
},
"reach": {
"total": 312,
"shopCustomers": 120,
"spaidooAccounts": 45,
"anonymous": 160,
"email": 128,
"push": 64
},
"returning": {
"value": 97,
"previous": 81
},
"savedRevisits": {
"value": 64,
"previous": 52
},
"listAdds": {
"value": 143,
"previous": 120
},
"communication": {
"alerts": {
"sent": 340,
"seen": 281,
"clicked": 58,
"previousSent": 303,
"previousClicked": 44
},
"notifications": {
"sent": 4,
"seen": 3,
"clicked": 1
},
"recovered": 21,
"board": {
"impressions": 1240,
"clicks": 96
},
"carousels": {
"impressions": 8400,
"clicks": 310
}
},
"surfaces": [
{
"surface": "launcher",
"saves": 214
},
{
"surface": "product",
"saves": 158
},
{
"surface": "listing",
"saves": 40
},
{
"surface": "library",
"saves": 0
}
],
"updatedAt": 1759500000
}| Field | |
|---|---|
previousSeries | The previous period day by day, as /stats' series: to draw both periods on top of each other |
topProducts / topViewed | As in /stats, up to 10. Every entry with a productId, here and in opportunities.*.products, carries its product card too (§4.3.1) |
opportunities.viewedNotSaved | Products viewed by 3 people or more (the widget's history) and saved by at most 1 in 5 of them: { productId, viewers, savers }. total counts them all; the list, up to 10 |
opportunities.priceDropped | Saved products whose price dropped in the period, and people, who have them in their favourites |
opportunities.dormant | People with favourites and no activity in the shop for days days |
opportunities.savedNotClicked | Products saved in the period that nobody has opened again since: { productId, savers } |
opportunities.revisited | People who came back to look at a product they had saved (their history, over an hour after saving it) and, by product, how many: { people, products: [{ productId, people }] }. The closest to buying; the «visit without buying» alerts are for them |
opportunities.removed | The products most removed from favourites in the period: { total, products: [{ productId, removals }] } |
opportunities.topClients | Now, no period: how many people have minSaves products saved or more. Only the number, never who |
opportunities.unavailable | Now: saved products nobody can buy, sold out (no variant in stock, as the carousels judge it) or no longer offered (inactive in the shop's catalogue). people in all, soldOutPeople and removedPeople by why, and each product with its reason (sold_out · removed) |
opportunities.sharedLists | Now: products in shared lists (ListIx), by how many of them hold each: { total, products: [{ productId, lists }] } |
reach | Who the shop can reach now (no period): total, by identity (shopCustomers, spaidooAccounts, anonymous; a linked person counts in the first two), and how many have email (with consent) or push |
returning | People who came back to the shop with something saved before: { value, previous } |
savedRevisits | Saved products the person looked at again (the product page, more than an hour after saving it); each person and product counts once: { value, previous } |
listAdds | Products put into lists in the period, every list counts (the same product in 5 lists is 5), only those still there: { value, previous }. Unlike saves, which counts each product once per person |
communication | The shop's communication in the period, summed (run in Spaidoo's admin): alerts (automatic alerts: sent, seen, clicked, and the previous period's), notifications (notifications written by hand), recovered (alerted products the person came back to within 7 days), board (the board's impressions and clicks) and carousels (the carousels') |
surfaces | Saves of the period by where they were made: launcher (floating button), product (product page button), listing (button on a listing), library (inside the panel). Only saves since the widget sends it |
Opportunities lead to an action in Spaidoo (alert, remind): the connector opens it with POST /sso (§4.11). Worked out with the reports of Spaidoo's admin and kept 5 minutes, the three periods together.
4.3.3 GET /search-analytics — what the shop's customers search for
?period=7d|30d|90d (default 30d), or ?from=YYYY-MM-DD&to=YYYY-MM-DD as in /stats (§4.3.1). The searches customers make in the shop's Spaidoo search (§4.10 /widget/search) and the clicks on their results. Spaidoo adds them up every hour: the last hour may not be in yet.
By plan. Growth and Pro get the whole report (access: "full"). Starter gets a taste of it (access: "teaser"): always the last 7 days, whatever is asked; the number of searches, the 3 most searched and the first 3 without results (only the query, how often and how many results), how many more each list has (more) and report: null. The plan is read on every request: after an upgrade, the next answer is the whole report.
{
"access": "full",
"period": "30d",
"from": 1756944000,
"to": 1759536000,
"timezone": "UTC",
"searches": { "value": 1240, "previous": 1105 },
"topQueries": [
{ "q": "abrigo", "searches": 182, "results": 24, "clickedSearches": 121, "clicks": 160, "averagePosition": 1.8 },
{ "q": "botas mujer", "searches": 97, "results": 11, "clickedSearches": 15, "clicks": 17, "averagePosition": 4.6 }
],
"zeroResults": [
{ "q": "zapatillas niño", "searches": 23, "results": 0 },
{ "q": "chubasquero", "searches": 9, "results": 0 }
],
"more": { "topQueries": 412, "zeroResults": 37 },
"report": {
"totals": { "searches": 1240, "zeroResults": 96, "filtered": 210, "clickedSearches": 702, "clicks": 915, "views": 1018 },
"previous": { "searches": 1105, "zeroResults": 101, "filtered": 188, "clickedSearches": 610, "clicks": 790, "views": 930 },
"series": [
{ "date": "2026-09-04", "searches": 38, "zeroResults": 3, "clicks": 29 },
{ "date": "2026-09-05", "searches": 44, "zeroResults": 2, "clicks": 31 }
],
"noClick": [
{ "q": "botas mujer", "searches": 97, "results": 11, "clickedSearches": 15, "clicks": 17, "averagePosition": 4.6 }
],
"trending": [
{ "q": "lino", "searches": 41, "previous": 12 },
{ "q": "sandalias plataforma", "searches": 16, "previous": 0 }
],
"products": [
{
"productId": "987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"clicks": 88,
"averagePosition": 1.4
},
{ "productId": "111", "product": null, "clicks": 41, "averagePosition": 3.2 }
],
"positions": { "1": 402, "2": 188, "3": 97, "4": 61, "5": 40, "6": 31, "7": 22, "8": 18, "9": 14, "10": 11, "11+": 31 }
},
"updatedAt": 1759500000
}On Starter:
{
"access": "teaser",
"period": "7d",
"from": 1758931200,
"to": 1759536000,
"timezone": "UTC",
"searches": { "value": 286, "previous": null },
"topQueries": [
{ "q": "abrigo", "searches": 41, "results": 24 },
{ "q": "botas mujer", "searches": 22, "results": 11 },
{ "q": "bufanda", "searches": 17, "results": 6 }
],
"zeroResults": [
{ "q": "zapatillas niño", "searches": 6, "results": 0 },
{ "q": "chubasquero", "searches": 3, "results": 0 },
{ "q": "guantes tactiles", "searches": 2, "results": 0 }
],
"more": { "topQueries": 131, "zeroResults": 14 },
"report": null,
"updatedAt": 1759500000
}| Field | |
|---|---|
access | full (Growth, Pro) or teaser (Starter) |
period / from / to / timezone | As in /stats (§4.3.1). On Starter, always 7d |
searches | Searches of the period: { value, previous }, previous the period before (null on Starter). A search counts once per page view, even when a filter changes its results |
topQueries | The most searched: { q, searches, results, clickedSearches, clicks, averagePosition }, up to 20 (3 on Starter, only q, searches and results). averagePosition, where its results were clicked on average (1 = the first; null without clicks). q as searched, lower case with single spaces; results, what it found the last time |
zeroResults | Those that found nothing, by how often: { q, searches, results: 0 }, up to 20 (3 on Starter). What customers want and the shop does not have, or has under another name |
more | How many distinct queries each list leaves out: { topQueries, zeroResults } |
report.totals | searches, zeroResults, filtered (with a filter on), clickedSearches (with at least one click on a result), clicks, views (page views where somebody searched) |
report.previous | The same totals for the period just before, of the same length |
report.series | One row per day of the period, days without searches included: { date, searches, zeroResults, clicks } |
report.noClick | Searched twice or more, with results, and clicked in at most 1 in 5: { q, searches, results, clickedSearches, clicks, averagePosition }, up to 20. The results do not convince |
report.trending | Up to 10 queries, searched twice or more in the period, going up against the period before or new (previous: 0): { q, searches, previous }, the biggest rise first. Empty if nothing was searched in the period before |
report.products | The 10 products most clicked from the search: { productId, product, clicks, averagePosition }, with their product card (§4.3.1) and the average position they were clicked at (1 = the first) |
report.positions | Clicks by the position of the result clicked: "1" … "10" and "11+". Many clicks far below the first mean the order of the results can improve |
updatedAt | When it was worked out. Kept 5 minutes |
Anonymous: Spaidoo does not know who searched, only what and how often. Only searches from the shop's own pages count.
4.3.3.1 GET /search-analytics/find — one list with a text
Growth and Pro only: on Starter it answers 403 SEARCH_FILTER_REQUIRES_PLAN. ?list=topQueries|zeroResults|noClick|trending|products&contains=<text> (1 to 100 characters), plus the period as in /search-analytics. It returns only what in that list contains the text, regardless of case and accents: queries by their text and products by their name. The same limits and rows as the list in the report (20 queries, 10 in trending and products) and more, how many more match (0 in noClick and trending).
{ "list": "topQueries", "contains": "camis", "rows": [ { "q": "camisa", "searches": 12, "results": 3, "clickedSearches": 7, "clicks": 8, "averagePosition": 2.1 } ], "more": 0 }4.4 POST /uninstall — {} → 204
The connector is being removed, or the merchant disconnects Spaidoo from the connector's panel: both are the same call. Spaidoo stops reading the catalog the connector published (feeds added by hand in Spaidoo's admin stay), takes the products out of sale when that was the only catalog, switches the identity off and regenerates the loader. The API key keeps working: the data stays, and a new POST /handshake picks up where it was (a reconnection). The key does change when the shop changes hands: connected through another app (§3), or taken by another account that proved its domain. Then the old key gets 401 and the connector pairs again.
4.5 Catalog — catalog.feed (required)
PUT /catalog/feeds
{ "feeds": [ { "language": "es", "url": "https://shop.example.com/spaidoo/feed?lang=es" } ] }The complete list: a language missing from it is removed. Up to 50 feeds, each url http(s) up to 1000 characters. Spaidoo reads every feed about once a day.
While the connector is connected, the catalogue is the connector's: Spaidoo's admin shows the feeds read-only, and changing or uploading a feed there answers 409 FEEDS_MANAGED_BY_CONNECTOR (asking to read them again still works). After POST /uninstall (§4.4) the merchant manages the feeds again.
POST /catalog/feeds/read → 202 { "queued": true } — "read now" (e.g. a button in the panel). 429 { "queued": false, "retryInSeconds": n } with Retry-After if asked again too soon (3 minutes).
The feed is a Google Merchant product feed (RSS 2.0 or Atom, g: namespace optional) with one <item>/<entry> per variant:
| Field | Required | Notes |
|---|---|---|
g:id | ✅ | Variant id |
g:item_group_id | if variants | The product id for Spaidoo (one row per product). Without it, g:id is the product id |
g:title, g:link | ✅ | Localized; link is the canonical product URL |
g:price | ✅ | "19.90 EUR": the shop's base currency |
g:sale_price | Same currency as g:price | |
g:availability | ✅ | in_stock · out_of_stock · preorder · backorder |
g:image_link, g:additional_image_link | ||
g:description, g:brand, g:product_type (A > B > C), g:color, g:size, g:mpn | ||
spaidoo:price currency="USD" | Namespace https://spaidoo.com/ns/feed/1. Exact price in every other currency the shop sells in (repeatable) | |
spaidoo:sale_price currency="USD" |
The product id is the one used everywhere else in this contract (data-sp-id, catalog.changes, wishlist import).
While a large feed is being generated, answer 202 (or 503/429) with Retry-After: <seconds>: Spaidoo comes back then and does not treat it as an empty catalog. Any other error keeps the previous catalog.
The first catalogue. A shop with no products that publishes its feeds shows no widget until Spaidoo has read its catalogue: without it, a customer could not save anything. Neither the mode (§4.10) nor the connector switching the widget on in the shop changes this. store.catalogSetup (§4.3) says how it is going, for the panel to show:
state | Meaning | Widget shown? |
|---|---|---|
reading | Spaidoo is waiting to read the feed | No |
importing | The products are coming in | No |
failed | No feed could be read, not even after three retries in about 15 minutes (meanwhile it stays reading or importing). Offer to try again: POST /catalog/feeds/read | No |
search | The catalogue is in (products, how many); search is being prepared | Yes, without search |
empty | The shop has no products yet | Yes, without search |
ready | Done. Also the value for any shop that already had a catalogue | Yes |
With the first search pack, Spaidoo's search goes on by itself, unless the shop chose otherwise first, switching it off included. Until then, switching it on does not show the button: it appears once the pack is ready. The daily reads do not close the widget again.
4.5.1 GET /catalog/products — the shop's products, as Spaidoo holds them
The shop's catalogue as Spaidoo read it from the feeds: a product picker for the connector's panel (alerts, carousels) and the names and photos of the products it already chose, without asking its platform. Only the products of the API key's shop, and only those still in its feed. No capability.
GET /catalog/products?q=camisa— titles that containq(2 to 100 characters), in any of the feed's languages, ignoring case and accents (pantalonfinds «Pantalón»).GET /catalog/products?ids=987,111— the products of those ids, up to 100, comma-separated, in the order asked. An id the catalogue does not have (unknown, or no longer in the feed) is left out: show it as removed.GET /catalog/products— the whole catalogue, page by page.
limit (1 to 50, default 20) and cursor page the search and the whole catalogue; ids answers all of them at once and goes alone. language (es, pt-BR…, read by its two letters): the titles and links in that language when the feed has it, else in the shop's own.
{
"products": [
{
"id": "111",
"title": "Camisa de lino blanca",
"image": "https://cdn.shop.example.com/products/111.jpg",
"url": "https://shop.example.com/products/camisa-de-lino-blanca",
"price": "59.00",
"salePrice": "44.90",
"currency": "EUR",
"available": true
}
],
"nextCursor": "OTg3"
}| Field | What it is |
|---|---|
id | The product id of the feed (g:item_group_id, else g:id, §4.5): the same id of productIds in §4.14 and §4.17 and of the imports (§4.8) |
title, url | From the feed, in language (or the shop's own) |
image | g:image_link; null when the feed has none |
price, salePrice, currency | Money as in §2, in the shop's base currency (g:price). salePrice only while it is below price. price and currency are null when the feed gives none |
available | false when every variant the feed reports is out_of_stock; a product without stock data is available |
nextCursor | Only when there are more: send it back as cursor, with the same q, for the next page. Opaque |
The products come in a stable order (by id), not by relevance. What the feed says is what Spaidoo answers: a change in the shop shows here after the next read (§4.5) or its catalog.changes (§4.6).
400 BAD_REQUEST: ids with q or cursor, more than 100 ids, q under 2 characters, limit outside 1–50, or a cursor this route did not give.
4.6 Catalog changes — catalog.changes
When a product changes in the shop, the connector tells Spaidoo right away. Price-drop alerts leave within minutes instead of on the next daily read. The daily feed read stays as the reconciliation.
POST /catalog/changes
{
"changes": [
{
"type": "product.updated",
"id": "123",
"at": 1759219200,
"price": { "amount": "24.90", "currency": "EUR" },
"salePrice": { "amount": "19.90", "currency": "EUR" },
"prices": [ { "currency": "USD", "price": "27.90", "salePrice": "21.90" } ],
"availability": "in_stock",
"variants": [
{ "sku": "123-1", "price": "24.90", "salePrice": "19.90", "availability": "in_stock" },
{ "sku": "123-2", "price": "24.90", "salePrice": null, "availability": "out_of_stock" }
]
},
{ "type": "product.deleted", "id": "456", "at": 1759219230 }
]
}idis the product id of the feed (item_group_id, oridwithout variants).product.updatedcarries only what can change without touching the catalog structure:price,salePrice(null= no sale),prices,availability,variants. Every field is optional; a present field replaces the stored value.variants: for a product with variants, the variants that changed, bysku(theg:idof the feed), with amounts in the currency ofprice. Price drops are measured on the cheapest variant, as with the feed. Variants not sent keep their values.product.deleted: the product is no longer sold (deleted or disabled).atis when the change happened in the shop. Spaidoo ignores a change older than the one it already applied for that product, so retries and out-of-order delivery are safe.- Amounts are decimal strings with at most 4 decimals (
"24.90").priceandsalePricemust be in the same currency; the variants' amounts are in that currency too. Changes in a currency other than a language's base currency leave that language's prices alone. availability:in_stock·out_of_stock·preorder·backorder.atin the future is taken as now.400 CATALOG_CHANGE_CURRENCY_MISMATCHwithid(the first change whosepriceandsalePriceare in different currencies): nothing of the request is applied.- Up to 100 changes per request and 60 requests a minute per shop (
429 CATALOG_CHANGES_RATE_LIMIT+Retry-After). The connector SHOULD coalesce bursts (a bulk price edit of 2 000 products is 20 requests, not 2 000). 409 CONNECTOR_CAPABILITY_MISSINGif the handshake did not declarecatalog.changes.- For 24 hours after a change, the feed does not overwrite that product's prices and stock (a feed built before the change would undo it); it still updates the rest.
- New products, and changes to title, link, images or categories, arrive with the next feed read. A connector may call
POST /catalog/feeds/readafter a bulk import.
Response 202 (changes are applied asynchronously, within seconds):
{ "accepted": 1, "unknown": ["456"] }unknown lists ids Spaidoo does not have yet; it schedules a feed read. Delivery is best effort: on failure, retry with backoff for up to 1 hour, then drop — the daily feed read corrects everything.
4.7 POST /customers/erase — erase a customer (customerErase)
{ "customerId": "123" } → 204. Any connector may call it, with or without customerErase declared: an erasure is always accepted (the capability only tells Spaidoo the connector sends them, §8). The shop deleted this customer (or received a GDPR erasure request). Spaidoo deletes the customer's list anchored to this shop and unlinks any Spaidoo account from it. Guests (customers without an account) need not be sent.
4.7.1 POST /customers/export — what Spaidoo holds of a customer
{ "customerId": "123" } → 200. A customer asked the shop for their data (a GDPR access request, a platform's customers/data_request): Spaidoo answers everything it holds of them for this shop, and the connector hands it to the merchant (who answers the customer). No capability needed, like §4.7: it always works.
{
"customerId": "123",
"known": true,
"since": 1756684800,
"spaidooAccountLinked": false,
"favorites": [
{
"name": "Blue shirt",
"url": "https://shop.example.com/products/blue-shirt",
"savedAt": 1757000000
}
],
"lists": [
{
"name": "Birthday",
"products": [
{
"name": "Red scarf",
"url": "https://shop.example.com/products/red-scarf",
"savedAt": 1757100000
}
]
}
],
"emailConsents": [
{
"email": "ana@example.com",
"source": "widget",
"consentedAt": 1757200000,
"textVersion": "2026-09-10"
}
],
"pushDevices": 1
}known: false(and empty lists): Spaidoo holds nothing of this customer.favorites: products saved on their own;lists: their lists, with only this shop's products. Each product{ name, url, savedAt }.spaidooAccountLinked: the customer also linked a Spaidoo account to the shop one (§5). Only what that account keeps of this shop comes along; the rest of it is the customer's relationship with Spaidoo, which they ask Spaidoo for.emailConsents: the emails given to the shop in the widget, for its alerts (source: "widget"), or the email of the linked Spaidoo account authorised for it (spaidoo_account), with when and which text. Spaidoo does not keep the shop's own customer emails (§6.2).pushDevices: browsers subscribed to the shop's push notifications.
4.7.2 GET /shop-data and GET /shop-data/export — the shop's customers and contacts
For the merchant to take their data away from the connector's panel, as from Spaidoo's admin. No capability needed.
GET /shop-data → 200: how many there are, without asking the shop for anything.
{ "customers": 120, "contacts": 37, "contactsLocked": false, "leavingUntil": null }customers: the shop's identified customers (their list is anchored to the shop, §5) who saved at least one product, also those who linked a Spaidoo account. A customer who saved nothing is left out: their email and consent are already the shop's.contacts: people who are not customers of the shop and agreed to its emails in the widget: an email typed by an anonymous visitor, or the email of a Spaidoo account. They are the contacts Spaidoo brought to the shop.contactsLocked: alwaysfalse, every plan takes its contacts. It stays for compatibility.leavingUntil: the shop left (POST /uninstall, §4.4). Until that date — 90 days from the connector's last contact — it takes everything, customers by id without email (Spaidoo can no longer ask the shop); then Spaidoo erases its contacts.nullotherwise. A platform that erases the shop's data sooner (POST /shop-redact, §3.5) shortens it.
GET /shop-data/export?format=json|csv → 200, the file itself (Content-Disposition: attachment), the same one Spaidoo's admin gives. Without format, JSON:
{
"shop": { "id": "shop_123", "name": "Mi tienda" },
"exportedAt": "2026-10-08T09:00:00.000Z",
"customers": [
{
"customerId": "123",
"email": "ana@example.com",
"spaidooAccountLinked": false,
"since": "2026-09-01T00:00:00.000Z",
"favorites": [{ "productId": "8812345600001", "name": "Blue shirt", "url": "https://shop.example.com/products/blue-shirt", "savedAt": "2026-09-04T15:33:20.000Z" }],
"lists": []
}
],
"contacts": [
{
"email": "marta@example.com",
"source": "widget",
"consentedAt": "2026-09-20T10:00:00.000Z",
"consentTextVersion": "shop-mail-save-v1",
"favorites": [],
"lists": []
}
],
"contactsLocked": false
}- A file for a person: dates are ISO 8601, not Unix seconds.
productIdis the shop's own id (the feed's);nullfor a product added to a list by hand. - CSV: one row per saved product, as other wishlist apps export:
type(customer|contact),customer_id,email,source(shop_customer,shop_customer_linked,widget,spaidoo_account),consented_at,product_id,product_title,product_url,list_name(empty: saved on its own, not in a list),added_at. A contact who saved nothing has one row with the product's columns empty; a customer who saved nothing is not in the file. The names are the ones Spaidoo's import reads. customers[].emailis asked from the shop at that moment (§6.2): Spaidoo does not keep it. If the shop does not answer,503 SHOP_EMAILS_UNAVAILABLEand no file: one without emails would look complete and is not.- Only those who authorised the shop come: a Spaidoo account without that consent never does. A contact typed in the widget comes with their favourites of the shop; the email of a Spaidoo account comes alone (they authorised the email, not their library).
4.8 POST /wishlists/import — wishlistImport
{
"customers": [
{ "customerId": "123", "lists": [
{ "id": "1", "name": "My wishlist", "isDefault": true, "products": ["123", "789"] }
] }
]
}Up to 50 customers per call, 100 lists per customer, 1 000 products per list. Products are product ids of the feed. Idempotent: importing the same list twice does not duplicate it.
4.8.1 POST /wishlists/import/rows — wishlistImport, row by row
The same import, for a connector that has the lists as rows (one saved product per row) and does not want to group them: a file exported from another wishlist app that the connector has read, for instance. Spaidoo resolves the products and groups the lists. Spaidoo never receives an email here: when the old app names the customer by email, the connector turns it into its own customer id first (with the platform's customer API) and leaves out the rows it cannot match.
{
"dryRun": true,
"rows": [
{ "customerId": "123", "productId": "987", "list": "Birthday", "addedAt": 1756684800 },
{ "customerId": "123", "variantId": "987-2" },
{ "customerId": "124", "handle": "blue-shirt" }
]
}- Up to 2 000 rows per call. Send all the rows of one customer in the same call (the counts of a call then describe whole customers).
customerId: the shop's customer id, as in §5 (a platform global id such asgid://…/Customer/123is read as123). Guests have no id: leave their rows out.- The product:
productId(the feed's product id), orvariantId(a variant'sg:id), orhandle(the last segment of the product's URL, or the whole URL). At least one; Spaidoo tries them in that order. list: the list's name in the old app. Absent or empty = the customer's main list, which goes to the library (likeisDefaultin §4.8). A customer with a single list gets it as their main list, whatever it is called.addedAt(optional): when the customer saved it, Unix seconds. Informative.dryRun: truechanges nothing and answers what would happen (the preview the connector shows before importing). Then the same rows withdryRun: false.- Idempotent like §4.8: running it again only brings what is new.
Response 200:
{
"dryRun": true,
"counts": { "rows": 3, "accepted": 2, "rejected": 1, "duplicates": 0, "customers": 1, "lists": 2, "products": 2 },
"rejected": [ { "row": 2, "reason": "PRODUCT_NOT_FOUND" } ]
}counts.rows=accepted+rejected+duplicates.duplicates: rows repeating a customer, list and product already in the call.customers,listsandproductsdescribe what is (or would be) imported: products counted once per customer and list.rejected: every rejected row, by its position inrows(from 0), with itsreason:PRODUCT_NOT_FOUND(not in the catalogue Spaidoo holds),PRODUCT_MISSING(noproductId,variantIdnorhandle),CUSTOMER_INVALID(an empty or malformed id),LIMIT_EXCEEDED(over 100 lists for the customer or 1 000 products in a list). New reasons may appear: show an unknown one as «not imported».- With
dryRun: falsethe response also carriesresult, the same object as §4.8 answers:{ customers, listsCreated, productsAdded, alreadyImported, notInCatalogue, overLimit, listsRemovedInSpaidoo, customersSkipped }.
Errors (also for §4.8), in this order: 409 TERMS_NOT_ACCEPTED (§4.13), 409 CONNECTOR_CAPABILITY_MISSING with capability: "wishlistImport" (not accepted at handshake), 409 WISHLIST_IMPORT_IDENTITY_OFF (the capability was accepted but the identity is not working now: nobody could open the lists), 409 WISHLIST_IMPORT_NO_CATALOGUE (Spaidoo has no catalogue of the shop yet).
4.8.2 POST /wishlists/import/file — wishlistImport, from a file the merchant uploads
The import of a file exported from another wishlist app, for a connector that does not want to resolve the customers itself: it reads the file into rows and Spaidoo does the rest. Unlike §4.8.1, the customer may be named by email: Spaidoo asks the shop who that is with customerLookup (§6.3), and confirms a customer id with customers (§6.2). Spaidoo uses the emails for that question and forgets them: it never stores them.
{
"dryRun": true,
"rows": [
{ "customer": "ana@example.com", "productId": "987", "list": "Birthday" },
{ "customer": "ana@example.com", "variantId": "987-2" },
{ "customer": "124", "handle": "blue-shirt" },
{ "customer": "Guest", "productId": "555" }
]
}- Up to 2 000 rows per call (at least 1). Send all the rows of one customer in the same call.
customer(up to 254): an email, or the shop's customer id (a platform global id such asgid://…/Customer/123is read as123). Empty orGuest: a guest, counted and left out.- Only customers the shop confirms are imported: an email the lookup does not find, or an id the customers route does not return, is left out (
customersNotFound). - The product:
productId(the feed's product id, up to 200),variantId(a variant'sg:id, up to 200) orhandle(the last segment of the product's URL, or the whole URL, up to 1000), tried in that order.list(up to 250): as in §4.8.1; no name, or a customer's only list, goes to the library. dryRun: truechanges nothing and answers the preview; then the same rows withdryRun: false. Idempotent like §4.8.
Response 200:
{
"preview": { "rows": 4, "guests": 1, "customers": 2, "customersNotFound": 0, "customersUnconfirmable": 0, "lists": 3, "productsNotFound": 0, "products": 3 },
"result": { "customers": 2, "listsCreated": 3, "productsAdded": 3, "alreadyImported": 0, "notInCatalogue": 0, "overLimit": 0, "listsRemovedInSpaidoo": 0, "customersSkipped": 0 }
}preview:rows;guests(rows of a guest);customers(the shop confirmed them);customersNotFound(distinct emails or ids the shop does not have);customersUnconfirmable(distinct emails or ids the shop cannot be asked about);lists;productsNotFound(rows of a confirmed customer whose product is not in the catalogue);products(what is brought, once per customer and list).result, only withdryRun: false: the same object as §4.8.1.
Errors, in this order:
409 TERMS_NOT_ACCEPTED(§4.13).409 CONNECTOR_CAPABILITY_MISSINGwithcapability:wishlistImportnot accepted; or the file names customers by email andcustomerLookupwas not accepted; or it names them by id andcustomerswas not.409 WISHLIST_IMPORT_IDENTITY_OFF: the identity is not working now.409 WISHLIST_IMPORT_NO_CATALOGUE: Spaidoo has no catalogue of the shop yet.503 SHOP_EMAILS_UNAVAILABLE: the shop did not answer the lookup or the customers route; nothing was imported, try later.
4.9 Domain verification — domainVerification
POST /domain-verification→{ "verified": false, "verificationCode": "spaidoo-verify-…", "domain": "shop.example.com" }. The connector stores the code and serves it aturls.verifyastext/plain, nothing else in the body.urls.verifymust be on the domain being proven (or itswww.) and must not contain the code. Spaidoo does not follow redirects.POST /domain-verification/check→{ "verified": true }. Spaidoo fetchedurls.verifyand found the code.- A shop whose domain is already proven answers
{ "verified": true }to both. - The domain is always the shop's own (the one of its page in Spaidoo). A different
storeUrldeclared at handshake is not what gets proven: proving a domain of the connector's never verifies a shop on another one. 400 DOMAIN_NOT_VERIFIABLE: Spaidoo has no domain to prove for the shop or no account owns it yet.429 CLAIM_RATE_LIMIT_EXCEEDED: too many codes asked for; try later.- Without the capability, the merchant can still verify by uploading the code as
https://<domain>/spaidoo-verify.txt.
4.10 Widget settings from the connector's panel (optional)
A connector may let the merchant change a few widget settings without leaving the back-office. These are the only writes a connector can make to the widget:
| Call | Body |
|---|---|
POST /widget/state | { "mode": "off" | "preview" | "live" } — 403 SHOP_NOT_VERIFIED for live on an unverified domain |
POST /widget/placement | { "desktop"?: {…}, "mobile"?: {…} } each { position?: "bottom-left"|"bottom-right"|"bottom-center"|"custom", offsets?: { top?|bottom?, left?|right? }, orientation?: "vertical"|"horizontal", showButton?: bool }. custom places the button by pixels from the screen's edges (offsets, integers 0–2000; one of top/bottom and one of left/right; a side not given: 20 px from the bottom / the right); a side sent replaces its opposite. offsets without custom, or both sides of a pair: 400 INVALID_PLACEMENT. A corner replaces a custom placement · bottom-center only on mobile (400 PLACEMENT_NOT_AVAILABLE on desktop) |
POST /widget/appearance | { theme?: "light"|"dark", accent?, iconColor?|null, icon?: "bookmark"|"heart", productCircle?, satelliteColor?|null, satelliteIconColor?|null } (colors #rrggbb; null = back to the automatic color) |
POST /widget/save-buttons | The save button over the photos (§7): { position?: "top-right"|"top-left"|"bottom-right"|"bottom-left", product?: bool, list?: bool, header?: bool, productSize?, listSize?, productStrokeWidth?, listStrokeWidth?, design?: { idle?, saved? }|null }. Sizes in px, 28–80; strokes 1–3, in steps of 0.25. Each state of the design: { background?: "#rrggbb"|"transparent", icon?: "#rrggbb", fill?: "outline"|"filled" }; an object replaces the whole design and null goes back to the floating button's colours |
POST /widget/library-selector | The shop's own element that opens the customer's list (its own header icon…): { selector: "…" }, a CSS selector (max 200), on desktop and mobile at once; "" removes it. Besides, any link to #spaidoo-list opens the list with nothing to set up (e.g. an item of the shop's menu) |
POST /widget/custom-css | The shop's own styles, per part: { styles: { save?, saveSaved?, saveIcon?, header?, headerAction?, headerIcon?, launcher?, launcherList?, launcherIcon?, launcherProduct? } }, each only declarations (property: value;, max 1000, no { }, @, < or url()), always the whole set; {} removes them. See §4.10.1 |
POST /widget/search | { search?: bool, showSearchButton?: bool, chatAI?: bool, header?: bool, selector?: "…" }. header: the search opens from the shop's header (§7 SpaidooConfig.searchHeader); selector: the shop's own element that opens it, a CSS selector (max. 200), on desktop and mobile alike, and "" removes it. Any link to #spaidoo-search also opens the search. search turns Spaidoo's search on or off, on every plan and with no other step, and showSearchButton is then only its button on the floating launcher. Sent without search, showSearchButton does both, as before. With another search linked, that one stays and only its button shows or hides. 409 SURFACE_NOT_AVAILABLE if chatAI: true is asked with no assistant linked |
POST /widget/hints | The widget's texts: what each button says on hover and what screen readers read, on desktop and mobile at once. { libraryHint?, addProductHint?, savedProductHint?, searchHint?, chatAIHint? } (savedProductHint: the save button's once the product is already in the list), each false (no text), { "es": "…", "en": "…" } (the shop's own, per 2-letter language, max 100; that part's whole set) or {} (back to the widget's own). A language left out, or empty, uses the widget's text in that language |
- Every call answers
200 { "success": true }(/widget/statealso returnsmode). At least one field;400 NOTHING_TO_CHANGEotherwise. themeis the base of the widget's look:lightordark. The widget derives the rest of the palette fromthemeandaccent.- The button above the phone's own bar (a fixed buy bar, a chat), placed by pixels:
{ "mobile": { "position": "custom", "offsets": { "bottom": 96, "right": 16 } } }./statusthen returnsposition: "custom"with thoseoffsets(§4.3). - Terms first: while the shop has not accepted the version of Spaidoo's terms in force (
store.termsAccepted: falsein §4.3), every write of this section answers409 TERMS_NOT_ACCEPTED. Show the acceptance (§4.13) and try again. Reads (/status) always work.
4.10.1 Custom CSS
The shop writes no selectors: it writes declarations (property: value;) for each part of what it sets up here, and the shop's loader wraps them in Spaidoo's selectors and puts them in the page. They never reach the list's panel.
| Part | Selector |
|---|---|
save · save button | [data-spaidoo-save]::part(button) |
saveSaved · save button, saved | [data-spaidoo-save]::part(saved) |
saveIcon · the save button's symbol | [data-spaidoo-save]::part(icon) |
header · header icon | [data-spaidoo-header] |
headerAction · the header icon's button (the widget's, fixed icons) | [data-spaidoo-header]::part(action) |
headerIcon · that icon's drawing: width, height, stroke-width (in a 24-unit box) | [data-spaidoo-header]::part(icon) |
launcher · floating button (whole) | #spaidoo-widget-root::part(launcher) |
launcherList · the list's button | #spaidoo-widget-root::part(launcher-list) |
launcherIcon · the list button's icon | #spaidoo-widget-root::part(launcher-icon) |
launcherProduct · the product's circle | #spaidoo-widget-root::part(launcher-product) |
On the save button its variables work too: --sp-save-size, --sp-save-radius, --sp-save-background, --sp-save-color, --sp-save-fill, --sp-save-shadow…
{ "styles": { "save": "border-radius: 8px; box-shadow: none;", "launcher": "bottom: 96px;" } }4.10.2 The widget's preview (optional)
A connector's panel can show the widget as the merchant sets it up, without a shop page: an iframe of Spaidoo's preview page, driven with postMessage. Nothing in it is real: it calls nothing of Spaidoo and counts nothing, and a click only tells the panel what was clicked.
<iframe src="https://widget.spaidoo.com/preview/v1/index.html?origin=https%3A%2F%2Fpanel.platform.example"
sandbox="allow-scripts allow-same-origin" width="360" height="640"></iframe>origin(required): your panel's origin. The preview only takes messages from that origin and from its parent window, and only posts to it.- Every message, both ways:
{ "ns": "spaidoo-preview", "v": 1, "type": "…", …fields }. Ignore any othernsorv, and check thatevent.originishttps://widget.spaidoo.comandevent.sourcethe iframe's window. A change that breaks this goes to/preview/v2/.
type | Direction | Fields | When |
|---|---|---|---|
ready | preview → panel | sizes: { mobile: [360, 640], desktop: [1024, 640] } | Once, when it can draw. Without it in a few seconds, show the preview as unavailable |
render | panel → preview | rev (a number that goes up with each one), config (below) | After ready and after every change, at most one per frame. Only the latest is drawn |
rendered | preview → panel | rev | That render is on screen: show the iframe (keep it hidden until the first) |
error | preview → panel | rev, code: BAD_CONFIG (with field) or RENDER_FAILED | The last good render stays |
focus | preview → panel | target: launcher · save · panel · header | The merchant clicked that part: take them to its setting |
config, one flat object with the same values as /status (§4.3) and the writes of §4.10:
| Key | What it is |
|---|---|
device | mobile or desktop (required) |
theme, accent, icon, productCircle | Required, as in POST /widget/appearance. iconColor, satelliteColor, satelliteIconColor: optional, #rrggbb or null |
placement | Required: { position, orientation, showButton, top?, right?, bottom?, left? } for that device; a custom position's pixels go here, not in offsets |
lang | The language the widget speaks |
page | product (default) or collection: the kind of page drawn behind |
panel | closed (default) or open: the list's panel open |
saveAnchors, saveButton, header | The save buttons over the photos and their design, as in POST /widget/save-buttons; header: the header icon |
hints, tip | The widget's texts, as in POST /widget/hints; tip: one of their keys, shown as if hovered |
search, chatAI | The search's and the assistant's buttons |
customCss | The shop's own styles per part (§4.10.1) |
stage | { width }, 240–1024: the width the panel shows; the preview draws a stage that wide, on the button's side |
products | Up to 8 of the shop's products, { name, image (https), price? }, instead of drawn placeholders |
The iframe never reports a height: give it a fixed size and crop it (stage). Its background is its own (a light page).
4.11 POST /sso — open Spaidoo's admin already signed in
{ "intent": "panel" } → { "url": "…" } (single use, 5 minutes). Intents: panel, widget-setup, spaidoo-search, providers, email, posts, carousels, push, automations, reports (the full reports), billing (plans and invoices in Spaidoo; for a shop billed by its platform, Spaidoo's admin sends the merchant on to urls.billing).
- An unknown intent falls back to
panel(200, never400): a connector published in a marketplace keeps working when Spaidoo renames or retires a page. Anintentmust still be a short name (^[a-z0-9-]{1,40}$). - Ask for the URL when the merchant clicks, and open it in a new tab: a URL created in advance may expire before it is used.
- The URL opens Spaidoo's «continue as
» page: the merchant clicks once more to sign in. Opening the link alone signs nobody in, so a link sent to someone else never puts them to work in your shop.
4.12 Plan billed by the platform — billing.platform
Some platforms bill their apps themselves (an app marketplace with its own billing), and their rules forbid charging the merchant anywhere else. With billing.platform the platform charges the shop's Spaidoo plan and the connector tells Spaidoo which plan the shop has. Spaidoo then takes that as the truth for the shop's plan, offers no checkout of its own and sends the merchant to urls.billing to change it.
The connector maps its platform's plans to Spaidoo's: starter · growth · pro. Spaidoo knows nothing of the platform's plan names.
PUT /billing — the shop's plan as the platform has it now. Idempotent: send the whole state every time.
{
"plan": "growth",
"interval": "monthly",
"status": "trialing",
"externalId": "sub_8f2a…",
"currentPeriodEnd": 1761955200,
"trialEndsAt": 1760572800,
"cancelAtPeriodEnd": false,
"pending": null,
"price": { "amount": "29.00", "currency": "USD" },
"test": false,
"occurredAt": 1759363200
}| Field | |
|---|---|
plan | starter · growth · pro. Anything else: 400 BILLING_PLAN_UNKNOWN |
interval | monthly · annual. Absent (or null) for a plan without a price |
status | active · trialing · frozen (the platform suspended the charges: an unpaid platform bill) · cancelled |
externalId | The platform's id of the subscription, or null. Kept for support and reconciliation |
currentPeriodEnd | When the period paid for ends (Unix seconds), or null. In a trial without a billing cycle yet, the trial's end: with null, Spaidoo takes trialEndsAt |
trialEndsAt | When the free trial ends, or null |
cancelAtPeriodEnd | The merchant cancelled: the plan lasts until currentPeriodEnd. Default false |
pending | A change that takes effect later (a downgrade at the end of the period): { plan, interval?, effectiveAt }, or null |
price | What the platform charges, { amount, currency } (§2), or null. Informative: Spaidoo never computes with it |
test | A test charge (a development shop): the plan is given, it does not count as revenue. Default false |
occurredAt | When the platform's state was true (the time of its event, or when the connector read it), Unix seconds |
Response 200: the same object as GET /billing.
What Spaidoo does with it:
| Report | Effect |
|---|---|
active / trialing | The shop has plan from now on |
pending | Nothing changes until effectiveAt; report again then |
cancelAtPeriodEnd: true | The plan lasts until currentPeriodEnd |
frozen | The shop uses starter (communication stops, nothing is deleted); a later active gives the plan back |
cancelled | The shop goes to starter |
- Order: reports may arrive out of order (a redirect and a reconciliation at once). Spaidoo applies the one with the newest
occurredAt. A report with exactly theoccurredAtalready applied is a retry: accepted,200. One strictly older answers409 BILLING_STALE, with thelastEventAtapplied. On409 BILLING_STALE, read the platform again and send the current state. - Report after every change of the platform's subscription, and at least once per billing period (a daily reconciliation is recommended). If
currentPeriodEndpasses by 2 days without a report, Spaidoo's staff are warned; after 7 days the shop moves tostarteruntil the next report. Spaidoo never lowers a plan because a call failed: only on a reported status or after those 7 days. 409 CONNECTOR_CAPABILITY_MISSINGifbilling.platformwas not accepted at handshake (§4.1).409 BILLING_STRIPE_ACTIVEwhile the shop still pays Spaidoo directly (a plan bought in Spaidoo's admin): nothing changes. The merchant cancels it in Spaidoo first; then report again. No shop is billed twice.- A connector that reported
cancelledand is then uninstalled (POST /uninstall, §4.4) gives the billing back to Spaidoo: the shop can buy a plan in Spaidoo's admin again. - While the shop's plan is billed by the platform, Spaidoo's own checkout (plan changes, payment method, cancellation in Spaidoo's admin) answers
409 BILLING_MANAGED_BY_PLATFORM.
GET /billing — what Spaidoo holds, for the connector's plans screen and for reconciliation. Works with or without the capability.
{
"provider": "platform",
"plan": "growth",
"interval": "monthly",
"status": "trialing",
"currentPeriodEnd": 1761955200,
"trialEndsAt": 1760572800,
"cancelAtPeriodEnd": false,
"pending": null,
"price": { "amount": "29.00", "currency": "USD" },
"test": false,
"externalId": "sub_8f2a…",
"lastEventAt": 1759363200,
"lastReportAt": 1759363260,
"manageUrl": "https://admin.platform.example/store/my-shop/apps/spaidoo/plans"
}provider: who bills the plan.platform(this capability),stripe(Spaidoo bills it) orinternal(granted by Spaidoo, nothing is billed).- With
providerother thanplatform:externalId,price,lastEventAtandlastReportAtarenull, andmanageUrlis the page of Spaidoo's admin (ornullforinternal).statususes the vocabulary above. lastEventAt: theoccurredAtof the report applied;lastReportAt: when the last report arrived.
4.12.1 GET /plans — Spaidoo's plans, for the connector's plans screen
What each plan includes, from the same table Spaidoo enforces, so a connector draws its plans screen without copying it. Keys and ids only: the labels are the connector's, in its own languages. No capability.
{
"current": "growth",
"billing": "stripe",
"plans": [
{
"id": "growth",
"price": { "currency": "EUR", "monthlyCents": 2900, "annualCents": 27600, "taxIncluded": false },
"features": {
"postsPerMonth": 10, "postsGapDays": 1, "notificationsPerMonth": 4, "notificationsGapDays": 1,
"boardCards": 3, "dashboards": null, "carousels": false, "contactsExport": true, "customSlug": true, "peopleLists": true
},
"automations": ["first_product_saved", "product_saved", "products_threshold", "product_removed"],
"integrations": ["webhook", "klaviyo", "mailchimp", "ga4"],
"reports": ["widget_usage", "library_usage", "top_saved_products"]
}
]
}| Field | What it is |
|---|---|
current | The plan the shop uses now: starter · growth · pro (a trial or a grant from Spaidoo can put it above the billed one) |
billing | Who bills it: stripe (Spaidoo) or platform (§4.12) |
plans | Every plan, lowest first |
price | Spaidoo's prices in cents, before tax (taxIncluded: false), per month and per year. null when the platform bills: it charges its own prices |
features | postsPerMonth, notificationsPerMonth, boardCards, dashboards: how many, null = no limit, 0 = not included. postsGapDays, notificationsGapDays: days between two. carousels, customSlug (the shop's own address on Spaidoo's portal), peopleLists (who each person is, in the reports): included or not. contactsExport: always true |
automations | The alert types it includes (§4.14) |
integrations | The tools it can connect (the id of §4.19) |
reports | The ids of the reports it includes in Spaidoo's admin |
New keys, ids and features may appear: show only the ones you know.
4.13 POST /terms/accept — accept Spaidoo's terms from the connector
A shop signed up by its connector (§3.4) has never been in Spaidoo's admin. The merchant accepts Spaidoo's terms in the connector's panel, and the connector tells Spaidoo:
{ "version": "2026-09-10", "acceptedBy": "staff-88120345", "at": 1759560000 }version: thestore.termsVersionthe merchant was shown (§4.3), with the text atstore.termsUrls.acceptedBy: who accepted: the staff member's id in the platform, never an email (400if it looks like one). Kept, with the shop, the version and the time, as the proof of acceptance.at: when they accepted, Unix seconds. Kept beside the time the call reached Spaidoo;atin the future is taken as now.
→ 200 { "termsAccepted": true, "termsVersion": "2026-09-10", "acceptedAt": 1759560003 }. Accepting the same version again changes nothing.
409 TERMS_VERSION_OUTDATEDwithcurrentVersionwhenversionis not the one in force (the merchant was shown an old text): show the new one and ask again.- The acceptance is the shop's, wherever it is done: accepting in Spaidoo's admin also turns
termsAcceptedtotrue. - Until the shop accepts, the writes of §4.10 and the imports (§4.8, §4.8.1) answer
409 TERMS_NOT_ACCEPTED. Everything else keeps working: the catalogue, the identity and the widget in the shop.
4.14 Automatic alerts — /automations
The shop's automatic alerts, the same as in Spaidoo's admin (Avisos automáticos): Spaidoo tells each person when something happens to what they saved. The connector's panel can list, create, change and remove them. Spaidoo writes each alert's title and text in each customer's language; the shop only adds, if it wants, a closing text.
Only the types the shop itself can set off: following the shop (new follower, unfollow) only happens in Spaidoo's portal and apps, and those two stay in its admin.
GET /automations → 200:
{
"kinds": [
{ "type": "price_drop", "plan": "pro", "setting": { "key": "minDropPercent", "min": 1, "max": 90, "default": 5 }, "products": true, "link": false, "push": true, "multiple": true }
],
"automations": [
{
"id": "6702a1b2c3d4e5f6a7b8c9d0", "type": "price_drop", "name": "Bajada de precio", "status": "active",
"config": { "minDropPercent": 10 },
"note": { "es": "Usa el código VUELVE10 en tu compra.", "en": "Use the code VUELVE10 at checkout." },
"link": null, "reach": { "sent": 42, "seen": 31 }, "lastSentAt": 1759400000, "createdAt": 1759300000
}
]
}kinds: what each type needs, as Spaidoo decides it. Draw the panel from here, without copying the rules into the connector:
| Field | What it is |
|---|---|
type | price_drop (its price dropped), back_in_stock (it was sold out and can be bought again), saved_reminder (saved N days ago), visit_reminder (N days without coming back), first_product_saved (their first save), product_saved (saves a product), products_threshold (reaches N saves), product_removed (removes a product) |
plan | The plan that includes it: growth or pro. There are no alerts on starter |
setting | The type's number (key: minDropPercent, days or productsCount) with its minimum, maximum and default; null when it has none |
products | Whether it can be limited to some products (config.productIds) |
link | Whether the alert carries its own link to the shop's website |
push | Whether, besides the widget, it also goes out as a push notification (the type decides, not the shop) |
multiple | Whether the shop can have several of the type (for instance, one per collection). false for first_product_saved: a single moment per person |
automations: the shop's alerts of those types, oldest first. There can be several of the same type when its multiple is true. config.productIds are the product ids of the connector's feed; without it, the alert covers every product. reach: alerts made and seen since it exists. Dates in Unix seconds.
POST /automations { "type", "name", "status"?, "config"?, "note"?, "link"? } → 201 with the alert. status defaults to active; without the setting number, its default. note: the closing text, one per language ({ "es": "…", "ca": "…" }, up to 300 characters each), in any of the alerts' languages: es, en, ca, fr, de, it, pt, nl, cs, da, fi, ja, ko, nb, pl, sv, th, tr, vi, zh (the same 20 for the posts, notifications and carousels of §4.15–§4.17). The primaryLanguage one is required: it is what a reader in a language without a text gets. GET tells the shop's languages (languages, those of its profile and its catalogue) and its own (primaryLanguage): show them as tabs.
PUT /automations/:id with the fields that change → 200 with the alert. config is replaced whole. The type does not change: another type is another alert. DELETE /automations/:id → 204; the alerts nobody has seen go with it.
400 PUSH_REQUIRES_PLAN: onstarter, when creating any alert switched on or switching one on. Created with"status": "paused"it needs no plan: it waits, ready, for the shop to change plans.400 ALERT_REQUIRES_PRO: switching on aprotype on a lower plan. Creating it paused, changing it while paused and pausing it are always allowed.400 NOTE_LANGUAGE_MISSING: the closing text lacks the shop's own language (primaryLanguage).400 CAMPAIGN_LINK_NOT_SHOP: the link is not on the shop's domains.400 BAD_REQUEST: a field the type does not take, or a number outside its range.409 AUTOMATION_ALREADY_EXISTS: creating another of a type withmultiple: false.404 NOT_FOUND: not one of the shop's alerts of these types.- Like the writes of §4.10, creating and changing wait for the terms (
409 TERMS_NOT_ACCEPTED, §4.13). Reading and removing do not.
4.15 Board — /posts
The shop's posts, the same as in Spaidoo's admin (Tablón de anuncios): an image, a headline, a text and a button, per language, on the board of the shop's widget and in the portal. growth has it (10 posts a month, 1 day between two) and so does pro (no limit, no wait). starter has no posts: it can read them, keep drafts and remove them, but not publish.
GET /posts ?status=published|draft&search=…&cursor=…&limit=1-50 (all optional) → 200:
{
"quota": { "plan": "growth", "used": 2, "quota": 10, "remaining": 8, "gapDays": 1, "nextAllowedAt": null },
"languages": ["es", "en"],
"primaryLanguage": "es",
"counts": { "all": 1, "published": 1, "draft": 0 },
"posts": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "status": "published",
"content": { "es": { "title": "Nueva colección de invierno", "text": "Ya están aquí los abrigos…", "ctaLabel": "Ver la colección", "ctaUrl": "https://shop.example.com/collections/invierno", "imageUrl": "https://cdn.spaidoo.com/posts/invierno.jpg" } },
"importance": "featured", "highlightDays": 7,
"publishedAt": 1759400000, "editedAt": null, "createdAt": 1759400000, "reach": { "views": 320, "clicks": 41 }
}
],
"nextCursor": null
}| Field | What it is |
|---|---|
quota | The month's posts: used, quota and remaining (null for the last two: no limit), gapDays between two, and nextAllowedAt, when the next can be published (null: now) |
counts | All the shop's posts, whatever the page: in total, published and drafts |
posts | A page (24 unless another limit is asked): drafts first, then published, newest first. status filters by state and search by headline or text, in any language |
nextCursor | The next page's cursor, with the same filters; null: there is no more |
status | published or draft. A published post never goes back to draft: it is edited or removed |
languages, primaryLanguage | The languages the shop writes in, its own first and required. A reader in a language without a text gets the shop's |
content | Per language (any of the alerts' 20, §4.14), the shop's own required. text (up to 300), and optional title (140), ctaLabel (80), ctaUrl (a URL, up to 300) and imageUrl (up to 1000) |
importance | How much it makes itself noticed: normal (only on the board), featured (also marks the widget's button), important (also opens by itself once, on entering) |
highlightDays | For how many days a featured or important post makes itself noticed (1–30, default 7) |
reach | Times it was seen on the board, and clicks, since it was published |
POST /posts { "content", "importance"?, "highlightDays"?, "status"? } → 201 with the post. By default it is published and uses one of the month's posts; "status": "draft" keeps it without publishing or using anything. POST /posts/:id/publish publishes a draft → 200.
PUT /posts/:id with the fields that change → 200. content is replaced whole. Editing never publishes again nor moves the post. DELETE /posts/:id → 204; it does not give back the month's post.
POST /posts/image { "image": "data:image/…;base64,…" } → 201 { "url" }: the uploaded image, for a language's imageUrl. The request's body may be up to 5 MB; as base64 grows an image by a third, that is an image of about 3.7 MB.
400: the text in the shop's own language is missing (content.<primaryLanguage>.text).400 POST_REQUIRES_PLAN: onstarter, when publishing (creating a published one or publishing a draft).400 POST_QUOTA_REACHED: the month's posts are used up.400 POST_GAP_TOO_SOON: the wait since the last one is not over (nextAllowedAtsays when).404 NOT_FOUND: not one of the shop's posts.- Like the writes of §4.10, creating, changing, publishing and uploading an image wait for the terms (
409 TERMS_NOT_ACCEPTED, §4.13). Reading and removing do not.
4.16 Notifications — /notifications
A message the shop writes to a group of its customers, the same notifications as in Spaidoo's admin (Notificaciones): it arrives as a push notification to whoever has them on, and as a card in the widget's alerts tray. The connector's panel can list them, create them, send or schedule them, change them while not sent, and remove them.
GET /notifications ?status=sent|pending|draft&search=…&cursor=…&limit=1-50 (all optional) → 200:
{
"audiences": [
{ "id": "audience_total", "name": { "es": "Audiencia total", "en": "Total audience" }, "description": { "es": "…", "en": "…" }, "people": 212 }
],
"quota": { "plan": "growth", "quota": 4, "used": 1, "remaining": 3, "nextAllowedAt": null, "gapDays": 1 },
"languages": ["es", "en"],
"primaryLanguage": "es",
"counts": { "all": 1, "sent": 1, "pending": 0, "draft": 0 },
"notifications": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "name": "Rebajas de otoño", "status": "sent", "audience": "audience_total",
"content": { "es": { "title": "Rebajas de otoño", "message": "Lo que guardaste, hasta un 30 % menos.", "url": "https://shop.example.com/collections/rebajas" } },
"push": true, "sendAt": null, "sentAt": 1759410000, "validUntil": null, "reach": { "sent": 212, "seen": 143, "clicked": 37 }, "createdAt": 1759400000
}
],
"nextCursor": null
}| Field | What it is |
|---|---|
audiences | The groups it can be sent to, with their name and description in es and en and how many people each has now (people). Spaidoo decides them |
quota | The plan's sends this month (quota, used, remaining) and the least wait between two (gapDays; nextAllowedAt, in Unix seconds: when one can be sent now, if not yet). Everything counts at the moment a notification GOES OUT: a scheduled one uses a send of its date's month, and two of them (sent or scheduled, in any order) must be gapDays apart. Deleting a scheduled one that has not gone out, or turning it back into a draft, gives its send back. On starter they are not sent: they are set up and kept as drafts, and sent after changing plans |
counts | All the shop's notifications, whatever the page: in total, sent, pending (scheduled, paused or sending) and drafts |
notifications (list) | A page (24 unless another limit is asked), newest first. status filters by group and search by name, title or message, in any language. nextCursor: the next page's cursor, with the same filters; null: there is no more |
validUntil | Until when what it says holds (a weekend offer), in Unix seconds, or null: no end. Past it, the notification stays in the widget's tray marked as ended and without its link, and no longer opens by itself nor marks the widget. It must come after it goes out. Sent when creating or changing it; null takes it away |
languages, primaryLanguage | The languages the shop writes in, its own first and required. A reader in a language without text gets the shop's |
status | draft, scheduled, paused, sending or sent |
content | Per language (any of the alerts' 20, §4.14): title (up to 100), message (up to 200) and an optional url, a page of the shop (http(s), up to 2048) |
push | Whether, besides the widget's tray, it goes out as a push. Defaults to true |
reach | Cards made in the tray, seen and clicked |
GET /notifications/:id/stats → 200: what a notification reached, as in Spaidoo's admin.
{
"totals": { "created": 212, "pushed": 96, "shown": 143, "read": 75, "clicked": 37 },
"period": "day",
"series": [{ "day": "2026-10-02", "created": 212, "pushed": 96, "shown": 118, "read": 65, "clicked": 29 }]
}| Field | What it is |
|---|---|
created | How many people it reached: an alert in each one's widget tray |
pushed | Of them, how many also got it as a push (phone or computer) |
shown, read, clicked | How many saw it in the tray, opened it, and went to its link |
period, series | Its life: from the day it went out to its last day with anything (not up to today: one from a year ago is told the same as one from yesterday), oldest first, days without anything at 0. By day (period: day) or, past 60 days, by week (week, each with its first day). day: YYYY-MM-DD, UTC |
POST /notifications { "name", "audience", "content", "push"?, "send", "sendAt"? } → 201 with the notification. name (up to 200) is the shop's own, never shown to customers. send: draft (kept without sending), now (sent right away) or schedule (sent at sendAt, Unix seconds in the future). Sending or scheduling takes one of the month's sends at that moment; a draft does not.
PUT /notifications/:id with the fields that change, while it is draft, scheduled or paused → 200. content is replaced whole; send decides again what happens. DELETE /notifications/:id → 204; it does not give back the month's send.
400 PUSH_REQUIRES_PLAN: onstarter, when sending or scheduling. Saving or editing a draft needs no plan.400 PUSH_QUOTA_REACHED: the month's sends are used up.400 PUSH_GAP_TOO_SOON: the wait since the last one is not over.400 BAD_REQUEST: a group not inaudiences, no text in the shop's language, or a pastsendAt.409 NOTIFICATION_ALREADY_SENT: it is being sent or was sent; it no longer changes.404 NOT_FOUND: not one of the shop's notifications.- Like the writes of §4.10, creating and changing wait for the terms (
409 TERMS_NOT_ACCEPTED, §4.13). Reading and removing do not.
4.17 Smart carousels — /carousels
The shop's carousels, the same as in Spaidoo's admin: a row (or a grid) of the shop's products that the widget places on its pages. The shop picks the products by hand, or Spaidoo does: the most viewed, the most saved, each customer's own (what they last looked at, what they saved), or, on a product page, what the people who saved that product saved too. They are of the Pro plan.
GET /carousels → 200:
{
"plan": "pro",
"kinds": [ { "kind": "manual", "products": true, "personal": false, "productPage": false }, { "kind": "saved_together", "products": false, "personal": false, "productPage": true } ],
"languages": ["es", "en"],
"primaryLanguage": "es",
"carousels": [
{
"id": "6702b1b2c3d4e5f6a7b8c9e0", "kind": "most_saved", "name": "Lo más guardado", "status": "active",
"productIds": [], "order": "fixed", "maxVisible": 10, "minProducts": 3,
"title": { "es": "Lo que más guardan", "en": "Most saved" },
"look": { "format": "slider", "template": "card", "showTitle": true },
"location": { "anchor": "product", "cssSelectors": ["main"], "position": "append", "urlPatterns": ["/products/*", "/*/products/*"], "device": "both" },
"reach": { "impressions": 1240, "clicks": 86 }, "createdAt": 1759300000
}
]
}| Field | What it is |
|---|---|
kind | manual (products picked), most_visited, most_saved, recently_viewed (what each customer last looked at), user_library (what each customer saved), saved_together (on a product page: what the people who saved it saved too). kinds tells which pick their products by hand (products), which change with each customer (personal) and which only make sense on a product page (productPage). recently_viewed, user_library and saved_together come out empty for some visitors (a new customer, a product nobody saved yet): those show the most saved instead, and the widget titles them as such |
productIds | manual only: the product ids of the connector's feed, in order, up to 50 (pick them, and show their names and photos, with GET /catalog/products, §4.5.1). order: fixed or random (shuffled for each visitor) |
name | The shop's own name for it (up to 200), never shown to customers |
maxVisible | How many products it shows, 1 to 50 |
minProducts | With fewer products than this (sold out, a visitor with nothing yet, after falling back to the most saved too) it does not show; 1 to 50 and at most maxVisible (400 BAD_REQUEST otherwise). Defaults to 1 |
title | The section's title (up to 200), one per language of the alerts (§4.14); the primaryLanguage one is required when look.showTitle, and is what a reader in a language without a title gets. null: no title |
look | format slider (a row, with arrows) or grid; template card (photo, name and price) or circle (the photo alone, round); showTitle |
location | Where the widget draws it: inside the connector's own place on the page, <div data-spaidoo-carousel="<anchor>"> (§7), when anchor is set and the page has it; otherwise the first element of cssSelectors found on the page, before/after it or inside it (prepend at the start, append at the end), on the pages whose path matches urlPatterns (* one segment, ** any; without it, every page), on desktop, mobile or both. anchor matches ^[a-z0-9][a-z0-9_-]{0,39}$; cssSelectors (up to 10) may be empty when there is an anchor, but one of the two is required; urlPatterns up to 20 |
reach | Times seen and clicks, since it exists |
The connector turns its own templates into location (for instance «at the end of the product page» → main, append, /products/*): Spaidoo does not know each platform's themes. A connector that prints anchors (a theme block, a hook) sets anchor too, and keeps the selectors as the place on pages whose theme does not print it.
POST /carousels { "kind", "name", "status"?, "productIds"?, "order"?, "maxVisible"?, "minProducts"?, "title"?, "look"?, "location" } → 201 with the carousel (status defaults to active). PUT /carousels/:id with the fields that change → 200; title, look and location are replaced whole; the kind does not change. DELETE /carousels/:id → 204.
400 SLIDERS_REQUIRE_PRO: creating a carousel switched on, or switching one on, without the Pro plan. Creating it off ("status": "paused"), changing one that is off, pausing it and removing it are always allowed: what is set up waits for the shop to change plans.400 BAD_REQUEST: amanualone without products,productIdson a kind that picks them itself, a shown title without the shop's own language, or alocationwith neitheranchornorcssSelectors.404 NOT_FOUND: not one of the shop's carousels of these kinds.- Like the writes of §4.10, creating and changing wait for the terms (
409 TERMS_NOT_ACCEPTED, §4.13). Reading and removing do not.
4.18 Integration events — GET /events
What Spaidoo sent to the shop's own tools (§4.19), as it happens: the same log as the live events of Spaidoo's admin, for the connector's panel to show. Any plan can read it (sending to a tool is what needs a plan). Kept 30 days. No capability.
GET /events?event=…&provider=…&productId=…&from=…&to=…&before=…&limit=… (all optional) → 200:
{
"items": [
{
"eventId": "3b2f6c1e-8a4d-4f7b-9c2e-1d5a7e9b0c42", "event": "price_drop", "createdAt": "2026-10-14T09:12:05.000Z",
"identified": false, "recipients": 18, "test": false,
"properties": { "old_price": 39.9, "new_price": 29.9, "discount_pct": 25, "currency": "EUR" },
"productId": "7f3c2a10-5b1e-4c8a-9f0d-2e6b8a4c1d90-987",
"product": { "name": "Abrigo de lana", "image": "https://shop.example.com/media/987.jpg", "url": "https://shop.example.com/products/abrigo-de-lana" },
"deliveries": [
{ "provider": "klaviyo", "status": "partial", "counts": { "accepted": 15, "skipped": 3, "failed": 0, "retrying": 0 }, "reasons": { "no_identity": 3 }, "attempts": 1 }
]
}
],
"next": null,
"total": 1
}| Field | What it is |
|---|---|
items | Newest first, limit a page (1–100, default 50) |
eventId | The event's id, a UUID: the same event_id the tools received |
event | product_saved, product_removed, product_clicked (what a visitor did), price_drop, back_in_stock, saved_reminder (one row for everybody it concerns), email_consent_granted, email_consent_revoked. New names may appear; a name never changes once published |
createdAt | When it happened. This log uses ISO 8601 dates (UTC), not Unix seconds: createdAt, next, before, from and to alike |
identified | For what a visitor did: whether they were signed in |
recipients | For price_drop, back_in_stock and saved_reminder: how many people it concerns; null for the rest |
properties | What the tools got besides the product, such as surface (where a product was saved), origin (where a click came from: alert, post, carousel, email, push or spaidoo), old_price, new_price, discount_pct and currency (a price drop). Informative: more may appear |
test | true for the sample sent by POST /integrations/:provider/test |
productId | Spaidoo's id of the product, not the feed's: take it as it comes, to filter by that product (?productId=). null for an event without a product (the consents) |
product | { name, image, url } from Spaidoo's catalogue, in the shop's own language (as GET /stats), or null when the product is no longer there |
deliveries | One per tool it went to: { provider, status, counts, reasons, attempts }. status: accepted, partial (some of the people), failed, skipped (nothing to send: nobody the tool can know, say) or retrying. counts: people per outcome (a tool without people, such as a webhook, counts 1). reasons: why the ones not accepted were not, with how many. Empty when no tool was connected |
next | When the page is full, the before of the next one (its last row's createdAt); null: no more |
total | How many rows match the filters, across every page; only on the first page (null on the pages asked with before): keep the first one |
Filters, all optional and together: event (one name), provider (only what went to that tool, its id of §4.19), productId (as a row returns it), from and to (ISO 8601 date-times, both included); before pages inside them. 400 VALIDATION_ERROR for a date that is not ISO 8601 or a limit out of range.
4.19 The shop's tools — /integrations
The shop connects its own tools (email marketing such as Klaviyo or Mailchimp, analytics such as GA4, a webhook of its own) and Spaidoo sends them what happens with its products and customers (§4.18): the same integrations as in Spaidoo's admin, from the connector's panel. A connected tool gets every event it supports; the shop only says where (a list, a URL). No capability.
GET /integrations → 200:
{
"tier": "growth",
"providers": [
{
"id": "webhook", "brand": { "color": "#303030", "logo": "https://cdn.spaidoo.com/integrations/webhook.svg" },
"auth": "secret", "layer": "server", "minTier": "growth",
"events": ["product_saved", "product_removed", "product_clicked", "price_drop", "back_in_stock", "saved_reminder", "email_consent_granted", "email_consent_revoked"],
"configFields": [{ "key": "url", "type": "url", "required": true }],
"integration": {
"status": "connected", "account": null, "config": { "url": "https://hooks.example.com/spaidoo" },
"health": { "lastSuccessAt": "2026-10-14T09:12:06.000Z", "consecutiveFailures": 0 }, "createdAt": "2026-10-10T16:00:00.000Z"
}
},
{
"id": "klaviyo", "brand": { "color": "#232426", "logo": "https://cdn.spaidoo.com/integrations/klaviyo.svg" },
"auth": "oauth2", "layer": "server", "minTier": "growth", "events": ["product_saved", "price_drop"],
"configFields": [{ "key": "listId", "type": "select", "required": false, "dynamic": true }],
"integration": null
}
],
"upcoming": []
}| Field | What it is |
|---|---|
tier | The plan the shop uses now |
providers | The tools the shop can connect. Draw the panel from here: Spaidoo adds tools without the connector changing |
id | Stable, ^[a-z0-9_-]+$: the :provider of the routes below |
brand | color (#rrggbb) and logo, an SVG drawn for that colour |
auth | oauth2 (the merchant signs in at the tool, in a window), secret (Spaidoo issues a signing secret, a webhook) or none |
layer | server (Spaidoo sends the events) or browser (the widget hands them to the tool the shop already loads on its pages) |
minTier | The plan it needs |
events | The events it gets, all of them once connected (§4.18) |
configFields | What it asks: { key, type: "string" | "number" | "url" | "select", required, options?, dynamic? }. dynamic: a select whose options come from the shop's account at the tool, once connected |
integration | The shop's, or null if it never connected it: { status, account, config, health, createdAt }. status: connected, error (it keeps failing; still connected) or revoked (disconnected). account: { id?, name? } at the tool. config: the values of configFields. health: { lastSuccessAt?, lastErrorAt?, lastError?, consecutiveFailures }. Dates in ISO 8601 |
upcoming | Tools on the way, { id, layer, minTier, brand }: show them greyed out; they cannot be connected yet |
POST /integrations/:provider/connect { "config"?, "rotateSecret"? } → 200:
oauth2:{ "authorizeUrl": "…" }. Open it in a new window, from the merchant's click, never in an iframe. The tool sends the merchant back to Spaidoo's admin, which posts{ "type": "spaidoo:integration-connected", "provider", "status": "ok" | "error", "reason"? }towindow.openerand closes. Accept it only whenevent.originishttps://admin.spaidoo.com; and as some tools cutwindow.opener, also readGET /integrationsagain every few seconds while the window is open.reason:denied,invalid_state,provider_error,not_configured,token_exchange_failed,internal.secretandnone: connected at once,{ "integration": {…}, "secret"? }.secret(a webhook's signing secret) comes only the first time, or with"rotateSecret": true: show it once, it never comes again. Connecting again with anotherconfigkeeps it.
PATCH /integrations/:provider { "config": {…} } → 200 { "integration" }: merged over the current one and checked whole.
DELETE /integrations/:provider → 200 { "integration" } with status: "revoked": the access is revoked at the tool when it allows it and Spaidoo forgets the credentials. No more events go to it.
POST /integrations/:provider/test → 200 { "queued": true }: Spaidoo sends a sample event (test: true) the real way; it shows in GET /events within seconds.
GET /integrations/:provider/options/:field → 200 { "options": [ { "value", "label" } ] }: the choices of a dynamic field, read now from the shop's account at the tool.
403 INTEGRATION_REQUIRES_PLANwithrequiredTier: connecting, changing or testing a tool above the shop's plan. A plan error, not a dead key (§2): offer the plans (§4.12, orPOST /ssowithbilling). Reading and disconnecting never need a plan: a shop that went down a plan can still see and switch off what it has.404 INTEGRATION_PROVIDER_UNKNOWN: no tool with thatid.404 INTEGRATION_NOT_CONNECTED: changing, disconnecting, testing or reading the options of a tool that is not connected (or isrevoked).400 INTEGRATION_CONFIG_INVALID: theconfigdoes not fitconfigFields(a required field missing, a URL that does not lead to a public address…), or a field with no options to read;messagesays which.409 INTEGRATION_TEST_UNSUPPORTED: abrowsertool: its events happen on the shop's pages, there is no test to send.503 INTEGRATION_UNAVAILABLE: the tool cannot be connected or does not answer right now; try later.- Like the writes of §4.10, connecting, changing and testing wait for the terms (
409 TERMS_NOT_ACCEPTED, §4.13). Reading and disconnecting do not.
4.20 Spaidoo Panel for connectors (optional)
Instead of building its own screens for §4.3.1–§4.19, a connector can embed Spaidoo Panel: the same screens as Spaidoo's own apps (home and status, appearance, analytics, communication, integrations, import and export, plans, terms), served by Spaidoo at https://panel.spaidoo.com and updated without a new release of the connector. The panel holds no secret and calls nothing by itself: every request goes through the page that embeds it, the host, over postMessage. The host is the connector's admin page: a module installed on the shop, whose server holds the API key, or a hosted connector's own server (the hosted bridge is reserved for now; this section describes the module one).
The panel speaks the merchant's admin language (the same 20 as the alerts, §4.14; en otherwise) and decides nothing from the platform's name: what it shows comes from the answers of this contract and from the host's info and actions.
4.20.1 Embedding
The host's admin page renders one iframe:
https://panel.spaidoo.com/?host=module&platform=<id>&lang=<bcp47>&origin=<urlencoded parent origin>| Parameter | What it is |
|---|---|
host | module: the panel talks to the parent page with postMessage. hosted is reserved |
platform | A free label (the platform of §4.1). Shown as text only, never branched on |
lang | The admin user's language; the panel falls back to en |
origin | The parent page's origin. The panel only talks to window.parent and only accepts messages whose event.origin is this one |
- iframe attributes:
allow="clipboard-write", nosandbox(the panel opens popups and downloads files). - For development, let the panel's URL be configured in the host (for instance
http://localhost:5180). - The host only accepts messages whose
event.originis the panel origin it configured and whoseevent.sourceis the iframe'scontentWindow.
4.20.2 Messages and handshake
Every message is a plain object:
{ "source": "spaidoo-panel", "v": 1, "type": "request", "id": "6f1c2e8a-0b3d-4c5e-9a7f-2d4b6c8e0a1f", "nonce": "b3f9a1c7d2e4" }source is spaidoo-panel from the panel and spaidoo-host from the host; v is the protocol version; id pairs a request with its answer.
- Panel → host:
{ "type": "hello", "id" }, repeated every 500 ms until answered. After 20 s without an answer the panel shows that the host is not responding. - Host → panel:
{ "type": "welcome", "id", "nonce", "info" }.nonceis random per page load; every later message of the panel carries it.
{
"platform": { "id": "my-platform", "name": "My Platform", "version": "8.1.7" },
"connector": { "version": "3.0.0" },
"lang": "es",
"user": { "id": "12", "name": "Ana", "email": "ana@shop.example.com" },
"shop": { "name": "Mi tienda", "url": "https://shop.example.com", "currency": "EUR" },
"connected": true,
"capabilities": { "privacy": true, "importSources": true }
}langis a language code (es,fr), with a region only where the panel has separate locales:pt-BR/pt-PT,zh-CN/zh-TW.connected: false: the shop is not paired yet; the panel shows only its connect screen (platform.connect, §4.20.4).capabilitiessays which optional actions the host offers:privacy(the platform has its own data-request tools),importSources(wishlists readable directly on the platform). Unknown keys are ignored.- The terms are accepted as
<platform.id>:<shop url host>:user:<user.id>inacceptedBy(§4.13).
4.20.3 API requests: the host's proxy
Panel → host:
{ "type": "request", "id": "…", "nonce": "…", "method": "GET", "path": "/stats", "query": { "period": "30d" }, "body": null }Host → panel:
{ "type": "response", "id": "…", "status": 200, "body": { "period": "30d" } }pathis relative to/connector/v1. The host's server sends the request to Spaidoo withAuthorization: Bearer <apiKey>and answers the status and body Spaidoo gave, errors included.- Allowlist. The host forwards only these method + path pairs (
{id}one path segment) and answers anything else{ "status": 403, "body": { "errorCode": "PANEL_PATH_NOT_ALLOWED" } }without calling Spaidoo:
| Routes | Methods |
|---|---|
/status, /stats, /analytics, /search-analytics, /search-analytics/find, /events, /billing, /plans, /shop-data, /shop-data/export, /integrations, /integrations/{id}/options/{field}, /notifications/{id}/stats, /catalog/products (§4.5.1) | GET |
/widget/state, /widget/appearance, /widget/placement, /widget/save-buttons, /widget/custom-css, /widget/hints, /widget/library-selector | POST |
/automations, /posts, /notifications, /carousels | GET, POST |
/automations/{id}, /posts/{id}, /notifications/{id}, /carousels/{id} | PUT, DELETE |
/posts/image, /posts/{id}/publish, /integrations/{id}/connect, /integrations/{id}/test, /wishlists/import/file, /terms/accept, /sso, /catalog/feeds/read | POST |
/integrations/{id} | PATCH, DELETE |
- Never forwarded, whatever the panel asks:
pairing/*,handshake,uninstall,identity-secret/*,customers/*,catalog/changes,PUT /catalog/feeds,shop-redact. Those belong to the connector's own server. - A response that is not JSON (
GET /shop-data/export) comes back as{ "status", "headers": { "content-type", "content-disposition" }, "bodyBase64" }; the panel builds the file and downloads it. POST /posts/imagecarries the same JSON body as the route (§4.15).GET /status: the host removesidentitySecret(and any other secret field) from the body before answering the panel, and stores and acknowledges it itself (§4.2).POST /wishlists/import/filewith customers by email needscustomerLookup(§6.3) accepted in the handshake; by customer id,customers(§4.8.2).- The admin user lacks the platform's permission for the panel:
{ "status": 403, "body": { "errorCode": "PANEL_HOST_FORBIDDEN" } }. Not paired:{ "status": 409, "body": { "errorCode": "PANEL_NOT_CONNECTED" } }. Spaidoo unreachable or a transport error:{ "status": 502, "body": { "errorCode": "PANEL_HOST_UPSTREAM" } }. - The panel waits 60 s for an answer (120 s for
/wishlists/import/file, one batch at a time).
4.20.4 Platform actions
What the panel cannot know by itself, it asks the host: panel → host { "type": "action", "id", "nonce", "name", "args" }; host → panel { "type": "result", "id", "ok": true, "data" } or { "type": "result", "id", "ok": false, "error": { "code", "message" } }. An action the host does not offer answers ok: false with ACTION_UNKNOWN.
name | args → data | What the host does |
|---|---|---|
platform.connect | { mode: "signup" | "login" } → { connected: true } | Opens the pairing popup (§3.2) from the parent page: the panel sends the action from the merchant's click and the host calls window.open at once in its message handler, so the browser keeps the gesture. Resolves when the popup reports back |
platform.disconnect | – → { connected: false } | POST /uninstall (§4.4) and forgets the API key |
platform.storefront | – → { widgetInstalled, locked, lockReason? } | widgetInstalled: the loader is printed on the storefront (the connector is enabled and hooked into the theme). locked: the shop is closed to the public; lockReason maintenance or coming_soon |
platform.carouselZones | – → [ { id, kind, available } ] | The places where the connector prints a carousel anchor (§7, data-spaidoo-carousel): id home, product, collection or the connector's own; kind fixed or custom; available whether it is printed now |
platform.importSources | – → [ { id, label, customers, items } ] | Wishlists the host can read directly on the platform (a previous wishlist module, say), with how many customers and items. Empty: only the file import (§4.8.2) |
platform.importRun | { source, cursor? } → { done, cursor, customers, items, errors } | One batch of a direct import, sent with POST /wishlists/import (§4.8). The panel calls it again with cursor until done |
platform.open | { url, target: "_blank" | "_top" } → {} | Opens a URL from the parent page (the POST /sso link, Spaidoo's checkout, a page of the platform's admin): popup blockers trust the parent's gesture |
platform.verifyDomain | – → { verified, reason? } | Proves the shop's domain when going live answers 403 SHOP_NOT_VERIFIED (§4.10): POST /domain-verification, serves the code at its verify route, then POST /domain-verification/check (§4.9). An action, not a proxied path, because the host must serve the code itself |
platform.refresh | – → { info } | Repeats the handshake (§4.1) if it is due and answers a fresh info (after connecting, after a plan change) |
Action error codes (error.code): POPUP_BLOCKED (the browser blocked the popup), CONNECT_CLOSED (the merchant closed the popup), CONNECT_CANCELLED (the merchant cancelled in Spaidoo), CONNECT_FAILED, VERIFY_FAILED, ACTION_UNKNOWN. New codes may appear: treat an unknown one as a failure with its message.
4.20.5 Notifications
No answer expected. Panel → host:
{ "type": "resize", "height" }: the host sets the iframe's height, so the page has a single scroll bar.{ "type": "title", "text" }: the host may setdocument.title.
Host → panel (optional, with the nonce):
{ "type": "viewport", "top", "height" }: the band of the iframe the admin user sees, in the panel's own pixels (integers): below the host's fixed chrome (a sticky admin header) and inside the window. Sent after thewelcomeand on scroll, on window resize and after eachresize, only when it changes and never with a height of0. The panel places its save bar, dialogs and toasts in that band; without it, it measures the top window's viewport, which does not know the host's fixed header.
4.20.6 Security
- The API key never leaves the host's server. The panel holds no secret, and nothing it holds is worth stealing.
- The host's proxy endpoint is on the same origin as the host's admin page (no third-party cookies are involved) and requires the admin session, the platform's permission to manage the shop's settings (
403 PANEL_HOST_FORBIDDENotherwise) and a CSRF token. - Origins are checked in both directions (§4.20.1). The nonce binds the messages to one page load: a message with a wrong or missing nonce is dropped silently.
- The allowlist (§4.20.3) is enforced by the host, not by the panel: a compromised panel can still reach only the panel's routes.
5 Identity — identity
Goal: a customer signed in to the shop sees the same saved products on every device, and can link them to a Spaidoo account. While the shop has a connector with identity, the shop's session rules: Spaidoo never asks the customer to log in to the shop on Spaidoo's behalf.
5.1 The identity route (urls.identity)
The widget calls it from the storefront, same origin, with the shop's cookies:
GET <urls.identity>?anon=<uuid>
| Answer | When |
|---|---|
200 { "assertion": "<assertion>" } | A customer is signed in |
200 { "anonymous": true } | Nobody is signed in (guests count as nobody) |
410 | The connector is disconnected |
Headers: Cache-Control: no-store, private and Vary: Cookie. It MUST never be cached by a page cache or CDN.
5.2 The assertion
payload = base64url( JSON ), no padding
signature = base64url( HMAC-SHA256( key = identity secret as UTF-8 text, data = payload ) )
assertion = payload + "." + signatureJSON:
{ "v": 1, "shopId": "7f3c…", "customerId": "123", "email": "", "anonId": "<the anon query param or null>", "iat": 1759219200, "exp": 1759219260, "jti": "<32 hex chars, random>" }exp - iat≤ 60 s. Spaidoo tolerates 30 s of clock skew.jtiis single use.anonIdechoes?anon=if it is a UUID, elsenull.emailMUST be"": Spaidoo does not keep shop customers' emails (see §6.2).
5.3 The session hint (optional, recommended)
So that the widget notices a login or logout without asking on every page, the connector prints in SpaidooConfig.shopSession (§7):
"" when nobody is signed in, else the first 16 hex chars of HMAC-SHA256(identity secret, "session:" + customerId).
It is a hint, not proof: the widget only uses it to decide when to call the identity route again.
5.4 Login
When the customer wants to keep their list and is not signed in, the widget sends them to urls.login with {back} replaced by the URL-encoded page they were on. After login, the shop MUST redirect back to it (same domain only).
6 Spaidoo → shop (signed calls)
6.1 Signature
Every call Spaidoo makes to a connector URL (except the public verify and feed) carries:
| Header | Value |
|---|---|
X-Spaidoo-Timestamp | Unix seconds |
X-Spaidoo-Nonce | 32 random hex chars |
X-Spaidoo-Signature | base64url( HMAC-SHA256( identity secret, timestamp + "." + nonce + "." + rawBody ) ) |
The connector MUST:
- reject a timestamp more than 300 s away from its clock (
401); - compare the signature in constant time over the raw body (
401); - SHOULD remember nonces for 600 s and reject a repeated one (
401).
6.2 POST <urls.customers> — customers
{ "customerIds": ["123", "124"] }Up to 500 ids. Answer 200:
{ "customers": [ { "customerId": "123", "email": "ana@example.com", "marketingConsent": true, "marketingState": "subscribed", "marketingUpdatedAt": "2026-09-14T08:30:00Z" } ] }- Omit customers that no longer exist, guests and deleted ones.
marketingConsent:truethe customer is subscribed to the shop's marketing emails (newsletter opt-in),falsethey are not,nullthe platform does not know. It istrueexactly whenmarketingStateis"subscribed".marketingState:"subscribed","not_subscribed","unsubscribed","pending"ornull."unsubscribed": the customer explicitly opted out; a platform that cannot tell it apart from never having subscribed answers"not_subscribed"."pending": waiting for the customer to confirm a double opt-in.null: the platform does not know.marketingUpdatedAt: ISO-8601, when the state last changed, ornullif the platform does not know.marketingStateandmarketingUpdatedAtare optional, so that connectors written before them keep working; Spaidoo takes a missing one asnull.- Spaidoo uses the answer at that moment (an export, a campaign audience, a sync to the merchant's email tool) and does not store the emails.
- Answer within 5 s.
410if disconnected.
What Spaidoo does with marketingConsent when the merchant syncs to an email tool (Klaviyo, Mailchimp…): true → subscribed to email marketing; false/null → profile without marketing subscription (transactional flows only).
6.3 POST <urls.customers> by email — customerLookup
The merchant uploads in Spaidoo's panel the lists exported from another wishlist app. Those files name the customer by email, so Spaidoo asks the shop which of its customers they are:
{ "emails": ["ana@example.com", "joan@example.com"] }Up to 500 emails, same route and signature as §6.2. Answer 200:
{ "customers": [ { "customerId": "123", "email": "ana@example.com" } ] }- Compare emails without case. Leave out the emails the shop has no customer with, and guests.
marketingConsentmay be included; it is not used here.- Only the customers in the answer get the lists. Spaidoo uses the emails for this lookup and does not store them.
- Answer within 5 s.
410if disconnected.
6.4 POST <urls.marketingConsent> — marketingConsent
When a customer signed in to the shop says yes, inside the widget, to receiving the shop's emails, Spaidoo asks the shop to turn their email-marketing consent on. Spaidoo only ever grants consent; it never unsubscribes anyone (the customer does that in the shop or from any email).
Spaidoo calls it only for a customer with a shop session (§5) whose state (§6.2) is "not_subscribed" or "unsubscribed", and only after the customer taps yes. Spaidoo asks on its own initiative (when a product is saved) only the "not_subscribed" ones and those "unsubscribed" for more than 30 days; a customer who opens the alerts window can turn it back on at any time.
Signed exactly as §6.1:
{ "customerId": "123", "textVersion": "shop-marketing-save-v1", "consentedAt": "2026-10-07T10:00:00Z" }textVersionidentifies the exact text the customer accepted. Spaidoo keeps the proof of consent: who, when and which text version.consentedAt: ISO-8601, when the customer said yes.
The connector sets the customer's email-marketing consent in the platform to subscribed (single opt-in). If they are already subscribed, nothing changes and the answer is the same (idempotent). If the shop requires double opt-in, the platform may leave them waiting for the confirmation and answer "pending".
Answer 200:
{ "customerId": "123", "marketingState": "subscribed" }marketingState is "subscribed" or "pending".
Errors: 400 malformed body, 401 bad signature, timestamp out of range or repeated nonce, 404 unknown customer, 405 not POST, 410 shop disconnected, 503 the platform failed.
7 Storefront
What the connector prints on the shop's pages (every page except the excluded ones):
<script data-spaidoo-config='{"currency":"EUR","shopSession":"","priceFormat":{"currency":"EUR","sample":"€1.234.567,89"},"themeId":"148392011","push":{"swUrl":"https://shop.example.com/spaidoo/push-sw.js","swScope":"/spaidoo-push/"}}'>
(function (s) { window.SpaidooConfig = Object.assign(window.SpaidooConfig || {}, JSON.parse(s.getAttribute('data-spaidoo-config'))); })(document.currentScript);
</script>
<script src="{scriptUrl}" async></script>window.SpaidooConfig — every key optional:
| Key | Value |
|---|---|
currency | ISO code of the currency the visitor is browsing in. The widget shows prices in it (from spaidoo:price) |
shopSession | Session hint (§5.3) |
priceFormat | { currency, sample }: how the shop writes prices in the visitor's currency. sample is the platform's own formatting of the amount 1234567.89 in currency, as plain text (whatever the platform's own price formatting writes in its templates), e.g. "€1.234.567,89" or "1 234 567,89 €". Knowing the digits, the widget reads the decimal and thousands separators, the decimals and the symbol's side and spacing, and writes its own prices the same way, whatever the page's language. Omit it when the platform can't tell; the widget then writes them the standard way of the language and currency |
themeId | The shop's current design, as the platform identifies it (the published theme's id, or its name). The widget reads from the page how the shop writes a product's name and price (the carousels' card look, §4.17) and Spaidoo keeps it for everyone; when themeId changes, the widget reads it again instead of waiting for it to expire. Omit it when the platform can't tell |
preview | true only for the shop's staff while the widget is in preview mode |
push | { swUrl, swScope } when push is declared |
- Never print the script on the cart, checkout or payment pages, and list them in
storefront.excludePaths(§4.1): the widget does not run there, so nothing of Spaidoo (button, save icons, carousels) shows there. - A full-page cache must keep one copy per currency (as it already does for prices).
Save buttons (optional): where the theme should show Spaidoo's save icon, print an empty anchor. The widget draws the icon, handles the click and the state.
<span data-spaidoo-save
data-sp-context="product" <!-- "product" (product page) or "list" (cards) -->
data-sp-id="123" <!-- product id of the feed -->
data-sp-url="https://shop.example.com/p/123"
data-sp-name="Blue shirt" <!-- optional -->
data-sp-image="https://…/123.jpg"></span> <!-- optional -->Its design and size come from Spaidoo's admin (§4.3); the widget adds no layout of its own. Placed over a photo, the anchor goes in the corner saveAnchors.position says.
Library link (optional): any element with data-spaidoo-library opens the customer's list (e.g. an entry in the account menu).
Carousel places (optional): where the theme has room for Spaidoo's smart carousels (§4.17), print an empty, named anchor. The widget mounts inside it the active carousels whose location.anchor is one of its names, in their order; a carousel whose anchor is not on the page goes to its cssSelectors. An anchor may answer to several names, space-separated, and with one name on several anchors the page's first one takes it: so a page can have several zones, each with its own name, and the page's name as well for the carousels set before it had any.
<div data-spaidoo-carousel="product"></div> <!-- under the product page -->
<div data-spaidoo-carousel="home-banner home"></div> <!-- a zone of the home page -->- Names:
^[a-z0-9][a-z0-9_-]{0,39}$. The conventional ones arehome,product(product page) andcollection(product listings); any other is a place of the shop's own, named in Spaidoo's admin. There are no carousels on the cart or the checkout: the widget never loads there (above), so do not print anchors on those pages. - Print it with nothing inside and no height: on most pages there is no carousel for it. Once the widget has looked, it marks the element
data-spaidoo-filled(something mounted) ordata-spaidoo-empty(nothing for it on this page). - To keep the page from moving when a carousel arrives, the theme may reserve its height with
--spaidoo-carousel-reserve(for instancestyle="--spaidoo-carousel-reserve: 380px"); the theme's own CSS applies it, as it has to be there before the widget arrives, and the widget only marks the anchor withdata-spaidoo-filledordata-spaidoo-empty. For instance:[data-spaidoo-carousel]:not([data-spaidoo-filled]):not([data-spaidoo-empty]) { min-height: var(--spaidoo-carousel-reserve, 0) }. The theme should also release it after a few seconds in case the widget never loads.
7.1 Push service worker — push
Web push is registered on the shop's domain, so the connector serves Spaidoo's service worker at urls.pushWorker:
Content-Type: application/javascript,Cache-Control: no-cache.Service-Worker-Allowed: <pushScope>when the scope is outside the worker's own directory. A worker served inside its scope (/apps/spaidoo/push-sw.jswithpushScope/apps/spaidoo/, behind a platform's app proxy, say) needs no header.- Body: the reference worker published at
https://cdn.spaidoo.com/connector/v1/push-sw.js(copy it verbatim; do notimportScriptsit from another origin). - It receives data-only messages
{ title, body, link, seen, icon, image, badge, shopId }.linkgoes through Spaidoo's tracking, which counts the click and the read and leads to the shop.seenis POSTed by the worker once it shows the notification, so it counts as seen.
7.2 What the widget tells the page (optional)
A connector's own script on the storefront (the one that places the save anchors over the photos, say) can read what Spaidoo's loader and widget leave on the page. Only what follows is stable:
| What it is | |
|---|---|
SpaidooConfig.merchantId | The shop's id, written by Spaidoo's loader as soon as it runs (absent while the widget is off, and in preview for a visitor without the preview link or SpaidooConfig.preview). It says the loader ran, not that the widget will start: on an excluded page (§4.1) the loader stops just after writing it. Before placing anything, wait for spaidoo:anchor-ready |
SpaidooConfig.saveAnchors | { position, product?, list?, header?, listPhoto?, productPhoto? }, the same as store.pluginConfig.saveAnchors (§4.3), written by the loader only when something differs from the defaults: product, list and header appear only as false. Absent: everything on, top-right |
SpaidooConfig.searchHeader | true when the search is on and the merchant wants it opened from the header; absent otherwise. The connector uses the search entry the theme already has, or places its own beside the cart, and opens the search with spaidoo:show-section |
SpaidooConfig.icon | "heart" when the shop's symbol is the heart; absent: the bookmark. For a header icon of the connector's own that matches the widget's |
spaidoo:anchor-ready | A CustomEvent on each save anchor (data-spaidoo-save), bubbling up to document, once the widget drew it, or hid it because its kind of page is off. No detail |
spaidoo:panel-open / spaidoo:panel-close | On window, each time the list's panel opens or closes. No detail |
spaidoo:show-section | Sent by the page to window with detail: { section: "library" }: the widget opens the customer's list. With { section: "search" } it opens the search, confirmed by spaidoo:search-open. Not answered before the widget starts: send it again until spaidoo:panel-open arrives (a few times, a few hundred ms apart) |
None of these events can be cancelled. Any other key of SpaidooConfig or event of the widget is internal and may change.
8 Conformance
A connector is Spaidoo-compatible v1 when the online conformance check passes with no failures for every capability it declares.
Connect a test installation of your platform with your connector (any shop reachable from the internet: a staging domain, or a tunnel such as ngrok or Cloudflare Tunnel for a local one), then run the check from the developers' page with that shop's API key. Spaidoo already holds the handshake and the identity secret, so no secret is ever pasted anywhere.
The same check is available to your own tooling:
POST /connector/v1/conformance{ "shop"?: "<product page>", "checkout"?: "<cart page>", "cookie"?: "<Cookie header of a signed-in test customer>", "customer"?: "<customer id>" }→202 { "runId": "…" }. The pages must be on the shop's domains. Ten runs an hour per shop (429+Retry-After).GET /connector/v1/conformance/{runId}→{ "status": "running" }, then{ "status": "done", "conformant": true|false, "counts": {…}, "results": [ { "capability", "title", "status": "pass"|"fail"|"warn"|"skip", "detail"?, "spec"? } ] }. Kept one hour.
It checks the handshake (with the URL each declared capability needs: customerLookup the customers route, marketingConsent, push, billing.platform and panel.widget theirs), the feeds and their items, the identity route and its assertions, the signed customers route (nonce, signature, raw body, age, limits, marketingState and marketingUpdatedAt when sent and in agreement with marketingConsent, and the lookup by email with customerLookup), the signed marketingConsent route without granting anything (a customer no shop has must answer 404; a repeated nonce, a wrong signature and a request older than 300 s 401; a body without customerId 400; a GET a 4xx), the verify route, the push worker, and the storefront (loader, SpaidooConfig, save anchors, nothing on the checkout). The calls from the connector to Spaidoo (catalog.changes, customerErase, wishlistImport, billing.platform) and the connector's own panel (panel.widget) are listed with how to check them by hand. Granting the consent for real is checked by hand: say yes to the shop's emails in the widget as a signed-in test customer and look for the consent in the platform.
The panel's reads and writes with no capability (/catalog/products, §4.5.1; /stats and /analytics, §4.3.1 and §4.3.2; /plans, §4.12.1; the alerts, posts, notifications and carousels, §4.14–§4.17; the integration events and the shop's tools, §4.18 and §4.19) are not part of the check: a connector may offer any of them, and the check says nothing about them. Neither is Spaidoo Panel (§4.20): check the host's allowlist and its actions by hand.
9 Changes
| Date | Change |
|---|---|
| 2026-09-30 | First draft |
| 2026-09-30 | Pairing with OAuth 2 + PKCE and registered connector apps (§3); server URLs on the app's domains and storefront.domains (§4.1); push worker inside its scope (§7.1) |
| 2026-10-01 | Client secret for hosted apps and provisioning: the connector's server signs the shop up itself (§3.1, §3.4) |
| 2026-10-04 | Plan billed by the platform: capability billing.platform, urls.billing, adminDomains and billingPlatform of the app, PUT/GET /billing (§1, §3.1, §4.1, §4.12). Spaidoo's terms accepted from the connector, 409 TERMS_NOT_ACCEPTED on the writes (§4.10, §4.13). /status documented field by field, with store.billing, store.termsAccepted, store.termsVersion, store.termsUrls, stats.alertsSent and stats.alertClicks (§4.3). Figures by period, GET /stats (§4.3.1). A customer's data for their access request, POST /customers/export (§4.7.1). What an uninstalled connector brought erased with the app's secret, POST /shop-redact (§3.5). Import by rows with a dry run (§4.8.1). theme in the appearance and the errors of each write (§4.10). Intents reports and billing; an unknown intent falls back to panel (§4.11). Disconnecting is POST /uninstall (§4.4). platform.name, panel.widget and urls.panel (§4.1); 409 BILLING_STRIPE_ACTIVE and billing back to Spaidoo after cancelled and an uninstall (§4.12); feeds read-only in Spaidoo's admin while a connector publishes them, 409 FEEDS_MANAGED_BY_CONNECTOR (§4.5) |
| 2026-10-05 | Save button, own selector for the list icon and own CSS per part (§4.10, §4.10.1). topViewed in GET /stats, the three periods worked out together (§4.3.1). The analytics page, GET /analytics (§4.3.2) |
| 2026-10-06 | Automatic alerts from the connector's panel: GET/POST /automations, PUT/DELETE /automations/:id (§4.14). savedRevisits replaces saveToClick in GET /analytics (§4.3.2). An alert's closing text in any of the alerts' languages, the shop's own required: languages and primaryLanguage, 400 NOTE_LANGUAGE_MISSING (§4.14). Board from the connector's panel: GET/POST /posts, PUT/DELETE /posts/:id, POST /posts/:id/publish, POST /posts/image; the post, in any of the alerts' languages with the shop's own required; the list, in pages with status, search and cursor, and counts (§4.15). Notifications from the connector's panel: GET/POST /notifications, PUT/DELETE /notifications/:id, 409 NOTIFICATION_ALREADY_SENT; a notification's text in any of the alerts' languages, the shop's own required; the list, in pages with status, search and cursor, and counts; GET /notifications/:id/stats; validUntil, until when it holds (§4.16). Smart carousels from the connector's panel: GET/POST /carousels, PUT/DELETE /carousels/:id, title per language (§4.17) |
| 2026-10-07 | The customer's email-marketing state in the customers answer: marketingState and marketingUpdatedAt, optional (§6.2). The customer's yes to the shop's emails from the widget: capability marketingConsent, urls.marketingConsent, POST <urls.marketingConsent> (§1, §4.1, §6.4) |
| 2026-10-08 | The shop's customers and contacts for the merchant to take away, GET /shop-data and GET /shop-data/export; the contacts come with Growth and up, contactsLocked (§4.7.2). The widget's texts from the connector, POST /widget/hints, and hints / hintLanguages in /status (§4.10, §4.3). seen in the push message, pinged by the reference worker when it shows it; link always present (§7.1) |
| 2026-10-08 | minProducts in the carousels (§4.17). Carousel places on the storefront, data-spaidoo-carousel (§7), and location.anchor in the carousels, cssSelectors optional with one; the kind saved_together and productPage in kinds; the personal kinds and saved_together fall back to the most saved (§4.17) |
| 2026-10-08 | §7 SpaidooConfig.priceFormat: how the shop writes its prices, a sample of the platform's own formatting; and SpaidooConfig.themeId, the shop's current design |
| 2026-10-09 | Figures and analytics for any range of days: from/to on GET /stats and GET /analytics, period: "custom", 400 STATS_RANGE_INVALID (§4.3.1, §4.3.2) |
| 2026-10-09 | Automatic alert back_in_stock: a saved product that was sold out (no variant in stock) can be bought again; Pro, push, no setting, with products (§4.14). opportunities.unavailable splits sold out and removed (§4.3.2) |
| 2026-10-13 | The floating button placed by pixels from the connector: position: "custom" and offsets in POST /widget/placement and in /status, 400 INVALID_PLACEMENT; 409 PLACEMENT_IS_CUSTOM retired (§4.10, §4.3). Provisioning: panel_url, and a directory shop handed over at once to Spaidoo's own apps (§3.4) |
| 2026-10-15 | The widget never loads on the cart, the checkout or the payment pages: list them all in storefront.excludePaths, and cart is no longer a conventional carousel place (§4.1, §7). No platform names in the text (§3.5, §4.7.2, §7) |
| 2026-10-15 | Integration events, GET /events, and the shop's tools, /integrations (in the API since 2026-10-09; §4.18, §4.19). Only 401 means a dead key; a 403 is about the call (§2). /status field by field: offsets, saveButton, searchProvider / aiProvider, spaidooSearch with its plan and quotas, productAnchor / actionsAnchor, brand deprecated (§4.3). lang, errors and the token of provisioning (§3.4); rotate answers shopId too, CONNECTOR_NOT_CONFIGURED (§4.2); reconnecting goes to preview, domains of another shop left out, pushScope by default (§4.1); CATALOG_CHANGE_CURRENCY_MISMATCH, CATALOG_CHANGES_RATE_LIMIT (§4.6); erasing a customer needs no capability (§4.7); the errors of §4.9. The 20 languages of the texts (§4.14–§4.17) and the limits of posts, notifications, carousels and feeds (§4.5, §4.15–§4.17). The widget's preview (§4.10.2) and what the widget tells the page (§7.2). The checks by hand and what the check leaves out (§8) |
| 2026-10-15 | The products of the figures named: product ({ name, image, url } or null) on every entry with a productId of GET /stats and GET /analytics (§4.3.1, §4.3.2). Spaidoo's plans for the connector's plans screen, GET /plans (§4.12.1). The import from a file with customers by email, POST /wishlists/import/file (§4.8.2); CONNECTOR_CAPABILITY_MISSING names the capability and the errors of the imports go in order (§4.8.1). The 401 of the key carries API_KEY_MISSING / API_KEY_INVALID, the general 429 RATE_LIMITED (§2). lang takes a short tag such as pt-BR (§3.4). The check tests the marketingConsent route without granting, the marketing fields of customers and the URL of every capability (§8) |
| 2026-10-15 | The shop's products as Spaidoo holds them, GET /catalog/products: by title (q, case and accents ignored), by ids or page by page, with title, photo, link, price, sale price and stock (§4.5.1) |
| 2026-10-15 | Spaidoo Panel for connectors: embedding, the bridge's messages, the host's proxy and its allowlist, platform actions and security (§4.20) |
| 2026-10-19 | Provisioning: a new shop with the email of an account your app created is no longer added to it on its own: 409 SHOP_LINK_CONFIRMATION_REQUIRED until the account's owner confirms from the link Spaidoo emails, and resend_confirmation (§3.4) |
| 2026-10-19 | Security: a shop already in the account comes back on its own only to the app that connected it; resend and daily limits of SHOP_LINK_CONFIRMATION_REQUIRED, and a «not mine» stands 30 days (§3.4). A new API key when the shop changes hands (§4.4). Domain verification proves the shop's own domain, never the handshake's storeUrl (§4.9) |
| 2026-10-19 | Every pairing (§3, §3.4) hands out a new API key: Spaidoo keeps only its hash, so store the one you get. The SSO URL opens a «continue as |
| 2026-10-19 | 409 SHOP_LINK_UNAVAILABLE when no link email can go; /pairing/provision/complete takes its token once (§3.4) |
| 2026-11-06 | The contacts download on every plan: contactsLocked always false and features.contactsExport always true (§4.7.2, §4.12.1) |
| 2026-11-06 | Spaidoo's search is on every plan: POST /widget/search turns it on with showSearchButton, no subscription needed. The Spaidoo Search add-on is retired: spaidooSearch leaves /status, and the spaidoo-search intent goes to the providers page (§4.3, §4.10) |
| 2026-11-07 | Opening the search from the header: POST /widget/search takes header and selector; new store.pluginConfig.searchHeader and searchSelector, SpaidooConfig.searchHeader, spaidoo:show-section with { section: "search" } and links to #spaidoo-search |
| 2026-11-06 | The first catalogue: a shop with no products shows no widget until Spaidoo has read its catalogue, and search goes on by itself with its first pack. New store.catalogSetup (§4.3, §4.5) |
| 2026-11-08 | What customers search for: GET /search-analytics (§4.3.3), the whole report on Growth and Pro and a taste of the last 7 days on Starter |
| 2026-11-08 | /search-analytics: averagePosition per query and report.trending, the queries going up or new |
| 2026-11-08 | POST /widget/search takes search: the search on or off, apart from its button on the floating launcher (§4.10) |
| 2026-11-09 | GET /search-analytics/find: one list of the report with a text, on Growth and Pro (§4.3.3) |