Skip to main content
sfnext-custom-apis End-to-end workflow for consuming custom SCAPI endpoints from a Storefront Next project — adding them as typed clients via `b2c sfnext scapi add custom`, discovering their schema, and calling them from loaders/actions/useScapiFetcher. Use this skill whenever the user wants to call a custom API from their Storefront Next app, gets a 404 or 401 when calling a custom endpoint from their sfnext loader, needs to add a custom API as a typed client in their storefront, asks about the full workflow from custom API cartridge to sfnext consumption, or says 'custom API in storefront next'. Also use when they ask how createApiClients exposes custom API methods or how to use useScapiFetcher with a custom endpoint. NOT for writing the custom API cartridge files (schema.yaml/script.js) from scratch — see b2c:b2c-custom-api-development. NOT for just checking registration status — see b2c-cli:b2c-scapi-custom.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/SalesforceCommerceCloud/b2c-developer-tooling --skill sfnext-custom-apisThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
name sfnext-custom-apis description End-to-end workflow for consuming custom SCAPI endpoints from a Storefront Next project — adding them as typed clients via `b2c sfnext scapi add custom`, discovering their schema, and calling them from loaders/actions/useScapiFetcher. Use this skill whenever the user wants to call a custom API from their Storefront Next app, gets a 404 or 401 when calling a custom endpoint from their sfnext loader, needs to add a custom API as a typed client in their storefront, asks about the full workflow from custom API cartridge to sfnext consumption, or says 'custom API in storefront next'. Also use when they ask how createApiClients exposes custom API methods or how to use useScapiFetcher with a custom endpoint. NOT for writing the custom API cartridge files (schema.yaml/script.js) from scratch — see b2c:b2c-custom-api-development. NOT for just checking registration status — see b2c-cli:b2c-scapi-custom.
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:
b2c code deploy ./my-cartridge --activate
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
This generates typed client code. The client becomes available as:
const clients = createApiClients (context);
clients.myLoyaltyApi .getPoints ({...});
Step 4: Discover the API Shape Use schema browsing to understand your custom API's endpoints and response types:
b2c scapi schemas get custom my-loyalty-api v1 --list-paths
b2c scapi schemas get custom my-loyalty-api v1 \
--expand-paths /loyalty/points/{customerId}
This shows you the exact parameter names and response shape to use in your loader.
Step 5: Call from Loaders and Actions
Calling from a Loader (Shopper API) import { createApiClients } from '@/lib/api-clients' ;
export function loader ({ params, context }: LoaderFunctionArgs ) {
const clients = createApiClients (context);
return {
loyaltyPoints : clients.myLoyaltyApi .getPoints ({
params : {
path : { customerId : params.customerId },
query : { siteId : context.siteId }
}
}).then (({ data } ) => data),
};
}
Calling from an Action (Mutation) import { data } from 'react-router' ;
import { createApiClients } from '@/lib/api-clients' ;
export async function action ({ request, context }: ActionFunctionArgs ) {
const formData = await request.formData ();
const clients = createApiClients (context);
try {
await clients.myLoyaltyApi .redeemPoints ({
params : {
path : { customerId : formData.get ('customerId' ) as string },
query : { siteId : context.siteId },
body : { points : Number (formData.get ('points' )) }
}
});
return data ({ success : true });
} catch (error) {
return data ({ success : false , error : error.message }, { status : 400 });
}
}
Using useScapiFetcher (Interactive) For on-demand fetching triggered by user interactions:
import { useScapiFetcher } from '@/hooks/use-scapi-fetcher' ;
export function useLoyaltyPoints (customerId : string const parameters = useMemo (
() => ({
params : {
path : { customerId },
query : { siteId : getSiteId () }
}
}),
[customerId]
);
const fetcher = useScapiFetcher (
'myLoyaltyApi' ,
'getPoints' ,
parameters
);
return {
points : fetcher.data ,
isLoading : fetcher.state === 'loading' ,
refresh : () => fetcher.load (),
};
}
Step 6: Debug Issues Issue Cause Solution Client property not available Forgot sfnext scapi add Run b2c sfnext scapi add custom <name> <version> 404 from custom endpoint API not registered Check b2c scapi custom status; redeploy with --activate 401 Unauthorized Wrong security scheme Shopper APIs use ShopperToken; Admin APIs use BearerToken Missing siteId error Shopper custom APIs require siteId Always include siteId in query params for Shopper APIs Schema returns empty API not yet registered Deploy and activate the cartridge first, then browse schemas Types outdated after schema change Stale generated types Re-run b2c sfnext scapi add custom <name> <version> --force
Custom API Client Naming The API directory name maps to a camelCase property on createApiClients():
Directory Name Client Property Example Call my-loyalty-apiclients.myLoyaltyApiclients.myLoyaltyApi.getPoints({...})order-statusclients.orderStatusclients.orderStatus.getStatus({...})inventory-checkclients.inventoryCheckclients.inventoryCheck.checkStock({...})
Shopper vs Admin Custom APIs Aspect Shopper API Admin API Auth scheme ShopperToken (SLAS) BearerToken (Account Manager) Requires siteId Yes No Called from Storefront loaders/actions Admin tools, batch jobs Typical use Customer-facing features Back-office operations
Most Storefront Next custom APIs are Shopper type since they serve storefront pages.
Common Pitfalls Pitfall Problem Solution Using admin auth for a shopper endpoint 401 errors in storefront context Set type: "shopper" in api.json Forgetting to redeploy after schema changes Stale endpoints Redeploy cartridge and re-add client with --force Not including siteId for shopper APIs Request rejected Always pass siteId in query params Calling custom API before registration completes Intermittent 404s Wait for status: active in b2c scapi custom status
Related Skills
storefront-next:sfnext-scapi-management - Managing typed clients (add/remove/list)storefront-next:sfnext-data-fetching - Loader/action/useScapiFetcher patternsb2c:b2c-custom-api-development - Creating the custom API cartridge (schema + script + mapping)b2c-cli:b2c-scapi-custom - Checking custom API registration statusb2c-cli:b2c-scapi-schemas - Schema discovery commandsb2c-cli:b2c-code - Deploying and activating code versions
Reference Documentation More from this repository Run and monitor jobs on B2C Commerce instances using the b2c CLI, including individual site archive imports and exports and search indexing. Use this skill whenever the user needs to trigger an existing job, import a single site archive, export site data, rebuild search indexes, check job status, or troubleshoot a failed job execution — even if they just say "run this job", "import this archive", or "rebuild the search index".
Import and export site archives containing metadata XML on B2C Commerce instances using the b2c CLI. Use this skill whenever the user needs to import a site archive directory or zip to an instance, apply an ordered set of archives idempotently, export site configuration as XML, structure a site archive folder (sites/site_template/meta/), write or debug metadata XML files (system-objecttype-extensions.xml, custom-objecttype-definitions.xml, preferences.xml), or push custom attributes, custom object types, or site preferences to a sandbox via site import. Also use when an import job fails with schema validation errors — even if they just say "push metadata to the sandbox" or "import my XML files".
List, upload, download, and manage files on B2C Commerce instances via WebDAV. Use this skill whenever the user needs to upload files to IMPEX directories, download exports from an instance, list remote files, create or delete directories, zip or unzip files on the server, manage file transfers to sandboxes, or browse instance file systems — even if they just say "upload a file to the instance" or "check what's in the IMPEX folder".
