Build a Storefront

Use the Infuse Cloud dashboard to create and manage listings first. Build a custom storefront only when you need to sell marketplace products from your own website or application.

Your storefront owns the customer experience: product browsing, customer authentication, device selection, post-checkout status, and install actions. Infuse remains the source of truth for published products, checkout sessions, purchase entitlements, release compatibility, and install access.

Dashboard Setup

Before integrating a custom storefront:

1. Open Marketplace.
2. Select the marketplace instance.
3. Open Provider.
4. Open Discover and choose products to sell.
5. Create listings for those products.
6. Open Listings and confirm each listing is active.
7. Open Purchases to understand how completed purchases are reviewed.
8. Open Devices to understand device state and install actions.

The dashboard is the operational control surface for products, listings, purchases, and installs. Store Preview can be useful later as a manual example of listing selection and checkout session creation, but a production storefront should use your own backend boundary so provider credentials never run in the customer browser.

At a high level, your backend reads products from Infuse, creates a checkout session for the selected products and devices, redirects the customer to Stripe Checkout, then reads purchase state from Infuse after Stripe confirms payment.

How the Integration Works

Your storefront should call Infuse APIs from your server. Do not call Infuse Marketplace APIs directly from customer browsers with provider credentials.

For manual dashboard verification of checkout states, see Checkout Flow.

---
toolbar:
  title: Storefront checkout flow
---
sequenceDiagram
    participant Customer as End customer
    participant Frontend as Your storefront frontend
    participant Backend as Your backend
    participant Infuse as Infuse Marketplace API
    participant Stripe as Stripe Checkout

    Customer->>Frontend: Opens storefront
    Frontend->>Backend: Request catalogue
    Backend->>Infuse: List published marketplace items
    Infuse-->>Backend: Items, prices, images, metadata
    Backend-->>Frontend: Storefront catalogue data
    Frontend-->>Customer: Show products
    Customer->>Frontend: Select products and devices
    Frontend->>Backend: Start checkout
    Backend->>Infuse: Create checkout session
    Infuse-->>Backend: checkoutSessionId and checkoutUrl
    Backend-->>Frontend: checkoutUrl
    Frontend-->>Customer: Redirect to Stripe Checkout
    Customer->>Stripe: Complete or cancel payment
    Stripe-->>Customer: Redirect to your success or cancel URL
    Infuse->>Infuse: Validate payment and create entitlements
    Frontend->>Backend: Load purchase status
    Backend->>Infuse: Read provider purchases
    Infuse-->>Backend: Purchase and entitlement state
    Backend-->>Frontend: Confirmation, pending, or error state

Before You Start

You need:

• An Infuse organisation with access to the marketplace instance you want to sell from.
• Server-side API credentials for that organisation.
• Permissions for published catalogue reads, checkout session creation, provider devices, provider purchases, and install access if your site will trigger installs.
• The marketplaceInstanceId for the marketplace instance your storefront should display.
• Absolute successUrl and cancelUrl routes hosted by your site.
• A way to map signed-in customers in your system to one or more Infuse device IDs.

Keep API credentials on your backend. Your frontend should receive only the product, device, checkout, and purchase data needed to render the customer experience.

Recommended Backend Boundary

Expose your own customer-facing routes and keep Infuse authentication behind them. For example:

This boundary lets you enforce your own customer authentication, hide provider credentials, validate selected devices belong to the signed-in customer, and store local audit records such as the returned checkoutSessionId.

1. Load Published Products

Use the public marketplace item APIs to build your catalogue and product detail pages.

GET /marketplace/marketplace-items?marketplaceInstanceId={marketplaceInstanceId}&page=1&pageSize=24
Authorization: Bearer {provider_access_token}

Common query fields:

For a product detail page, fetch the current listed item before showing price or allowing checkout.

GET /marketplace/marketplace-items/{id}?marketplaceInstanceId={marketplaceInstanceId}
Authorization: Bearer {provider_access_token}

Use Infuse as the source of truth for marketplace item IDs, listing visibility, price, currency, version metadata, icons, images, and developer-provided descriptions. If you cache catalogue data, refresh it before checkout so you do not sell an item that has changed price or visibility.

2. Resolve Customer Devices

Checkout sessions are created for one or more target devices. Your storefront must know which devices the customer can buy for before creating checkout.

Most providers resolve this through their own account system:

1. Authenticate the customer in your site.
2. Load the customer-owned devices from your system.
3. Map each selectable device to the corresponding Infuse deviceId.
4. Send only valid selected deviceIds to your checkout route.

