Custom / headless store integration

If you don’t run Shopify or WooCommerce — a headless storefront, a bespoke stack, or a platform we don’t natively connect — you can still run Zubby. Instead of a sync connector, you push your catalog and orders to Zubby over the public REST API. They land in the exact same tables Shopify and WooCommerce sync into, so every AI tool (search, recommendations, order status, reorder) works identically.

1. Create a custom store

From onboarding choose Custom / API (the third option beside Shopify and WooCommerce). Enter your storefront URL — it’s used for links and the widget origin allow-list. Unlike the platform connectors there’s no OAuth or plugin handshake, so the workspace activates immediately and you land on a setup guide with your store ID.

2. Mint a write API key

Open Settings → API Keys and create a key with the write scope (catalog + order ingest need write; the read endpoints below need read). The secret is shown once — store it in a secret manager, never commit it.

Every request authenticates with a Bearer token:

Authorization: Bearer sp_live_<prefix>.<secret>

The store is derived from the key — there is no separate store-ID header on the public API.

3. Push your catalog

POST products (each with its variants) to /api/public/v1/catalog. The call is idempotent on your own externalId — re-send the same product to update it in place. Up to 200 products per request. Products become AI-searchable within seconds once the embedding worker processes them.

curl -X POST https://api.zubbyai.com/api/public/v1/catalog \
  -H "Authorization: Bearer sp_live_<prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "externalId": "SKU-1",
        "title": "Waxed Field Jacket",
        "description": "Waxed cotton, charcoal, brass hardware.",
        "vendor": "Northbound",
        "productType": "Outerwear",
        "status": "active",
        "url": "https://shop.yourbrand.com/p/field-jacket",
        "imageUrl": "https://cdn.yourbrand.com/jacket.jpg",
        "tags": ["jackets", "waxed-cotton"],
        "variants": [
          {
            "externalId": "SKU-1-M",
            "title": "Medium",
            "sku": "FJ-CHAR-M",
            "price": 189.00,
            "compareAtPrice": 220.00,
            "inventory": 12,
            "requiresShipping": true,
            "imageUrl": "https://cdn.yourbrand.com/jacket-m.jpg"
          }
        ]
      }
    ]
  }'

Response:

{ "upserted": 1, "received": 1, "errors": [] }

Only externalId and title are required on a product; only externalId, title, and price on a variant. A product with no variants is allowed but won’t be purchasable through checkout tools. Money fields accept a number or a string.

4. Push orders (optional)

POST orders to /api/public/v1/orders so the agent’s order status and reorder tools work for your shoppers. Idempotent on externalId; re-push to update financial/fulfillment status (line items are replaced on each push). The original orderedAt is preserved across re-syncs.

curl -X POST https://api.zubbyai.com/api/public/v1/orders \
  -H "Authorization: Bearer sp_live_<prefix>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "externalId": "1001",
        "email": "shopper@example.com",
        "currency": "USD",
        "subtotal": 189.00,
        "total": 199.00,
        "financialStatus": "paid",
        "fulfillmentStatus": "unfulfilled",
        "shippingCountry": "US",
        "shippingZip": "97201",
        "orderedAt": "2026-06-16T12:00:00Z",
        "items": [
          {
            "title": "Waxed Field Jacket",
            "platformProductId": "SKU-1",
            "platformVariantId": "SKU-1-M",
            "quantity": 1,
            "unitPrice": 189.00,
            "lineTotal": 189.00
          }
        ]
      }
    ]
  }'

5. Embed the widget

Drop the zubby-widget web component on every storefront page. The store ID is on your setup guide; mint a widget key from Settings → API Keys (the widget key is origin-bound and safe to ship to the browser — unlike the write key above).

<script src="https://app.zubbyai.com/widget-element.js" defer></script>
<zubby-widget
  store-id="YOUR_STORE_ID"
  widget-key="YOUR_WIDGET_KEY"
></zubby-widget>

See widget embed codes for framework-specific variants (React, Vue, Next.js) and SPA boot notes.

Checkout links on custom stores

Shopify and WooCommerce have cart-permalink protocols, so the agent can build a one-tap checkout URL. Custom stores have no universal add-to-cart protocol, so the inline-checkout and reorder tools link the shopper to the product page you provided in url (falling back to your store root). Always send a real product url so those links land somewhere useful.

Reading data back out

Two read endpoints (a key with the read scope) let you mirror Zubby data into your CDP or warehouse. Both are cursor-paginated — pass the next_cursor from the previous response.

See the REST API reference for the full request/response shape, rate limits, and error format.

Keeping data fresh

• On change — push a product whenever its price, inventory, or copy changes, and an order whenever its status changes. Single-item pushes are cheap.
• Nightly full sync — re-push your whole catalog (in batches of ≤200) once a day as a backstop. Idempotency makes this safe and free of duplicates.
• Worker dependency — products only become searchable once the embedding worker processes them. If a freshly pushed product never appears in search, see embedding worker / DLQ.

Errors

A malformed body returns 400 with a details field from validation. A missing or wrong scope returns 401/403. When some items in a batch fail but others succeed, you get 200 with the failures listed in errors; when every item fails you get 422. Always inspect errors even on a 200.

Adjacent

• REST API reference — auth, pagination, rate limits, errors.
• API keys — minting read vs. write keys and revoking them.
• Widget embed codes — every snippet variant.