Skip to main content

Hub Methods

Hub methods are invoked from your client application to perform actions on the server. All methods are asynchronous and should be called using connection.invoke().

CreateBasket​

Creates a new basket or associates an existing basket ID with your connection.

await connection.invoke("CreateBasket", basketId, salesChannelId);

Parameters​

ParameterTypeDescription
basketIdstringA unique identifier for the basket (UUID recommended)
salesChannelIdstringYour Sales Channel identifier

Usage Notes​

  • Call this method after establishing a connection
  • The basketId should be generated client-side and stored in local storage for persistence
  • If a basket with the given ID already exists, it will be associated with the current connection

Example​

function generateBasketId() {
  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function (c) {
    const r = (Math.random() * 16) | 0;
    const v = c === "x" ? r : (r & 0x3) | 0x8;
    return v.toString(16);
  });
}

const basketId = localStorage.getItem("basketId") || generateBasketId();
localStorage.setItem("basketId", basketId);

await connection.invoke("CreateBasket", basketId, salesChannelId);

ResumeShopping​

Retrieves the current state of an existing basket. Use this to restore the basket after a page reload or reconnection.

const response = await connection.invoke(
  "ResumeShopping",
  basketId,
  salesChannelId,
);

Parameters​

ParameterTypeDescription
basketIdstringThe basket identifier to resume
salesChannelIdstringYour Sales Channel identifier

Returns​

Returns a response object containing the basket state:

{
  "result": {
    "items": [...],
    "promoCode": "SUMMER20"
  }
}

Example​

const response = await connection.invoke(
  "ResumeShopping",
  basketId,
  salesChannelId,
);
if (response && response.result) {
  const basket = response.result;
  updateCartUI(basket.items);
  if (basket.promoCode) {
    displayAppliedPromoCode(basket.promoCode);
  }
}

GetVouchers​

Retrieves the available voucher products for a sales channel. Use this method to display the products that customers can add to their basket.

Limitations

The Storefront API currently does not support:

  • Vouchers with promotional discounts - Products with special pricing or promotions
  • Custom value vouchers - Products where the customer can choose their own amount
const response = await connection.invoke("GetVouchers", salesChannelId);

Parameters​

ParameterTypeDescription
salesChannelIdstringYour Sales Channel identifier

Returns​

Returns an array of available products directly. See Product Model for the full schema.

[
  {
    id: "cd4f589c-b2d3-0b90-3862-986e252d536c",
    catalogueId: "96b4e0f2-96aa-7376-775f-8cb7af702c6f",
    name: "Afternoon Tea for two",
    venueName: null,
    price: {
      amount: "100",
      currency: "GBP",
    },
    isPrivate: false,
    limitedAvailability: null,
    marketingDescription: "A fantastic afternoon tea",
    detailedDescription: "A fantastic afternoon tea",
    images: ["https://example.com/media/voucher-image.png"],
    tags: ["dining", "relax"],
    terms: "<p>Terms and conditions...</p>",
    validity: {
      validMonths: 6,
    },
    reservationEmail: "reservations@example.org",
    reservationPhone: "+44 00-00-0000",
    reservationWebsite: null,
    reservationInstructions: null,
    isActive: true,
  },
];

Example​

async function loadProducts(salesChannelId) {
  const products = await connection.invoke("GetVouchers", salesChannelId);

  // Filter to only show active products
  const activeProducts = products.filter((p) => p.isActive);

  activeProducts.forEach((product) => {
    console.log(
      `${product.name}: ${product.price.amount} ${product.price.currency}`,
    );
  });

  return activeProducts;
}

// Render products in the UI
function renderProducts(products) {
  const container = document.getElementById("products");

  container.innerHTML = products
    .map(
      (product) => `
    <div class="product-card">
      <img src="${product.images[0]}" alt="${product.name}">
      <h3>${product.name}</h3>
      <p>${product.marketingDescription}</p>
      <p class="price">${formatPrice(product.price)}</p>
      <p class="validity">Valid for ${product.validity.validMonths} months</p>
      <div class="tags">
        ${product.tags.map((tag) => `<span class="tag">${tag}</span>`).join("")}
      </div>
      <button
        class="add-to-cart-btn"
        data-product-id="${product.id}">
        Add to Cart
      </button>
    </div>
  `,
    )
    .join("");
}

AddItem​

Adds a product to the basket. Each invocation adds one unit of the product.

await connection.invoke("AddItem", productId);

Parameters​

ParameterTypeDescription
productIdstringThe product identifier to add

Behavior​

  • Triggers a BasketUpdated event on success
  • Triggers a SomethingHappened event if the product is unavailable

Example​

async function addToCart(productId, quantity = 1) {
  for (let i = 0; i < quantity; i++) {
    await connection.invoke("AddItem", productId);
  }
}

RemoveItems​

Removes one or more items from the basket by their line item IDs.

await connection.invoke("RemoveItems", lineItemIds);

Parameters​

ParameterTypeDescription
lineItemIdsstring[]Array of line item identifiers to remove

Usage Notes​

  • Each item in the basket has a unique lineItemId
  • To remove all instances of a product, collect all line item IDs for that product
  • To decrement quantity by one, remove a single line item ID

Example​

// Remove a single item (decrement quantity)
async function decrementQuantity(productId, basketItems) {
  const item = basketItems.find((i) => i.productId === productId);
  if (item) {
    await connection.invoke("RemoveItems", [item.lineItemId]);
  }
}

// Remove all instances of a product
async function removeProduct(productId, basketItems) {
  const lineItemIds = basketItems
    .filter((i) => i.productId === productId)
    .map((i) => i.lineItemId);

  if (lineItemIds.length > 0) {
    await connection.invoke("RemoveItems", lineItemIds);
  }
}

ApplyPromoCode​

Applies a promotional code to the basket.

const result = await connection.invoke("ApplyPromoCode", promoCode);

Parameters​

ParameterTypeDescription
promoCodestringThe promotional code to apply

Behavior​

  • Triggers a BasketUpdated event on success with updated prices
  • Triggers a SomethingHappened event with error code PromoCodeDoesntExist if invalid

Example​

async function applyPromoCode(code) {
  try {
    await connection.invoke("ApplyPromoCode", code);
    // Success - BasketUpdated event will contain new prices
  } catch (err) {
    console.error("Failed to apply promo code:", err);
  }
}

RemovePromoCode​

Removes the currently applied promotional code from the basket.

await connection.invoke("RemovePromoCode");

Parameters​

None.

Behavior​

  • Triggers a BasketUpdated event with original prices restored