HTTP API

1https://app.ekoo.co

1GET /ws/websites/{websiteId}/products/{productRef}

1curl -s "https://app.ekoo.co/ws/websites/{websiteId}/products/{productRef}?locale=en&variant=homepage"

1// Node.js 18+ / Bun / Deno — global fetch
2const websiteId = process.env.EKOO_WEBSITE_ID!
3const productRef = 'SKU-1234'
4
5const res = await fetch(
6  `https://app.ekoo.co/ws/websites/${websiteId}/products/${productRef}?locale=en&variant=homepage`,
7  { headers: { Accept: 'application/json' } }
8)
9
10if (!res.ok) throw new Error(`Ekoo API ${res.status}`)
11const product = await res.json()

1# Python 3.8+ — requests
2import os, requests
3
4website_id = os.environ["EKOO_WEBSITE_ID"]
5product_ref = "SKU-1234"
6
7res = requests.get(
8    f"https://app.ekoo.co/ws/websites/{website_id}/products/{product_ref}",
9    params={"locale": "en", "variant": "homepage"},
10    timeout=5,
11)
12res.raise_for_status()
13product = res.json()

1{
2  "id": "9b0c2f3e-8e4d-4d9b-9c8a-0f3a6b7e1d22",
3  "external_id": "SKU-1234",
4  "name": "Eau de parfum 50ml",
5  "audio_url": "https://cdn.ekoo.co/audios/...",
6  "website": {
7    "id": "f7c1...",
8    "name": "Acme Cosmetics"
9  },
10  "config": { /* widget config */ },
11  "experiment": { /* optional A/B experiment */ },
12  "reviews": [
13    {
14      "id": "5d2a...",
15      "type": "review",
16      "label": "Marie, 34",
17      "rating": 5,
18      "audio_url": "https://cdn.ekoo.co/audios/abc.mp3",
19      "is_active": true,
20      "is_default": true,
21      "transcript": "I bought this perfume for my wife...",
22      "user": {
23        "id": "u_8f...",
24        "firstname": "Marie",
25        "lastname": "D.",
26        "image_url": "https://cdn.ekoo.co/avatars/marie.jpg"
27      }
28    }
29  ]
30}

1// Drop into your project — fully typed responses
2
3export type EkooReviewType = 'review' | 'testimony'
4
5export interface EkooReviewUser {
6  id: string
7  firstname?: string
8  lastname?: string
9  email?: string
10  image_url?: string
11  description?: string
12}
13
14export interface EkooReview {
15  id: string
16  type: EkooReviewType
17  label?: string
18  rating?: number
19  audio_url?: string
20  is_active: boolean
21  is_default: boolean
22  transcript?: string
23  user: EkooReviewUser
24}
25
26export interface EkooExperimentVariation {
27  id: string
28  name: string
29  widgetEnabled: boolean
30  widgetConfigId: string | null
31  audioSelection: string
32  audioId: string | null
33  audioPosition: number | null
34  audioIdsByLocale?: Record<string, string>
35  allocation: number
36  position: number
37  config?: unknown
38}
39
40export interface EkooExperiment {
41  id: string
42  name: string
43  variations: EkooExperimentVariation[]
44}
45
46export interface EkooProduct {
47  id: string
48  external_id: string
49  name?: string
50  audio_url?: string
51  website: { id: string; name?: string }
52  config?: Record<string, unknown>
53  experiment?: EkooExperiment
54  reviews: EkooReview[]
55}
56
57export interface EkooProductList {
58  limit: number
59  offset: number
60  count_item: number
61  items: EkooProduct[]
62}

1GET /ws/websites/{websiteId}/products

1curl -s "https://app.ekoo.co/ws/websites/{websiteId}/products?limit=50&offset=0"

1{
2  "limit": 50,
3  "offset": 0,
4  "count_item": 124,
5  "items": [
6    { /* same shape as single product */ }
7  ]
8}

1// app/products/[ref]/page.tsx — Next.js App Router (Server Component)
2import { notFound } from 'next/navigation'
3import type { EkooProduct } from '@/lib/ekoo-types'
4
5async function fetchEkooProduct(ref: string, locale: string) {
6  const url = `https://app.ekoo.co/ws/websites/${process.env.EKOO_WEBSITE_ID}/products/${ref}?locale=${locale}&variant=homepage`
7  const res = await fetch(url, { next: { revalidate: 300 } })
8  if (!res.ok) return null
9  return (await res.json()) as EkooProduct
10}
11
12export default async function ProductPage({
13  params
14}: { params: Promise<{ ref: string }> }) {
15  const { ref } = await params
16  const product = await fetchEkooProduct(ref, 'en')
17  if (!product) notFound()
18
19  const primary = product.reviews.find((r) => r.is_default && r.is_active)
20
21  return (
22    <article>
23      {primary?.transcript && (
24        <section aria-label="Audio review transcript">
25          <h2>What our customers say</h2>
26          <blockquote>{primary.transcript}</blockquote>
27          <cite>{primary.user.firstname} {primary.user.lastname}</cite>
28        </section>
29      )}
30
31      {/* Ekoo widget hydrates client-side and takes over */}
32      <ekoo-widget
33        data-ekoo={process.env.EKOO_WEBSITE_ID}
34        data-ekoo-product-id={ref}
35        data-ekoo-locale="en"
36        data-ekoo-variant="homepage"
37      />
38    </article>
39  )
40}

1{
2  "type": "ERR_NOT_FOUND",
3  "message": "Product not found"
4}