← Back to shop settings

Kubiq Connect — Integration guide

REST API or HTML snippet: integrate shop, appointment booking, and Google reviews on WordPress, Django, React, etc. Stripe checkout stays on Kubiq.

Quick start

Two paths depending on your site. No environment variables required in production.

WordPress / HTML

  1. Shop settings → Kubiq Connect: register your production URL.
  2. Copy the "Product grid" snippet into a custom HTML block.
  3. embed.js automatically loads your products based on the domain.

REST API / custom site

  1. Register your production URL in Kubiq Connect.
  2. Call GET /api/kubiq-connect/public/by-site?host=… from your server (Django, Node, PHP…).
  3. Render products[] with your UI (templates, React, Vue…). Payment: POST checkout-mint.

.env variables (NEXT_PUBLIC_KUBIQ_CONNECT_SHOP_ID): optional, only to simplify local dev.

Visual journey

Two integrations. Kohi Store shows API + React — the same API works with Django or any stack.

WWordPress / HTML

embed.js snippet — design via .kubiq-connect-* CSS

1

Register domain

Shop settings → Kubiq Connect → production URL.

2

Paste snippet

Custom HTML block on your shop page.

<div data-kubiq-host="…"> + embed.js
3

Customize design

Theme CSS targeting .kubiq-connect-* classes from embed.js.

APIREST API — custom site

JSON + your UI (React, Django templates, Vue, etc.) — no embed.js

1

Register domain

Shop settings → Kubiq Connect → production URL. No .env in production.

2

Catalog API (server)

Your server calls Kubiq by domain and receives shop + products as JSON.

3

Your interface

Grid, product pages, buttons — any frontend or server templates.

React (Kohi Store), Django templates, Vue, PHP…
4

Local cart

Cart on client (localStorage) or server session — your logic.

5

Stripe checkout

POST checkout-mint → Stripe redirect → confirmation page on your domain.

6

Order tracking

Guest refs stored on your side → Kubiq API for tracking.

Code examples

Same REST API for every stack. Kohi Store is a React example; Django below too.

React / Next.js (Kohi Store)

Python / Django
Customization: your CSS/components for design; product content (name, price, options) in Kubiq Shop admin.
  • Grid & cards: KubiqProductCard.tsx (Tailwind, Kohi typography)
  • Options & add to cart: KohiProductPurchase.tsx + KohiProductOptions.tsx
  • Product content: managed in Kubiq Shop admin — synced via API
View live demo →
Overview
Kubiq Connect separates catalog (your site) and payment (Stripe via Kubiq). You control design; Kubiq handles products, orders and Stripe Connect.
  1. Visitors browse products on your site (grid, product pages, your CSS).
  2. Cart is local on your site (localStorage or your backend).
  3. On pay: POST checkout-mint → direct redirect to Stripe (pay.kubiq.app).
  4. After payment: return to your confirmation page; order appears in Kubiq.
Setup
From Shop settings → Kubiq Connect:
  • Register your production URL (public domain) — required for all sites.
  • WordPress: HTML snippet. REST API: call by-site from your backend.
  • Local dev (optional): localhost URL in Kubiq, or "Connect with Kubiq" button on the site.
Shop must be active and Stripe Connect configured before first payment.
WordPress
Paste the snippet in a custom HTML block. embed.js loads the grid via data-kubiq-host or data-kubiq-shop.
<div id="kubiq-connect-shop" data-kubiq-host="www.mysite.com"></div>
<script src="https://kubiq.net/kubiq-connect/embed.js" async></script>
Customize your theme CSS targeting .kubiq-connect-* classes from embed.js.
API integration (language-agnostic)
Unauthenticated REST endpoints (open CORS). Callable from any language.
GET /api/kubiq-connect/public/by-site?host=...
GET /api/kubiq-connect/public/{pageId}/catalog
POST /api/kubiq-connect/checkout-mint
Typical flow:
  • Catalog: GET by-site?host= or GET /{shopId}/catalog
  • Display: your HTML/templates/components (not embed.js)
  • Cart: on your side (session, localStorage, database…)
  • Payment: POST checkout-mint → checkoutUrl (Stripe)
Public API
Unauthenticated endpoints (open CORS):
GET /api/kubiq-connect/public/by-site?host=...
GET /api/kubiq-connect/public/{pageId}/catalog
POST /api/kubiq-connect/checkout-mint
checkout-mint requires successUrl and cancelUrl on a host linked to the shop. Response: checkoutUrl (Stripe session).
Cart & checkout
Recommended flow:
  1. Store line items client-side (productId, qty, display price).
  2. Show cart count in header (custom event on cart update).
  3. POST checkout-mint with prefill, successUrl, cancelUrl.
  4. window.location.href = checkoutUrl — customer pays on Stripe then returns to your site.
Firestore orders are only confirmed after Stripe payment (webhook).
Free design
You control:
  • Product grid, typography, add-to-cart animations.
  • Product page layout (images, description, CTAs).
  • Cart page and order confirmation page.
  • Colors — Kubiq shop colors in API are optional.
Appointment widget
When online booking is enabled, paste the “Book appointment” snippet (same embed.js as the shop). The widget shows party size, next availability, times, then the booking form.
Custom site: GET /booking (settings + next dates), GET /slots?date=YYYY-MM-DD, POST /book with name, email, and slot. CORS is open.
Booking endpoints
GET /api/kubiq-connect/public/by-site?host=...
GET /api/kubiq-connect/public/{pageId}/catalog
POST /api/kubiq-connect/checkout-mint
Google reviews widget
Google reviews only render if they have already been synced and at least one remains (after the minimum-rating filter). Otherwise the block stays empty — no placeholder. Organization pages work too, not only shops.
API: GET /reviews?minRating=4&limit=8 → { available, reviews, averageRating, totalReviewCount, minRating, mapsUrl }. Effective minRating is max(page setting, query). Header stars stay Google’s official rating; quoted comments respect the floor (e.g. 4★). available=false when 0 reviews remain after the filter.
Snippet attrs: data-min-rating="4" (optional, cannot go below the page setting), data-theme="dark" on photo backgrounds, data-title for the heading, data-limit for card count.
Reviews endpoint
GET /api/kubiq-connect/public/by-site?host=...
GET /api/kubiq-connect/public/{pageId}/catalog
POST /api/kubiq-connect/checkout-mint