Skip to content

Specification · v1

Spaidoo Connector API v1

The public contract between a connector and Spaidoo. Section numbers are the same in English and Spanish: the conformance check and the assistant link to them.

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:

CapabilityWhat it adds
catalog.feedSpaidoo knows the shop's products (price, stock, images) — required
catalog.changesPrice and stock changes reach Spaidoo in seconds instead of on the next daily read
storefront.saveAnchorsThe connector prints the save buttons in the theme (§7); Spaidoo's admin tells the merchant they come from the connector
identityA customer signed in to the shop keeps their saved products on every device, without a Spaidoo account
customersSpaidoo can ask the shop for the email (and marketing consent) of an identified customer when the merchant needs it
customerLookupThe customers route also answers by email: the merchant can import lists from a file exported from another wishlist app
marketingConsentWhen 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
customerEraseDeleting a customer in the shop deletes their Spaidoo data for that shop
wishlistImportLists from a previous wishlist extension are brought into Spaidoo
pushWeb push notifications are served from the shop's own domain
domainVerificationThe shop proves it owns its domain without DNS changes
billing.platformThe 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.widgetThe 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 is 400 VALIDATION_ERROR, with details: [ { field, message } ]. Only 401 means the API key is not valid any more (the shop disconnected, or its key was replaced): the connector must show "disconnected". A 403 is about that one call, never about the key: its errorCode says 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. The 401's errorCode is API_KEY_MISSING (no Authorization: Bearer header) or API_KEY_INVALID (a key Spaidoo does not know); its body also keeps valid: false and error for older readers. 429 carries Retry-After; the API's general rate limit answers errorCode: "RATE_LIMITED", a route's own limit its own code (CATALOG_CHANGES_RATE_LIMIT…). Any 5xx or 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

SecretWhat it isUsed for
API keyOpaque string issued at pairingAuthorization: Bearer <apiKey> on every connector → Spaidoo call
Identity secret32 random bytes, base64url, issued by SpaidooHMAC 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:

redirectModeForCallback (redirect_uri)
fixedA 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
shopA 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

  1. Your server generates a random state and a code_verifier (43–128 characters of [A-Za-z0-9-._~]), keeps both, and computes code_challenge = base64url(SHA-256(code_verifier)) without padding.
  2. 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>
    domain is required; name, email, mode (the tab that opens first), verify (only with domainVerification) and lang are optional.
  3. Spaidoo checks the client_id and the redirect_uri. If either is wrong it shows the error and never redirects.
  4. 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).
  5. 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.
  6. Your server checks state and trades the code within 60 seconds (a code is good for one exchange):

POST /pairing/token — the only call without an API key:

