BusinessPlus Connect (Developer)

Storefront Integration Models & Quick Start

Choose the optimal integration model for your business: Embed the interactive BusinessPlus storefront widget into an existing site, or build a bespoke headless frontend powered by high-speed REST APIs.

Two Storefront Integration Models

BusinessPlus provides two production-tested integration models designed for different technical requirements. Neither model is universally superior; each solves a distinct engineering need.

Model A: Store Embed (No-Code / Low-Code Embed): For businesses that already have a content website (WordPress, Webflow, Shopify blog, static HTML, or custom portal) and want to add an interactive commerce catalogue, intelligent assistant, shopping cart, and checkout without developing a custom frontend from scratch. Developers copy a generated script tag into their site, and BusinessPlus handles catalogue discovery, customer cart, and checkout ordering natively.
Model B: Headless Storefront (Fully Custom Frontend): For developers creating a custom shopping experience in modern frontend frameworks (Next.js, React, Vue, Nuxt, Svelte, or native mobile applications). In this architecture, your custom frontend owns 100% of the customer user interface and styling, while BusinessPlus functions as the headless commerce engine managing product catalogues, server-authoritative inventory, orders, payments, CRM leads, and multi-channel messaging.

Core Architectural Principle

The guiding architectural principle of the BusinessPlus headless engine is simple and strict: BusinessPlus owns commerce state. The custom frontend owns customer experience.

Architecture Diagram

Storefront interactions follow a strict trust boundary separating public edge-cached queries from privileged server operations:

Endpoint Security Classification

Every BusinessPlus endpoint falls strictly into one of two tiers. Developers must never mix the two:

Public Storefront Reads (No API Key Required): Endpoints under /v1/storefront/* (such as /v1/storefront/catalog-items and /v1/storefront/product) are public, high-speed, edge-cached GET routes. They can be safely called from browser JavaScript, edge workers, or Static Site Generation (SSG) pipelines without any credentials.
Server-Authenticated Operations (Requires Secret x-api-key): Endpoints such as POST /v1/orders, GET /v1/orders/:id, and POST /v1/lead-capture require your secret Site API Key. These endpoints must NEVER be called directly from browser JavaScript.

Configuring Hosting Platform Environment Variables

When deploying your custom storefront to modern cloud hosting platforms, you MUST configure your environment variables in your hosting provider settings before building production:

Vercel: Navigate to your Project -> Settings -> Environment Variables. Add BUSINESSPLUS_API_KEY (mark as Secret/Production), and public variables NEXT_PUBLIC_BUSINESSPLUS_IDENTIFIER and NEXT_PUBLIC_BUSINESSPLUS_SITE_ID.
Netlify: Navigate to Site configuration -> Environment variables. Add BUSINESSPLUS_API_KEY as a Server-only variable, plus your public store identifier.
Cloudflare Pages / AWS Amplify / Render: Define BUSINESSPLUS_API_KEY under Environment Variables / Secrets. Ensure server secrets are NOT exposed to the client-side build bundle.

Quick Start: Headless Integration in 4 Steps

To implement a headless storefront in minutes, follow these four canonical steps:

1. Fetch Storefront Catalogue Items: Call GET /v1/storefront/catalog-items?identifier=YOUR_STORE_SLUG to retrieve active products with categories, pricing, stock indicators, and commerce modes.
2. Fetch Product Specifications & Media: Call GET /v1/storefront/product?site_id=YOUR_SITE_UUID&identifier=PRODUCT_SLUG to fetch detailed specifications, photo galleries, dimensions, FAQs, and commerce.mode.
3. Create Order via Server Backend: When the shopper checks out, dispatch POST /v1/orders from your server with customer contact info, delivery address, an idempotency order_request_id UUID, and item IDs with quantities.
4. Redirect to Hosted Payment & Verify: Append your URL-encoded ?return_url to payment.payment_url and redirect the shopper. Upon customer return, verify payment status authoritatively using GET /v1/orders/:id.

NOTE: For a complete, copyable Next.js 14 App Router example demonstrating these four steps with secure trust boundaries, see the Complete Headless Example article.