sfcc-scapi-custom-endpoints

Custom SCAPI Endpoint Development Skill

This skill guides you through developing Custom APIs for Salesforce B2C Commerce under the SCAPI framework.

Quick Checklist

[ ] Cartridge contains `cartridge/rest-apis/{api-name}/` with schema.yaml, script.js, api.json
[ ] operationId in schema matches exported function name with `.public = true`
[ ] Custom parameters and scopes use the `c_` prefix
[ ] Contract avoids unsupported features (no additionalProperties, only local $ref)
[ ] Shopper APIs include siteId; Admin APIs omit it
[ ] Code version is activated to register endpoints

URL Structure

https://{shortcode}.api.commercecloud.salesforce.com/custom/{api-name}/v{major}/organizations/{org-id}{path}?{params}

Version is derived from info.version: "1.2.0" → /v1/, "2.0.0" → /v2/

Cartridge Structure

my_cartridge/
└── cartridge/
    └── rest-apis/
        └── my-api-name/          # Lowercase alphanumeric + hyphens only
            ├── api.json          # Mapping file
            ├── schema.yaml       # OAS 3.0 contract
            └── script.js         # Implementation

The Three Components

1. API Contract (schema.yaml)

openapi: 3.0.0
info:
  title: My Custom API
  version: "1.0.0"
paths:
  /my-endpoint:
    get:
      operationId: getMyData        # Must match function name
      parameters:
        - name: siteId              # Required for Shopper APIs
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: c_my_param          # Custom params must have c_ prefix
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
      security:
        - ShopperToken: [c_my_scope]

components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{orgId}/oauth2/token
          scopes:
            c_my_scope: Description