JSON
{ "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.

  1. Store the key server-side and call POST /handshake (§4.1). The redirect_uri page then tells your admin page (postMessage to window.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):

JSON
{ "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-YY or xx-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 of SHOP_LINK_CONFIRMATION_REQUIRED again (below). Send it only on their click.
  • claim: the domain belongs to a shop of Spaidoo's directory. Serve verificationCode at verify (§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 through SHOP_LINK_CONFIRMATION_REQUIRED like 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 call POST /pairing/provision again every few seconds while they look: once they click, it answers 201 and the flow goes on. Asking again does not send another email; resend_confirmation: true does, 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) or 409 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: domain is 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 a fixed app. 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:

JSON
{
  "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_CONNECTED otherwise. 404 NOT_FOUND if the app never connected that shop. 401 OAUTH_INVALID_CLIENT, 403 CONNECTOR_APP_SUSPENDED as 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/erase does 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.

JSON
{
  "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, and verify, 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 the serverDomains of 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: true when 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 means false.
  • 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 the storeUrl domain (§4.9).
  • login MUST 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 (with push): 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 in preview (§4.10), unless it was already live: reconnecting a public shop does not take the widget away from its customers. A connector update changes nothing.
  • A declared domain (storeUrl or storefront.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.id stays the technical, informative id.
  • panel.widget and urls.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 to urls.panel instead. Like urls.billing, urls.panel MUST be https on one of the app's adminDomains; without them the capability is refused (left out). Any platform with a panel may declare it.
  • billing.platform and urls.billing: the platform bills the shop's Spaidoo plan (§4.12). urls.billing is 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 be https on one of the adminDomains of the app the shop connected with (§3.1). The capability is accepted only when that app has billingPlatform enabled by Spaidoo; otherwise it is refused like any switched-off capability (left out, not an error).

Response 200:

JSON
{
  "shopId": "7f3c…",
  "contractVersion": 1,
  "capabilities": { "catalog.changes": true, "identity": true, "…": "…" },
  "identitySecret": "b64url…"
}
  • capabilities are 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, marketingConsent and wishlistImport are refused without identity; billing.platform is refused unless the app has billingPlatform. customerLookup uses urls.customers.
  • identitySecret is 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 /handshake and /status responses until the connector confirms it.
  • POST /identity-secret/ack { "fingerprint": "<sha256 hex of the secret>" } → 200 { "acknowledged": true } (false if 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_CONFIGURED when Spaidoo did not accept identity for this shop.
  • While Spaidoo has the identity switched off, ack and rotate answer 404 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).

JSON
{
  "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" }
    }
  }
}
FieldWhat it is
identitySecretPresent only while there is a secret to deliver (§4.2)
connectorWhat Spaidoo holds from the last handshake (below)
store.planThe plan the shop uses now: starter · growth · pro. It can be higher than the billed one (a trial or a grant from Spaidoo)
store.statusactive (the shop is listed in Spaidoo's portal) or pending_review. It does not stop the widget
store.verifiedThe domain is proven (§4.9): needed to publish (live)
store.identityOnThe 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.termsAcceptedThe 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.termsVersionThe version of the terms in force (YYYY-MM-DD). A new version turns termsAccepted back to false
store.termsUrlsThe text of the terms, by language (es, en): link it next to the acceptance
store.statsTotals for the panel (below)
store.feedsThe catalogue feeds Spaidoo holds, by language: { language, url, type: "url" | "upload", source?: "plugin" }. source: "plugin" = published by the connector (§4.5)
store.feedHistoryThe 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.catalogSetupHow the shop's first catalogue is going: { state, products? }, see §4.5
store.pluginConfigThe 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:

FieldWhat it counts
savedProductsProducts saved in the shop's lists, now
widgetOpensTimes the widget was opened, ever
historyProductsProducts in the customers' browsing history
catalogueProductsActive products of the catalogue Spaidoo holds
productVisitsVisits 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
alertsSentAlerts (price drop, back in stock, reminders) sent to the shop's customers in the last 30 days
alertClicksAlerts the customer clicked (each alert counts once), last 30 days
followersDeprecated (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:

JSON
"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-section with { 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:

FieldWhat it is
desktop / mobileThe 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)
saveButtonThe 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 / aiProviderThe 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 / actionsAnchorSpaidoo'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
brandDeprecated: 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.

JSON
{
  "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
period7d, 30d, 90d, or custom when asked by from/to
from / toThe 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
totalssaves (products saved), savers (people who saved), widgetOpens, productVisits (visits Spaidoo sent to the shop's products), alertsSent, alertClicks (as in §4.3)
previousThe same totals for the period just before, of the same length
seriesOne row per day of the period, the days without activity included: { date: "YYYY-MM-DD", saves, productVisits }
topProductsThe 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
topViewedThe 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)
updatedAtWhen 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.

JSON
{
  "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
previousSeriesThe previous period day by day, as /stats' series: to draw both periods on top of each other
topProducts / topViewedAs in /stats, up to 10. Every entry with a productId, here and in opportunities.*.products, carries its product card too (§4.3.1)
opportunities.viewedNotSavedProducts 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.priceDroppedSaved products whose price dropped in the period, and people, who have them in their favourites
opportunities.dormantPeople with favourites and no activity in the shop for days days
opportunities.savedNotClickedProducts saved in the period that nobody has opened again since: { productId, savers }
opportunities.revisitedPeople 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.removedThe products most removed from favourites in the period: { total, products: [{ productId, removals }] }
opportunities.topClientsNow, no period: how many people have minSaves products saved or more. Only the number, never who
opportunities.unavailableNow: 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.sharedListsNow: products in shared lists (ListIx), by how many of them hold each: { total, products: [{ productId, lists }] }
reachWho 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
returningPeople who came back to the shop with something saved before: { value, previous }
savedRevisitsSaved products the person looked at again (the product page, more than an hour after saving it); each person and product counts once: { value, previous }
listAddsProducts 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
communicationThe 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')
surfacesSaves 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.

JSON
{
  "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:

JSON
{
  "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
accessfull (Growth, Pro) or teaser (Starter)
period / from / to / timezoneAs in /stats (§4.3.1). On Starter, always 7d
searchesSearches 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
topQueriesThe 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
zeroResultsThose 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
moreHow many distinct queries each list leaves out: { topQueries, zeroResults }
report.totalssearches, zeroResults, filtered (with a filter on), clickedSearches (with at least one click on a result), clicks, views (page views where somebody searched)
report.previousThe same totals for the period just before, of the same length
report.seriesOne row per day of the period, days without searches included: { date, searches, zeroResults, clicks }
report.noClickSearched 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.trendingUp 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.productsThe 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.positionsClicks 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
updatedAtWhen 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).

JSON
{ "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

JSON
{ "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:

FieldRequiredNotes
g:id✅Variant id
g:item_group_idif variantsThe 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_priceSame 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:

stateMeaningWidget shown?
readingSpaidoo is waiting to read the feedNo
importingThe products are coming inNo
failedNo 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/readNo
searchThe catalogue is in (products, how many); search is being preparedYes, without search
emptyThe shop has no products yetYes, without search
readyDone. Also the value for any shop that already had a catalogueYes

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 contain q (2 to 100 characters), in any of the feed's languages, ignoring case and accents (pantalon finds «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.

JSON
{
  "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"
}
FieldWhat it is
idThe 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, urlFrom the feed, in language (or the shop's own)
imageg:image_link; null when the feed has none
price, salePrice, currencyMoney 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
availablefalse when every variant the feed reports is out_of_stock; a product without stock data is available
nextCursorOnly 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

JSON
{
  "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 }
  ]
}
  • id is the product id of the feed (item_group_id, or id without variants).
  • product.updated carries 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, by sku (the g:id of the feed), with amounts in the currency of price. 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).
  • at is 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"). price and salePrice must 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.
  • at in the future is taken as now.
  • 400 CATALOG_CHANGE_CURRENCY_MISMATCH with id (the first change whose price and salePrice are 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_MISSING if the handshake did not declare catalog.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/read after a bulk import.

Response 202 (changes are applied asynchronously, within seconds):

JSON
{ "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.

JSON
{
  "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.

JSON
{ "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: always false, 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. null otherwise. 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:

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. productId is the shop's own id (the feed's); null for 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[].email is asked from the shop at that moment (§6.2): Spaidoo does not keep it. If the shop does not answer, 503 SHOP_EMAILS_UNAVAILABLE and 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

JSON
{
  "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.

JSON
{
  "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 as gid://…/Customer/123 is read as 123). Guests have no id: leave their rows out.
  • The product: productId (the feed's product id), or variantId (a variant's g:id), or handle (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 (like isDefault in §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: true changes nothing and answers what would happen (the preview the connector shows before importing). Then the same rows with dryRun: false.
  • Idempotent like §4.8: running it again only brings what is new.

Response 200:

JSON
{
  "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, lists and products describe what is (or would be) imported: products counted once per customer and list.
  • rejected: every rejected row, by its position in rows (from 0), with its reason: PRODUCT_NOT_FOUND (not in the catalogue Spaidoo holds), PRODUCT_MISSING (no productId, variantId nor handle), 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: false the response also carries result, 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.

JSON
{
  "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 as gid://…/Customer/123 is read as 123). Empty or Guest: 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's g:id, up to 200) or handle (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: true changes nothing and answers the preview; then the same rows with dryRun: false. Idempotent like §4.8.

Response 200:

JSON
{
  "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 with dryRun: false: the same object as §4.8.1.

Errors, in this order:

  • 409 TERMS_NOT_ACCEPTED (§4.13).
  • 409 CONNECTOR_CAPABILITY_MISSING with capability: wishlistImport not accepted; or the file names customers by email and customerLookup was not accepted; or it names them by id and customers was 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 at urls.verify as text/plain, nothing else in the body.
  • urls.verify must be on the domain being proven (or its www.) and must not contain the code. Spaidoo does not follow redirects.
  • POST /domain-verification/check → { "verified": true }. Spaidoo fetched urls.verify and 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 storeUrl declared 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:

CallBody
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-buttonsThe 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-selectorThe 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-cssThe 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/hintsThe 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/state also returns mode). At least one field; 400 NOTHING_TO_CHANGE otherwise.
  • theme is the base of the widget's look: light or dark. The widget derives the rest of the palette from theme and accent.
  • 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 } } }. /status then returns position: "custom" with those offsets (§4.3).
  • Terms first: while the shop has not accepted the version of Spaidoo's terms in force (store.termsAccepted: false in §4.3), every write of this section answers 409 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.

PartSelector
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…

JSON
{ "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.

HTML
<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 other ns or v, and check that event.origin is https://widget.spaidoo.com and event.source the iframe's window. A change that breaks this goes to /preview/v2/.
typeDirectionFieldsWhen
readypreview → panelsizes: { mobile: [360, 640], desktop: [1024, 640] }Once, when it can draw. Without it in a few seconds, show the preview as unavailable
renderpanel → previewrev (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
renderedpreview → panelrevThat render is on screen: show the iframe (keep it hidden until the first)
errorpreview → panelrev, code: BAD_CONFIG (with field) or RENDER_FAILEDThe last good render stays
focuspreview → paneltarget: launcher · save · panel · headerThe 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:

KeyWhat it is
devicemobile or desktop (required)
theme, accent, icon, productCircleRequired, as in POST /widget/appearance. iconColor, satelliteColor, satelliteIconColor: optional, #rrggbb or null
placementRequired: { position, orientation, showButton, top?, right?, bottom?, left? } for that device; a custom position's pixels go here, not in offsets
langThe language the widget speaks
pageproduct (default) or collection: the kind of page drawn behind
panelclosed (default) or open: the list's panel open
saveAnchors, saveButton, headerThe save buttons over the photos and their design, as in POST /widget/save-buttons; header: the header icon
hints, tipThe widget's texts, as in POST /widget/hints; tip: one of their keys, shown as if hovered
search, chatAIThe search's and the assistant's buttons
customCssThe 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
productsUp 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, never 400): a connector published in a marketplace keeps working when Spaidoo renames or retires a page. An intent must 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.

JSON
{
  "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
planstarter · growth · pro. Anything else: 400 BILLING_PLAN_UNKNOWN
intervalmonthly · annual. Absent (or null) for a plan without a price
statusactive · trialing · frozen (the platform suspended the charges: an unpaid platform bill) · cancelled
externalIdThe platform's id of the subscription, or null. Kept for support and reconciliation
currentPeriodEndWhen 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
trialEndsAtWhen the free trial ends, or null
cancelAtPeriodEndThe merchant cancelled: the plan lasts until currentPeriodEnd. Default false
pendingA change that takes effect later (a downgrade at the end of the period): { plan, interval?, effectiveAt }, or null
priceWhat the platform charges, { amount, currency } (§2), or null. Informative: Spaidoo never computes with it
testA test charge (a development shop): the plan is given, it does not count as revenue. Default false
occurredAtWhen 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:

ReportEffect
active / trialingThe shop has plan from now on
pendingNothing changes until effectiveAt; report again then
cancelAtPeriodEnd: trueThe plan lasts until currentPeriodEnd
frozenThe shop uses starter (communication stops, nothing is deleted); a later active gives the plan back
cancelledThe 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 the occurredAt already applied is a retry: accepted, 200. One strictly older answers 409 BILLING_STALE, with the lastEventAt applied. On 409 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 currentPeriodEnd passes by 2 days without a report, Spaidoo's staff are warned; after 7 days the shop moves to starter until 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_MISSING if billing.platform was not accepted at handshake (§4.1).
  • 409 BILLING_STRIPE_ACTIVE while 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 cancelled and 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.

JSON
{
  "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) or internal (granted by Spaidoo, nothing is billed).
  • With provider other than platform: externalId, price, lastEventAt and lastReportAt are null, and manageUrl is the page of Spaidoo's admin (or null for internal). status uses the vocabulary above.
  • lastEventAt: the occurredAt of 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.

JSON
{
  "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"]
    }
  ]
}
FieldWhat it is
currentThe plan the shop uses now: starter · growth · pro (a trial or a grant from Spaidoo can put it above the billed one)
billingWho bills it: stripe (Spaidoo) or platform (§4.12)
plansEvery plan, lowest first
priceSpaidoo's prices in cents, before tax (taxIncluded: false), per month and per year. null when the platform bills: it charges its own prices
featurespostsPerMonth, 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
automationsThe alert types it includes (§4.14)
integrationsThe tools it can connect (the id of §4.19)
reportsThe 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:

JSON
{ "version": "2026-09-10", "acceptedBy": "staff-88120345", "at": 1759560000 }
  • version: the store.termsVersion the merchant was shown (§4.3), with the text at store.termsUrls.
  • acceptedBy: who accepted: the staff member's id in the platform, never an email (400 if 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; at in 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_OUTDATED with currentVersion when version is 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 termsAccepted to true.
  • 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:

JSON
{
  "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:

FieldWhat it is
typeprice_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)
planThe plan that includes it: growth or pro. There are no alerts on starter
settingThe type's number (key: minDropPercent, days or productsCount) with its minimum, maximum and default; null when it has none
productsWhether it can be limited to some products (config.productIds)
linkWhether the alert carries its own link to the shop's website
pushWhether, besides the widget, it also goes out as a push notification (the type decides, not the shop)
multipleWhether 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: on starter, 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 a pro type 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 with multiple: 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:

JSON
{
  "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
}
FieldWhat it is
quotaThe 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)
countsAll the shop's posts, whatever the page: in total, published and drafts
postsA 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
nextCursorThe next page's cursor, with the same filters; null: there is no more
statuspublished or draft. A published post never goes back to draft: it is edited or removed
languages, primaryLanguageThe languages the shop writes in, its own first and required. A reader in a language without a text gets the shop's
contentPer 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)
importanceHow 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)
highlightDaysFor how many days a featured or important post makes itself noticed (1–30, default 7)
reachTimes 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: on starter, 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 (nextAllowedAt says 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:

JSON
{
  "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
}
FieldWhat it is
audiencesThe 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
quotaThe 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
countsAll 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
validUntilUntil 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, primaryLanguageThe languages the shop writes in, its own first and required. A reader in a language without text gets the shop's
statusdraft, scheduled, paused, sending or sent
contentPer 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)
pushWhether, besides the widget's tray, it goes out as a push. Defaults to true
reachCards made in the tray, seen and clicked

GET /notifications/:id/stats → 200: what a notification reached, as in Spaidoo's admin.

JSON
{
  "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 }]
}
FieldWhat it is
createdHow many people it reached: an alert in each one's widget tray
pushedOf them, how many also got it as a push (phone or computer)
shown, read, clickedHow many saw it in the tray, opened it, and went to its link
period, seriesIts 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: on starter, 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 in audiences, no text in the shop's language, or a past sendAt.
  • 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:

JSON
{
  "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
    }
  ]
}
FieldWhat it is
kindmanual (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
productIdsmanual 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)
nameThe shop's own name for it (up to 200), never shown to customers
maxVisibleHow many products it shows, 1 to 50
minProductsWith 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
titleThe 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
lookformat slider (a row, with arrows) or grid; template card (photo, name and price) or circle (the photo alone, round); showTitle
locationWhere 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
reachTimes 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: a manual one without products, productIds on a kind that picks them itself, a shown title without the shop's own language, or a location with neither anchor nor cssSelectors.
  • 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:

JSON
{
  "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
}
FieldWhat it is
itemsNewest first, limit a page (1–100, default 50)
eventIdThe event's id, a UUID: the same event_id the tools received
eventproduct_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
createdAtWhen it happened. This log uses ISO 8601 dates (UTC), not Unix seconds: createdAt, next, before, from and to alike
identifiedFor what a visitor did: whether they were signed in
recipientsFor price_drop, back_in_stock and saved_reminder: how many people it concerns; null for the rest
propertiesWhat 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
testtrue for the sample sent by POST /integrations/:provider/test
productIdSpaidoo'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
deliveriesOne 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
nextWhen the page is full, the before of the next one (its last row's createdAt); null: no more
totalHow 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:

JSON
{
  "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": []
}
FieldWhat it is
tierThe plan the shop uses now
providersThe tools the shop can connect. Draw the panel from here: Spaidoo adds tools without the connector changing
idStable, ^[a-z0-9_-]+$: the :provider of the routes below
brandcolor (#rrggbb) and logo, an SVG drawn for that colour
authoauth2 (the merchant signs in at the tool, in a window), secret (Spaidoo issues a signing secret, a webhook) or none
layerserver (Spaidoo sends the events) or browser (the widget hands them to the tool the shop already loads on its pages)
minTierThe plan it needs
eventsThe events it gets, all of them once connected (§4.18)
configFieldsWhat 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
integrationThe 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
upcomingTools 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"? } to window.opener and closes. Accept it only when event.origin is https://admin.spaidoo.com; and as some tools cut window.opener, also read GET /integrations again every few seconds while the window is open. reason: denied, invalid_state, provider_error, not_configured, token_exchange_failed, internal.
  • secret and none: 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 another config keeps 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_PLAN with requiredTier: connecting, changing or testing a tool above the shop's plan. A plan error, not a dead key (§2): offer the plans (§4.12, or POST /sso with billing). 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 that id. 404 INTEGRATION_NOT_CONNECTED: changing, disconnecting, testing or reading the options of a tool that is not connected (or is revoked).
  • 400 INTEGRATION_CONFIG_INVALID: the config does not fit configFields (a required field missing, a URL that does not lead to a public address…), or a field with no options to read; message says which.
  • 409 INTEGRATION_TEST_UNSUPPORTED: a browser tool: 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>
ParameterWhat it is
hostmodule: the panel talks to the parent page with postMessage. hosted is reserved
platformA free label (the platform of §4.1). Shown as text only, never branched on
langThe admin user's language; the panel falls back to en
originThe 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", no sandbox (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.origin is the panel origin it configured and whose event.source is the iframe's contentWindow.

4.20.2 Messages and handshake

Every message is a plain object:

JSON
{ "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.

  1. 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.
  2. Host → panel: { "type": "welcome", "id", "nonce", "info" }. nonce is random per page load; every later message of the panel carries it.
JSON
{
  "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 }
}
  • lang is 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).
  • capabilities says 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> in acceptedBy (§4.13).

4.20.3 API requests: the host's proxy

Panel → host:

JSON
{ "type": "request", "id": "…", "nonce": "…", "method": "GET", "path": "/stats", "query": { "period": "30d" }, "body": null }

Host → panel:

JSON
{ "type": "response", "id": "…", "status": 200, "body": { "period": "30d" } }
  • path is relative to /connector/v1. The host's server sends the request to Spaidoo with Authorization: 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:
RoutesMethods
/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-selectorPOST
/automations, /posts, /notifications, /carouselsGET, 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/readPOST
/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/image carries the same JSON body as the route (§4.15).
  • GET /status: the host removes identitySecret (and any other secret field) from the body before answering the panel, and stores and acknowledges it itself (§4.2).
  • POST /wishlists/import/file with customers by email needs customerLookup (§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.

nameargs → dataWhat 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 set document.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 the welcome and on scroll, on window resize and after each resize, only when it changes and never with a height of 0. 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_FORBIDDEN otherwise) 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>

AnswerWhen
200 { "assertion": "<assertion>" }A customer is signed in
200 { "anonymous": true }Nobody is signed in (guests count as nobody)
410The 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 + "." + signature

JSON:

JSON
{ "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.
  • jti is single use.
  • anonId echoes ?anon= if it is a UUID, else null.
  • email MUST 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:

HeaderValue
X-Spaidoo-TimestampUnix seconds
X-Spaidoo-Nonce32 random hex chars
X-Spaidoo-Signaturebase64url( HMAC-SHA256( identity secret, timestamp + "." + nonce + "." + rawBody ) )

The connector MUST:

  1. reject a timestamp more than 300 s away from its clock (401);
  2. compare the signature in constant time over the raw body (401);
  3. SHOULD remember nonces for 600 s and reject a repeated one (401).

6.2 POST <urls.customers> — customers

JSON
{ "customerIds": ["123", "124"] }

Up to 500 ids. Answer 200:

JSON
{ "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: true the customer is subscribed to the shop's marketing emails (newsletter opt-in), false they are not, null the platform does not know. It is true exactly when marketingState is "subscribed".
  • marketingState: "subscribed", "not_subscribed", "unsubscribed", "pending" or null. "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, or null if the platform does not know.
  • marketingState and marketingUpdatedAt are optional, so that connectors written before them keep working; Spaidoo takes a missing one as null.
  • 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. 410 if 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:

JSON
{ "emails": ["ana@example.com", "joan@example.com"] }

Up to 500 emails, same route and signature as §6.2. Answer 200:

JSON
{ "customers": [ { "customerId": "123", "email": "ana@example.com" } ] }
  • Compare emails without case. Leave out the emails the shop has no customer with, and guests.
  • marketingConsent may 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. 410 if 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:

JSON
{ "customerId": "123", "textVersion": "shop-marketing-save-v1", "consentedAt": "2026-10-07T10:00:00Z" }
  • textVersion identifies 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:

JSON
{ "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):

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

KeyValue
currencyISO code of the currency the visitor is browsing in. The widget shows prices in it (from spaidoo:price)
shopSessionSession 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
themeIdThe 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
previewtrue 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.

HTML
<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.

HTML
<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 are home, product (product page) and collection (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) or data-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 instance style="--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 with data-spaidoo-filled or data-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.js with pushScope /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 not importScripts it from another origin).
  • It receives data-only messages { title, body, link, seen, icon, image, badge, shopId }. link goes through Spaidoo's tracking, which counts the click and the read and leads to the shop. seen is 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.merchantIdThe 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.searchHeadertrue 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-readyA 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-closeOn window, each time the list's panel opens or closes. No detail
spaidoo:show-sectionSent 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

DateChange
2026-09-30First draft
2026-09-30Pairing 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-01Client secret for hosted apps and provisioning: the connector's server signs the shop up itself (§3.1, §3.4)
2026-10-04Plan 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-05Save 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-06Automatic 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-07The 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-08The 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-08minProducts 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-09Figures 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-09Automatic 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-13The 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-15The 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-15Integration 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-15The 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-15The 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-15Spaidoo Panel for connectors: embedding, the bridge's messages, the host's proxy and its allowlist, platform actions and security (§4.20)
2026-10-19Provisioning: 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-19Security: 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-19Every 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 » page (§4.11)
2026-10-19409 SHOP_LINK_UNAVAILABLE when no link email can go; /pairing/provision/complete takes its token once (§3.4)
2026-11-06The contacts download on every plan: contactsLocked always false and features.contactsExport always true (§4.7.2, §4.12.1)
2026-11-06Spaidoo'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-07Opening 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-06The 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-08What 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-08POST /widget/search takes search: the search on or off, apart from its button on the floating launcher (§4.10)
2026-11-09GET /search-analytics/find: one list of the report with a text, on Growth and Pro (§4.3.3)