@shopstack-enterprise/sdk

Server, browser, and React SDKs for Shopstack checkout.

Install

npm install @shopstack-enterprise/sdk

React consumers also need React 18 or 19:

npm install react

Server SDK

The server SDK is available only through @shopstack-enterprise/sdk/server. Never expose a Shopstack API key in browser code.

import { Shopstack } from '@shopstack-enterprise/sdk/server'

const shopstack = new Shopstack({
  apiKey: process.env.SHOPSTACK_API_KEY!,
})

const session = await shopstack.checkoutSessions.create({
  productUrl: 'https://merchant.example/products/blue-shirt',
  amount: 1999,
  currencyCode: 'usd',
  imageUrls: [
    'https://merchant.example/images/blue-shirt-front.jpg',
    'https://merchant.example/images/blue-shirt-back.jpg',
  ],
})

amount is a positive integer in the currency's minor unit, so USD 19.99 is sent as 1999. currencyCode is a lowercase three-letter ISO 4217 currency code. imageUrls is optional. When provided, it accepts up to 10 absolute HTTPS image URLs to display in order on the checkout site.

Failed API responses throw ShopstackError, which includes status, code, and requestId. The server that creates the session should return only checkoutSessionId to its browser client.

Browser SDK

import { createShopstackCheckout } from '@shopstack-enterprise/sdk/browser'

const checkout = createShopstackCheckout({
  checkoutSessionId: '019...',
})

checkout.mount('#checkout')

// Remove the iframe and its event listeners when it is no longer needed.
checkout.destroy()

The iframe fills the width of its container. Set its height through the optional className or your container styles:

.shopstack-checkout {
  min-height: 720px;
}

createShopstackCheckout({
  checkoutSessionId: '019...',
  className: 'shopstack-checkout',
}).mount('#checkout')

React SDK

import { ShopstackCheckout } from '@shopstack-enterprise/sdk/react'

export function Checkout({ checkoutSessionId }: { checkoutSessionId: string }) {
  return (
    <ShopstackCheckout
      checkoutSessionId={checkoutSessionId}
      iframeClassName="shopstack-checkout"
      onLoad={() => console.log('Checkout loaded')}
    />
  )
}

An iframe load event only means the checkout UI loaded. Treat any browser success screen or future client-side completion event as a UI signal; fulfill orders from your verified server-side payment webhook.

Local development

Use baseUrl for the API and checkoutUrl for the embed site:

const shopstack = new Shopstack({
  apiKey: 'local-api-key',
  baseUrl: 'http://localhost:8787',
})

createShopstackCheckout({
  checkoutSessionId: '019...',
  checkoutUrl: 'http://localhost:3002',
}).mount('#checkout')

Development

Install dependencies from the repository root, then work from packages/sdk:

vp install
cd packages/sdk
vp pack --watch

Before submitting changes:

vp check
vp test --run
vp pack

Publishing

After the checks pass, bump the version and publish from packages/sdk:

npm version patch # or minor / major
npm publish --access public

The prepack script rebuilds and validates the package before npm publishes it. Use npm pack --dry-run to inspect the release contents first.