Skip to main content

Overview

The Storefront API enables you to build custom shopping experiences for voucher products. Unlike traditional REST APIs, the Storefront API uses SignalR for real-time, bidirectional communication between your frontend application and our servers.

Key Features​

  • Real-time updates: Receive instant notifications when the basket is updated
  • Client-only architecture: No backend required - connect directly from your frontend
  • Stateful sessions: Maintain basket state across page reloads using local storage
  • Promo code support: Apply and remove promotional codes in real-time

How It Works​

  1. Connect to the SignalR hub from your frontend application
  2. Create or resume a shopping basket using a unique identifier
  3. Add/remove items and apply promo codes via hub method invocations
  4. Listen for events to receive basket updates and handle errors
  5. Redirect to checkout when the customer is ready to complete their purchase

Prerequisites​

Before integrating with the Storefront API, you will need:

  • A Sales Channel ID - identifies your storefront configuration
  • Access to product IDs for the vouchers you want to sell
  • The SignalR JavaScript client library included in your frontend
  • Your domain(s) whitelisted for CORS (see below)

Domain Whitelisting​

The Storefront API requires your domain to be whitelisted for CORS (Cross-Origin Resource Sharing). Before you can connect to the API from your frontend, you must provide us with the domains you plan to use.

Required Setup

Please contact our support with the following information:

  • Staging domain(s): e.g., https://staging.yourstore.com
  • Production domain(s): e.g., https://yourstore.com, https://www.yourstore.com

Your integration will not work until your domains have been whitelisted.

Architecture Overview​

┌─────────────────────┐         ┌─────────────────────┐
│   Your Frontend     │◄───────►│   SignalR Hub       │
│   (Browser)         │     WebSocket/SSE    (Storefront API)
└─────────────────────┘         └─────────────────────┘
         │                               │
         │                               ▼
         │                      ┌─────────────────────┐
         │                      │   Basket Service    │
         │                      └─────────────────────┘
         │                               │
         ▼                               ▼
┌─────────────────────┐         ┌─────────────────────┐
│   Checkout Page     │◄────────│   Order Processing  │
│   (Hosted)          │         └─────────────────────┘
└─────────────────────┘

The Storefront API handles basket management while the checkout process is completed on a hosted checkout page. Your application is responsible for the product display and shopping experience.