--- schema_version: "1" id: 06472dcff065c803ed19332ef573ffcffde8ad2717426d6969b11e21d53d12fe title: Custom API Status Report collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-status-report.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-status-report.html source_site: developer.salesforce.com content_type: documentation content_hash: ce01424f8be3ba8ceea3b385584662be1a6585b5c7baeaabdb5d060ffd065126 products: - Composable Storefront - Salesforce APIs --- # 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](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md): ```bash # 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 ```http 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: ```bash curl -X GET \ 'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints' \ -H 'Authorization: Bearer {access_token}' ``` Response: ```json { "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: ```bash curl -X GET \ 'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints?status=not_registered' \ -H 'Authorization: Bearer {access_token}' ``` Response: ```json { "activeCodeVersion": "version1", "limit": 1, "data": [ { "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" } ], "filter": { "status": "not_registered" }, "total": 3 } ``` ## Responses 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) ## Common Error Scenarios 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 ## Troubleshooting Workflow 1. Check overall status: Use the status report without filters to get an overview of all endpoints. 2. Check code version: Verify that the active code version in the field `activeCodeVersion` is the version you expect. 3. Identify failed endpoints: Filter by `status=not_registered` to focus on problematic endpoints. 4. Analyze errors: Review the `errorReason` field for specific guidance. 5. Fix issues: Address the identified problems in your cartridge. 6. Reactivate: Upload and activate a new code version. 7. Verify: Call the status report again to confirm successful registration. ## Related Documentation - [Custom API Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-troubleshooting.md): Additional troubleshooting guidance for Custom API development - [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md): Set up authentication for Status Report endpoints