Commerce API use cases: seven builds you can't do with a widget

What an ecommerce API for embedding is for

Most ecommerce platforms give you a widget. Paste a script, get a storefront. Works fine for 95% of stores.

A commerce API is what you reach for when you want to do something a widget doesn't: render products inside your own UI, embed checkout inside a SaaS dashboard, distribute a catalogue across multiple surfaces (web + mobile + voice), or build custom buyer flows that no platform ships out of the box.

Shoprocket ships both. The widget is the default. The @shoprocket/core SDK is when you outgrow the widget or never needed one in the first place.

Use cases that require an API, not a widget

These are the builds where a widget isn't enough. If your idea is in this list, you're in API territory.

1. Commerce inside your SaaS product

Your SaaS dashboard already has its own UI. You want customers to buy add-ons, credit packs, premium tiers, or physical merch without leaving your app.

A widget would be the wrong shape: it doesn't know about your users, doesn't match your design system, and assumes a full-page storefront. The API lets you render product cards with your own components, call cart.addItem() on button click, and pop up your own checkout panel (or redirect to a hosted checkout if you want to defer the compliance work).

import { ShoprocketCore } from '@shoprocket/core'

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

// Render add-on tiles inside your SaaS dashboard
const addons = await sr.products.list({ category: 'addons' })

// User clicks "Add credits" button
await sr.cart.addItem(addon.id, 1)

2. Multi-surface catalogue (web + native app + voice + chat)

One catalogue of products, rendered differently in each place. Web storefront shows full product detail, native iOS app shows a compact list, voice assistant describes items aloud, a chat integration replies with a buyable link.

All four surfaces call the same API. When you update a product's price in the Shoprocket dashboard, every surface reflects it on the next fetch. No per-surface content sync.

3. White-label / partner storefronts

You're a platform where other people sell their goods: a community marketplace, a partner directory, a franchise network with individual dealer sites. Each partner has branding that's theirs, not yours.

Each partner's site runs your framework but calls into the commerce API with their publicKey. Their products, their orders, their payouts, all scoped by account. No widget gets in the way of their branding.

4. Completely custom buyer UX

Interactive product configurators (custom PC builds, personalised jewellery, made-to-order furniture). 3D product viewers. "Shop the room" photo galleries where clicking on pixels in an image adds the product to cart. Quick-reorder buttons inside email.

The widget can't do any of these. The API can. You render whatever UI your designer dreamed up; the API handles the commerce mechanics behind it.

5. AI agents and agentic commerce

An AI agent (ChatGPT, Claude, a custom agent) that can browse products and complete purchases on behalf of the user. The agent needs programmatic access to your catalogue and cart, not a DOM widget it has to parse.

Shoprocket ships feeds for AI commerce protocols alongside standard API access. An agent asked "what's in stock under $50 with free shipping" gets a structured answer, not a screen scrape.

6. Embedded commerce in content tools

A Notion page where blocks can be buyable. A Framer design with click-to-purchase hotspots. A newsletter tool where subscribers can tap a product card and pay without leaving the email. All built on top of an API.

7. Custom reporting and BI dashboards

The Shoprocket dashboard shows revenue, conversion, top products. What it doesn't show is your custom metrics: lifetime-value by customer cohort, orders per referral source, margin after supplier cost. The API exposes order and customer data so you can pipe it into your own BI tool, spreadsheet, or internal dashboard.

What the SDK gives you today

From @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 the full REST API for anything the SDK doesn't wrap yet (orders, customers, discounts, products-write). See api.shoprocket.io/docs for the complete reference.

Where API-first is a mistake

A few cases where the widget is the right choice and the API is overkill:

• A simple storefront with 10-200 products. The widget renders this perfectly; writing your own catalogue UI is re-doing solved work.
• You don't have dedicated frontend engineering capacity. API-first requires shipping and maintaining your own loading states, variant UI, error handling, accessibility, i18n across 21 locales. That's weeks of work the widget gives you free.
• Your primary concern is launch speed. The widget is minutes; API-first is weeks minimum.

Default to the widget. Reach for the API when you hit something the widget can't do.

A realistic first project

The most common "I need the API" project: a SaaS product that wants to sell credits, subscriptions, or one-off add-ons inside its own dashboard.

Approach:

1. Install @shoprocket/core in your frontend
2. Create a category in Shoprocket called "Add-ons" or similar
3. Add products with the exact pricing / description you want
4. Render the product list in your dashboard using your own component library
5. On click, add to cart + redirect to Shoprocket's hosted checkout (or embed the checkout inline if you're comfortable with the additional work)
6. Configure a webhook endpoint to receive order.paid events so you can provision whatever the purchase unlocks (credits, access, shipment)

That's it. A handful of files, a day of work for someone who's used to calling APIs. No widget, no iframe, no compromise on your product's UI.

What we don't recommend

Don't rebuild a full catalogue UI that closely resembles what the widget already does. If you're spending weeks on "products grid with filters and search", you're writing what the widget ships in minutes. Use the widget for that shape, use the API for the genuinely different shapes.

Tip: If you're thinking about going API-first because the widget's default styling doesn't match your brand, try the widget's styling hooks first. The widget accepts a lot more CSS customisation than it looks. Full API rebuild is a much heavier lift.

TL;DR

• Widget = default, covers 95% of stores
• API / SDK = when the widget isn't the right shape (SaaS embedded commerce, multi-surface, white-label, custom UX, AI agents, custom BI)
• Today's SDK surface: products, cart, sessions; plus full REST API for orders / customers / discounts
• First project pattern: SaaS dashboard selling credits or add-ons via SDK + webhook-driven provisioning
• Don't API-rebuild what the widget already does well; pick your shape

Start a free trial and grab a public key; the SDK is free to use on any Shoprocket plan. 14 days, no card.