# Use cases voor een commerce-API: zeven bouwprojecten die met een widget niet kunnen

> Wanneer een storefront-widget niet de juiste vorm heeft: embedded commerce in SaaS, catalogi over meerdere oppervlakken, white-label shops, eigen UX, AI-agents en eigen BI. Plus codevoorbeelden uit de Shoprocket JS SDK.

Ryan Badger - 4 augustus 2025 - 5 min leestijd

## Waar een e-commerce-API voor inbedden voor dient

De meeste e-commerceplatforms geven je een widget. Plak een script, krijg een storefront. Werkt prima voor 95% van de shops.

Een commerce-API pak je erbij als je iets wilt wat een widget niet kan: producten renderen binnen je eigen UI, checkout inbedden in een SaaS-dashboard, een catalogus verspreiden over meerdere oppervlakken (web + mobiel + spraak) of eigen koopflows bouwen die geen enkel platform kant-en-klaar levert.

Shoprocket levert beide. De [widget](https://v3.shoprocket.io/nl/blog/headless-commerce-drie-niveaus-welke-past-bij-jou.md) is de standaard. De [`@shoprocket/core` SDK](https://github.com/shoprocket/shoprocket-js) is voor als je de widget ontgroeit of er nooit een nodig had.

## Use cases die een API vragen, geen widget

Dit zijn de projecten waar een widget niet genoeg is. Staat jouw idee in deze lijst, dan zit je in API-gebied.

### 1. Commerce binnen je SaaS-product

Je SaaS-dashboard heeft al een eigen UI. Je wilt dat klanten add-ons, creditpakketten, premiumniveaus of fysieke merchandise kunnen kopen zonder je app te verlaten.

Een widget zou de verkeerde vorm zijn: die kent je gebruikers niet, past niet bij je designsysteem en gaat uit van een storefront over de hele pagina. Met de API render je productkaarten met je eigen componenten, roep je `cart.addItem()` aan bij een klik op een knop en open je je eigen checkoutpaneel (of stuur je door naar een gehoste checkout als je het compliancewerk wilt uitstellen).

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// Render add-on-tegels in je SaaS-dashboard
const addons = await sr.products.list({ category: 'addons' })

// Gebruiker klikt op de knop // User clicks "Add credits" buttonquot;Credits toevoegen// User clicks "Add credits" buttonquot;
await sr.cart.addItem(addon.id, 1)
```

### 2. Catalogus over meerdere oppervlakken (web + native app + spraak + chat)

Eén catalogus met producten, op elke plek anders weergegeven. De webstorefront toont de volledige productdetails, de native iOS-app een compacte lijst, de spraakassistent beschrijft artikelen hardop en een chatintegratie antwoordt met een link waarmee je kunt kopen.

Alle vier de oppervlakken roepen dezelfde API aan. Pas je de prijs van een product aan in het Shoprocket-dashboard, dan zie je dat op elk oppervlak bij de volgende ophaalronde. Geen contentsynchronisatie per oppervlak.

### 3. White-label / storefronts voor partners

Je bent een platform waar anderen hun goederen verkopen: een community-marktplaats, een partnerdirectory, een franchisenetwerk met sites van individuele dealers. Elke partner heeft branding die van hem is, niet van jou.

De site van elke partner draait op jouw framework maar roept de commerce-API aan met zijn eigen `publicKey`. Hun producten, hun bestellingen, hun uitbetalingen, allemaal per account afgebakend. Geen widget die hun branding in de weg zit.

### 4. Volledig eigen koopervaring

Interactieve productconfigurators (pc's op maat, gepersonaliseerde sieraden, meubels op bestelling). 3D-productviewers. Fotogalerijen met "shop de kamer" waarin je door op pixels in een afbeelding te klikken het product in de winkelwagen legt. Knoppen voor snel opnieuw bestellen in een e-mail.

De widget kan geen van deze dingen. De API wel. Je rendert de UI die je ontwerper heeft bedacht; de API regelt de commerce erachter.

### 5. AI-agents en agentic commerce

Een AI-agent (ChatGPT, Claude, een eigen agent) die producten kan bekijken en namens de gebruiker aankopen kan afronden. De agent heeft programmatische toegang tot je catalogus en winkelwagen nodig, geen DOM-widget die hij moet ontleden.

Shoprocket levert feeds voor AI-commerceprotocollen naast gewone API-toegang. Een agent die vraagt "wat is er op voorraad onder $50 met gratis verzending" krijgt een gestructureerd antwoord, geen schermschraap.

### 6. Embedded commerce in contenttools

Een Notion-pagina waar blokken koopbaar kunnen zijn. Een Framer-ontwerp met hotspots waarmee je door te klikken koopt. Een nieuwsbrieftool waarin abonnees op een productkaart kunnen tikken en kunnen betalen zonder de e-mail te verlaten. Allemaal gebouwd op een API.

### 7. Eigen rapportages en BI-dashboards

Het Shoprocket-dashboard toont omzet, conversie en topproducten. Wat het niet toont, zijn *jouw* eigen maatstaven: lifetime value per klantcohort, bestellingen per verwijzingsbron, marge na kosten van de leverancier. De API biedt bestel- en klantgegevens zodat je ze kunt doorsturen naar je eigen BI-tool, spreadsheet of interne dashboard.

## Wat de SDK je vandaag geeft

Uit `@shoprocket/core`:

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

Plus de volledige REST API voor alles wat de SDK nog niet omvat (bestellingen, klanten, kortingen, producten schrijven). Zie [api.shoprocket.io/docs](https://api.shoprocket.io/docs) voor de complete referentie.

## Waar API-first een vergissing is

Een paar gevallen waarin de widget de juiste keuze is en de API overkill:

- **Een eenvoudige storefront met 10-200 producten.** De widget rendert dit perfect; zelf een catalogus-UI schrijven is opnieuw doen wat al is opgelost.
- **Je hebt geen eigen capaciteit voor frontend-engineering.** API-first betekent dat je zelf laadstatussen, variant-UI, foutafhandeling, toegankelijkheid en i18n voor 21 talen moet opleveren en onderhouden. Dat zijn weken werk die de widget je gratis geeft.
- **Je belangrijkste zorg is snelheid van lanceren.** De widget kost minuten; API-first minimaal weken.

Ga uit van de widget. Pak de API erbij als je iets tegenkomt wat de widget niet kan.

## Een realistisch eerste project

Het meest voorkomende "ik heb de API nodig"-project: een SaaS-product dat credits, abonnementen of eenmalige add-ons wil verkopen in zijn eigen dashboard.

Aanpak:

1. Installeer `@shoprocket/core` in je frontend
2. Maak in Shoprocket een categorie "Add-ons" of iets dergelijks
3. Voeg producten toe met precies de prijs en beschrijving die je wilt
4. Render de productlijst in je dashboard met je eigen componentenbibliotheek
5. Bij een klik: in de winkelwagen leggen + doorsturen naar de gehoste checkout van Shoprocket (of de checkout inline inbedden als je het extra werk aandurft)
6. Configureer een webhook-endpoint om `order.paid`-events te ontvangen, zodat je kunt leveren wat de aankoop ontgrendelt (credits, toegang, zending)

Meer is het niet. Een handvol bestanden, een dag werk voor iemand die gewend is API's aan te roepen. Geen widget, geen iframe, geen concessie aan de UI van je product.

## Wat we niet aanraden

Bouw geen volledige catalogus-UI na die sterk lijkt op wat de widget al doet. Als je weken bezig bent met "productraster met filters en zoeken", schrijf je wat de widget in minuten levert. Gebruik de widget voor die vorm en de API voor de echt andere vormen.

> **Tip:** Overweeg je API-first omdat de standaardstijl van de widget niet bij je merk past? Probeer dan eerst de [stylinghaken van de widget](https://github.com/shoprocket/shoprocket-js). De widget accepteert veel meer CSS-aanpassing dan het lijkt. Alles met de API herbouwen is een veel zwaardere klus.

## TL;DR

- **Widget** = standaard, dekt 95% van de shops
- **API / SDK** = als de widget niet de juiste vorm heeft (embedded commerce in SaaS, meerdere oppervlakken, white-label, eigen UX, AI-agents, eigen BI)
- **De SDK van vandaag:** producten, winkelwagen, sessies; plus de volledige REST API voor bestellingen / klanten / kortingen
- **Patroon voor een eerste project:** een SaaS-dashboard dat credits of add-ons verkoopt via de SDK + levering aangedreven door webhooks
- **Bouw niet met de API opnieuw** wat de widget al goed doet; kies je vorm

[Start een gratis proefperiode](https://app-v3.shoprocket.io/signup) en pak een publieke sleutel; de SDK is gratis te gebruiken bij elk Shoprocket-abonnement. 14 dagen, geen kaart nodig.

---

- HTML version: https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget
- Language: Nederlands (nl)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [日本語](https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)