If the devices are registered in your provider Infuse IoT organisation, your backend can also read provider devices from Infuse:

GET /marketplace/providers/devices?limit=50&offset=0
Authorization: Bearer {provider_access_token}

Before checkout, validate that you have:

• At least one selected deviceId.
• At least one selected marketplaceItemId.
• A signed-in customer who is allowed to buy for those devices.
• Current product data from Infuse for the selected marketplace items.

3. Create a Checkout Session

When the customer confirms their basket, create an Infuse checkout session from your backend.

POST /marketplace/checkout/session
Authorization: Bearer {provider_access_token}
Content-Type: application/json

{
  "deviceIds": ["device_123", "device_456"],
  "marketplaceItemIds": ["mi_abc"],
  "successUrl": "https://example.com/marketplace/checkout/success",
  "cancelUrl": "https://example.com/marketplace/checkout/cancel",
  "livemode": true
}

The request includes:

The response includes:

{
  "checkoutSessionId": "mcs_123",
  "checkoutUrl": "https://checkout.stripe.com/c/session...",
  "livemode": true
}

Store the checkoutSessionId with your local order, customer action, or audit record if you need reconciliation. Then redirect the customer to checkoutUrl.

4. Redirect to Stripe Checkout

Infuse creates the Stripe Checkout session. Your integration should not create Stripe products, prices, line items, or fulfillment records directly for Marketplace purchases.

After the customer pays or cancels, Stripe redirects the browser to the successUrl or cancelUrl you supplied. Treat this redirect as a browser navigation event, not proof that the purchase is active. Infuse validates successful payment, records purchase state, and creates the relevant entitlements.

5. Read Purchase State

After the customer returns to your site, read purchase state from Infuse through your backend.

GET /marketplace/providers/purchases?deviceId={deviceId}&livemode=true&page=1&pageSize=20
Authorization: Bearer {provider_access_token}

Useful query fields:

Use this endpoint to drive "Your purchases", checkout confirmation, pending payment, and entitlement-aware UI states.

For a device detail page, load the device and purchase context:

GET /marketplace/providers/devices/{deviceId}/details
Authorization: Bearer {provider_access_token}

For release and compatibility information for a purchased product on a device:

GET /marketplace/providers/devices/{deviceId}/purchases/{marketplaceItemId}/releases
Authorization: Bearer {provider_access_token}

Your success page should be able to show a pending state while Infuse confirms the purchase. Poll or refresh purchase state from your backend until the purchase is active, failed, or requires customer support.

6. Queue Installs

Payment and installation are separate steps. A successful checkout grants purchase entitlements. Your storefront decides whether to install immediately after purchase or present install controls later.

First, read available releases for the purchased item and device:

GET /marketplace/providers/devices/{deviceId}/purchases/{marketplaceItemId}/releases
Authorization: Bearer {provider_access_token}

Then queue an install for the selected version:

POST /marketplace/providers/devices/{deviceId}/purchases/{marketplaceItemId}/install
Authorization: Bearer {provider_access_token}
Content-Type: application/json

{
  "version": "1.4.2"
}

Only show install actions for active purchases and compatible releases. If a release is not compatible with the target device, keep the action disabled and explain the device or version requirement in your UI.

Provider Listing APIs

Provider listing APIs are useful for provider administration screens, but customer-facing storefront pages should normally read from the public marketplace item APIs so the storefront reflects what is currently published and visible to customers.

GET /marketplace/providers/listings
Authorization: Bearer {provider_access_token}

GET /marketplace/providers/listings/{marketplaceId}
Authorization: Bearer {provider_access_token}

Use these APIs when you need to inspect or manage the products your provider organisation lists. Do not use them as the only checkout-time availability check.

Customer Experience States

Build explicit states into your storefront:

Implementation Checklist

• Keep provider API credentials server-side.
• Build around Infuse marketplaceItemIds; avoid a separate product ID system unless it maps directly back to Infuse IDs.
• Validate selected devices against your signed-in customer before creating checkout.
• Refresh product details before checkout so price, currency, and visibility are current.
• Use absolute, stable successUrl and cancelUrl values.
• Store checkoutSessionId if you need local order tracking or support diagnostics.
• Treat successUrl as a return route, not fulfillment confirmation.
• Read purchase state from GET /marketplace/providers/purchases.
• Use livemode: true only for real customer transactions.
• Trigger installs only for active purchases and compatible releases.
• Do not call Stripe directly to fulfill Marketplace purchases.

Endpoint Summary

Related Documentation

• Checkout flow
• Purchases
• Install purchased products
• Marketplace API reference