Custom API Status Report

The Custom API status report enhances transparency and reduces troubleshooting time by providing real-time visibility into the registration status of your Custom APIs. When you activate a code version that includes Custom APIs, the registration process can yield different outcomes for each endpoint. Previously, developers had to manually sift through logs to diagnose issues, but the Custom API status report simplifies this by offering clear, actionable feedback.

Use the B2C CLI:

# Required scopes: sfcc.custom-apis
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli scapi custom status --tenant-id abcd_001
npx @salesforce/b2c-cli scapi custom status --tenant-id abcd_001 --status not_registered

Key Benefits

Real-time status reporting: Get immediate feedback on endpoint registration status.
Error transparency: Understand why an endpoint failed to register.
Reduced debugging time: No manual log searching.
Improved development workflow: Quickly identify and resolve endpoint issues.

Endpoint Registration Status

Every Custom API endpoint can have one of the following registration statuses:

Status	Description	Accessible?
`active`	Endpoint was successfully registered and is ready to handle requests.	Y
`not_registered`	Endpoint failed to register due to an error in configuration or implementation.	N

Use the Custom API Status Report

Authentication

The Custom API status report requires authentication using the Account Manager OAuth 2.0 flow with the required scope:

sfcc.custom-apis (read-only)

Endpoint URL

GET https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints

Parameters

Parameter	Type	Required	Description
`shortCode`	Path	Yes	An eight-character string assigned to a realm for routing purposes, for example: `kv7kzm78`
`organizationId`	Path	Yes	A short string that identifies your B2C Commerce instance, for example: `f_ecom_zzte_053`
`status`	Query	No	Filter endpoints by status: `active` or `not_registered`

Response Format

The endpoint returns a JSON object containing:

activeCodeVersion: The currently active code version
total: Total number of endpoints discovered across all sites and cartridges
limit: Number of endpoints included in this response. This count matches the filter criteria and equals total when no filters are applied.
data: Array of endpoint objects with detailed information
filter: Object containing applied filters. This is present only if filters are used in the request.

Each endpoint object includes:

Field	Description
`id`	Unique identifier for the endpoint (consistent across code version activations)
`apiName`	Name of the API, for example: `loyalty-info`
`apiVersion`	Version of the API, for example: `v1`
`cartridgeName`	Name of the cartridge containing the endpoint
`endpointPath`	The endpoint path, for example: `/customers`
`httpMethod`	HTTP method, for example: `GET`, `POST`)
`operationId`	Operation identifier from the OpenAPI schema
`implementationScript`	Name of the implementation script file
`schemaFile`	Name of the OpenAPI schema file
`siteId`	Site identifier where the endpoint is registered
`securityScheme`	Security scheme used by the endpoint
`status`	Registration status (`active` or `not_registered`)
`errorReason`	Error description (only present when status is `not_registered`)

Examples

List All Endpoints

Get information for all Custom API endpoints in your organization:

curl -X GET \
  'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints' \
  -H 'Authorization: Bearer {access_token}'

Response:

{
  "activeCodeVersion": "version1",
  "limit": 3,
  "data": [
    {
      "id": "10bd7f2dc40ab7aede7f0d60e5c3a783",
      "apiName": "loyalty-info",
      "apiVersion": "v1",
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": "/customers",
      "httpMethod": "GET",
      "implementationScript": "customers.js",
      "operationId": "getLoyaltyInfo",
      "securityScheme": "ShopperToken",
      "schemaFile": "loyalty-schema.yaml",
      "siteId": "Sites-MyStore-Site",
      "status": "active"
    },
    {
      "id": "fd2e726fc9e23dac4951bfe325146c24",
      "apiName": "loyalty-info",
      "apiVersion": "v1",
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": "/rewards",
      "httpMethod": "POST",
      "implementationScript": "rewards.js",
      "operationId": "addReward",
      "securityScheme": "AmOAuth2",
      "schemaFile": "loyalty-schema.yaml",
      "siteId": "Sites-MyStore-Site",
      "status": "active"
    },
    {
      "id": "7f8cfdf0534476b858d080b9059bc07e",
      "apiName": "loyalty-info",
      "apiVersion": null,
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": null,
      "errorReason": "Schema file ../broken-schema.yaml in API folder loyalty-info must not be a relative path.",
      "httpMethod": null,
      "implementationScript": "broken-endpoint.js",
      "operationId": "brokenOperation",
      "securityScheme": null,
      "schemaFile": "../broken-schema.yaml",
      "siteId": "Sites-Site",
      "status": "not_registered"
    }
  ],
  "total": 3
}

Filter by Status

Get endpoints that failed to register:

curl -X GET \
  'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints?status=not_registered' \
  -H 'Authorization: Bearer {access_token}'