Skip to content
AM

Storefront SDK overview

@inblack/commerce-sdk is the typed JavaScript client for the Commerce Storefront API. It sends the site SDK key on every request, manages an optional customer access token, and turns non-success responses into CommerceError instances.

Install and initialize

Terminal window
pnpm add @inblack/commerce-sdk
import { CommerceClient } from "@inblack/commerce-sdk";


const commerce = new CommerceClient({
  apiUrl: "https://commerce.inblack.app",
  sdkKey: "inb_pk_live_REDACTED",
});

apiUrl is the Commerce API origin. The client adds /storefront/v1 to SDK requests. Use a publishable SDK key for browser code.

The package also exports InBlack and createInBlackClient(). InBlack extends CommerceClient with a grouped commerce namespace while retaining the same methods.

Current namespaces

The checked-in client includes:

  • Products, reviews, collections, inventory, pages, blog, and search.
  • Cart, checkout, shipping, discounts, returns, and recommendations.
  • Customer authentication, account profile, addresses, orders, wishlist, B2B membership, and portal projections.
  • Storefront configuration, SEO, redirects, and page/component contracts.
  • Public form schema and submission methods.

Use the generated TypeScript declarations as the method and response contract for the installed package version.

Customer authentication

After passwordless or Google sign-in, set the returned access token:

const session = await commerce.auth.verify({
  challenge_id: challenge.challenge_id,
  otp,
});


commerce.setToken(session.access_token);
const account = await commerce.account.get();

The SDK stores no token by itself. Your application owns secure storage, refresh, logout, and clearing the client token.

Forms

const schema = await commerce.forms.getSchema(formId);


const submission = await commerce.forms.submit(formId, {
  email: "alex@example.com",
  first_name: "Alex",
});

The method wraps the supplied record as { data: ... }. See Form submissions for validation and contact mapping.

Errors

import { CommerceError } from "@inblack/commerce-sdk";


try {
  await commerce.products.get(productId);
} catch (error) {
  if (error instanceof CommerceError) {
    console.error(error.status, error.code, error.message);
  }
}

The SDK does not automatically retry writes. Handle 429 using the response policy described in SDK key auth.