b2c-custom-api-development

Original：🇺🇸 English

Translated

Develop Custom SCAPI endpoints for B2C Commerce. Use when creating REST APIs, defining api.json routes, writing schema.yaml (OAS 3.0), or building headless commerce integrations. Covers cartridge structure, endpoint implementation, and OAuth scope configuration.

3installs

Sourcesalesforcecommercecloud/b2c-developer-tooling

Added on2026-04-10

NPX Install

npx skill4agent add salesforcecommercecloud/b2c-developer-tooling b2c-custom-api-development

SKILL.md Content

View Translation Comparison →

Custom API Development Skill

This skill guides you through developing Custom APIs for Salesforce B2C Commerce. Custom APIs let you expose custom script code as REST endpoints under the SCAPI framework.

Tip: If
b2c
CLI is not installed globally, use
npx @salesforce/b2c-cli
instead (e.g.,
npx @salesforce/b2c-cli code deploy
).

Overview

A Custom API URL has this structure:

https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}/organizations/{organizationId}/{endpointPath}

Three components are required to create a Custom API:

API Contract - An OAS 3.0 schema file (YAML)
API Implementation - A script using the B2C Commerce Script API
API Mapping - An
```
api.json
```
file binding endpoints to implementations

Cartridge Structure

/my-cartridge
    /cartridge
        package.json
        /rest-apis
            /my-api-name              # API name (lowercase alphanumeric and hyphens only)
                api.json              # Mapping file
                schema.yaml           # OAS 3.0 contract
                script.js             # Implementation

Important: API directory names can only contain alphanumeric lowercase characters and hyphens.

Component 1: API Contract (schema.yaml)

Minimal example:

yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: My Custom API
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my_scope: My custom scope
  parameters:
    siteId:
      name: siteId
      in: query
      required: true
      schema:
        type: string
        minLength: 1
paths:
  /my-endpoint:
    get:
      operationId: getMyData
      parameters:
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: Success
security:
  - ShopperToken: ['c_my_scope']

Key requirements:

Use
```
ShopperToken
```
for Shopper APIs (requires siteId),
```
AmOAuth2
```
for Admin APIs
Custom scopes must start with
```
c_
```
, max 25 chars
Custom parameters must have
```
c_
```
prefix

See Contract Reference for full schema examples and Shopper vs Admin API differences.

Component 2: Implementation (script.js)

javascript

var RESTResponseMgr = require('dw/system/RESTResponseMgr');

exports.getMyData = function() {
    var myParam = request.getHttpParameterMap().get('c_my_param').getStringValue();
    var result = { data: 'my data', param: myParam };
    RESTResponseMgr.createSuccess(result).render();
};
exports.getMyData.public = true;  // Required

Key requirements:

Mark exported functions with
```
.public = true
```
Use
```
RESTResponseMgr.createSuccess()
```
for responses
Use
```
RESTResponseMgr.createError()
```
for error responses (RFC 9457 format)

See Implementation Reference for caching, remote includes, and external service calls.

Component 3: Mapping (api.json)

json

{
  "endpoints": [
    {
      "endpoint": "getMyData",
      "schema": "schema.yaml",
      "implementation": "script"
    }
  ]
}

Important: Implementation name must NOT include file extension.

Development Workflow

Create cartridge with
```
rest-apis/{api-name}/
```
structure
Define contract (schema.yaml) with endpoints and security
Implement logic (script.js) with exported functions
Create mapping (api.json) binding endpoints to implementation
Deploy and activate to register endpoints
Check registration status and test

Deployment

bash

# Deploy and activate to register endpoints
b2c code deploy ./my-cartridge --reload

# Check registration status
b2c scapi custom status --tenant-id zzpq_013

# Show failed registrations with error reasons
b2c scapi custom status --tenant-id zzpq_013 --status not_registered --columns apiName,endpointPath,errorReason

Authentication Setup

For Shopper APIs

Create a SLAS client with your custom scope(s):