sfnext-custom-apis

Custom APIs in Storefront Next

This skill covers the end-to-end workflow for implementing and consuming custom SCAPI endpoints from a Storefront Next project.

Overview

Custom APIs let you define your own REST endpoints on B2C Commerce. In a Storefront Next project, you call these from loaders and actions just like standard SCAPI clients — with full type safety.

End-to-End Workflow

Create custom API    →  Deploy & register  →  Add typed client  →  Discover schema  →  Call from loader
(cartridge)             (b2c code deploy)     (sfnext scapi add)   (scapi schemas)     (createApiClients)

Step 1: Create the Custom API

A custom API consists of three files in a cartridge:

my-cartridge/cartridge/rest-apis/my-loyalty-api/
├── schema.yaml     # OpenAPI 3.0 schema (endpoints, params, responses)
├── api.json        # API metadata (version, security scheme)
└── script.js       # Implementation (controller script)

For full details on writing these files, see the b2c:b2c-custom-api-development skill.

Key choices that affect the client:

Choice	Impact
Directory name (my-loyalty-api)	Becomes the API name for scapi add
type in api.json (shopper or admin)	Determines auth scheme and whether siteId is required
Paths in schema.yaml	Become the methods on the typed client

Step 2: Deploy and Register

Deploy the cartridge and verify the custom API is registered:

# deploy the cartridge
b2c code deploy ./my-cartridge --activate

# verify registration
b2c scapi custom status

A successful registration shows status: active for your endpoints. If you see not_registered, debug with:

b2c scapi custom status --status not_registered --columns type,apiName,endpointPath,errorReason

See b2c-cli:b2c-scapi-custom for full diagnostics.

Step 3: Add as Typed Client

Once registered, add the custom API to your Storefront Next project:

b2c sfnext scapi add custom my-loyalty-api v1