Public Theme SDK

@upstorr/theme-sdk/v1 is the only Upstorr package a theme may use. It gives every theme the same documented data and actions. It contains no brand-specific design.

The generated .upstorr-theme/sdk/ files give VS Code autocomplete. Do not edit them; the CLI replaces them.

The complete public export index is generated from the real version-one SDK and published at help.upstorr.com/developers/sdk/api-reference. Use this guide to choose the right group of helpers, then use autocomplete or the API reference for the exact input and return types.

Optional browser JavaScript

Put Level 3 browser code in theme/assets/theme.ts:

const enhance = () => {
  // Attach this theme's animation or interaction to the current page.
};

enhance();
window.addEventListener('upstorr:storefront-navigation', enhance);

Upstorr changes many storefront pages without refreshing the browser. Listen for upstorr:storefront-navigation when your enhancement must run again.

Use SDK builders instead of rebuilding route rules:

import {
  buildThemeArticleUrl,
  buildThemeCollectionUrl,
  buildThemeOrdersUrl,
  buildThemeProductUrl,
  buildThemeSearchUrl,
} from '@upstorr/theme-sdk/v1';

Cart and product actions

Use named helpers such as addThemeCartItem, updateThemeCartItemQuantity, removeThemeCartItem, fetchThemeCart and the approved themeRuntimeProps.productAddToCart(...) attributes. Do not call cart endpoints or create CSRF headers yourself.

Product helpers include URL, image, pricing, variant, inventory, recommendation, gift-card metadata and review view helpers. Use the generated autocomplete to see the exact input and result types for the installed CLI version.

Checkout

Checkout state and submission use fetchThemeCheckout, saveThemeCheckoutDraft, submitThemeCheckout and documented themeRuntimeProps.checkout* attributes. The backend remains the only owner of inventory reservations, discounts, GST, shipping totals, payment actions and order creation.

Never put payment-provider names, provider script URLs, payment globals or tax calculations in a theme.

Accounts and addresses

Account helpers cover sending and verifying sign-in codes, logout, address forms and supported account attributes. Common names include sendThemeAccountCode, verifyThemeAccountCode, createThemeAccountAddressFormView, getThemeAccountAuthFormProps, getThemeAccountFieldProps, getThemeAccountActionProps, getThemeAccountAddressFormProps and getThemeAccountAddressSaveProps.

Themes never read login cookies or store authentication tokens. Upstorr uses secure httpOnly cookies and SDK-owned CSRF handling.

Wishlist

Use fetchThemeWishlist, getThemeWishlistItems, addThemeWishlistItem, removeThemeWishlistItem, publishThemeWishlistUpdated and the supported wishlist runtime props. Do not call a wishlist URL directly.

Orders, bookings and digital delivery

Order helpers include fetchThemeOrders, fetchThemeOrderDetail, formatThemeOrderNumber, formatThemeOrderStatusLabel, getThemeOrderStatusTone and buildThemeOrdersUrl.

Booking, cancellation, return, gift-card and digital-delivery helpers are exposed through the same versioned SDK. Use autocomplete to choose the exact named helper and required typed input. Protected downloads and account-owned information must always flow through the SDK.

Third-party browser libraries

Install a normal browser library in the theme checkout and declare it in the root package.json. Then import it from theme/assets/theme.ts. The CLI checks that the package is declared and bundles it into local preview and uploaded versions.

Forbidden code

A theme must not:

import any other @upstorr/* package;
use fetch, Axios or XMLHttpRequest for platform data;
reference /api/ or storefront API paths;
read cookies or manually create authorization/CSRF headers;
use local storage for platform state;
import Node modules, server libraries or Next.js internals;
hand-write data-upstorr-*, data-account-* or data-selected* attributes in TypeScript;
inject script tags or payment-provider SDKs.

If a required platform action is missing, the SDK contract must be expanded for every theme. Do not create a private shortcut inside one theme.

Theme SDK overview