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.

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.

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

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

sfcc.custom-apis (read-only)

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`

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`)

Get information for all Custom API endpoints in your organization:

Response:

Get endpoints that failed to register:

Response:

The API returns these standard HTTP status codes:

200: Successful request
400: Invalid filter parameter, for example: unsupported status value
401: Authentication required
403: Insufficient permissions (missing required scope)

When endpoints have a NOT_REGISTERED status, common errors include:

Invalid file paths: Schema or implementation files are not found
Invalid files: Schema or implementation files are unreadable
Configuration errors: Issues with API mapping
Validation errors: Issues with security scheme or parameter definition
Schema file errors: Invalid OpenAPI specification format or structure
Schema reference errors: External dependency validation issues
Path pattern errors: URL pattern parsing failures

Check overall status: Use the status report without filters to get an overview of all endpoints.
Check code version: Verify that the active code version in the field activeCodeVersion is the version you expect.
Identify failed endpoints: Filter by status=NOT_REGISTERED to focus on problematic endpoints.
Analyze errors: Review the errorReason field for specific guidance.
Fix issues: Address the identified problems in your cartridge.
Reactivate: Upload and activate a new code version.
Verify: Call the status report again to confirm successful registration.

Custom API Troubleshooting: Additional troubleshooting guidance for Custom API development
Authorization for SCAPI Admin APIs: Set up authentication for Status Report endpoints