---
schema_version: "1"
id: 72c659105b31cd074034840f9d1bcbcc4e69c418af7b1067fc83240dc460317b
title: Custom
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/custom-apis.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis
source_site: developer.salesforce.com
content_type: documentation
content_hash: 6ca0d145cd63966d1e7b2fe7297d0fd71ae5c4be631dc08852db509afd426e58
products:
  - B2C Commerce API
  - Salesforce APIs
---
Custom

# Custom

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/custom-apis/custom-apis-oas-v1-public.yaml)

## API Overview

The Custom APIs DX API provides enhanced transparency and manageability of Custom API endpoints within the platform. This API offers a user-friendly and secure approach by providing real-time feedback on endpoint registration status, including successful registrations and failed attempts with error reasons.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.custom-apis` (read-only access) or `sfcc.custom-apis.rw` (read-write access) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

Access is intended for admin users only.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Endpoint Status Transparency

During a new code version activation, developers and administrators often struggle to verify the status of all their Custom API endpoints. This can lead to confusion and time-consuming manual log checks to diagnose why an endpoint might not be active. By using the Custom APIs DX endpoint, a user can programmatically fetch a list of all endpoints and their current status (`active` or `not_registered`). This allows for quick identification of any registration issues, including specific error reasons for endpoints that failed to register, thereby streamlining the validation process after a deployment.

#### Debug Failed Registrations

When a Custom API endpoint fails to register, it can be difficult to understand the root cause without accessible error details. This API directly addresses this by providing an `errorReason` property for any endpoint with a `not_registered` status. For example, if an endpoint registration is skipped because its schema file cannot be read, the API response will explicitly state this, allowing developers to quickly pinpoint and resolve the issue without needing to contact support or search through extensive log files.

**Version:** 1.0.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.custom-apis: Custom APIs READONLY scope
    *   Scope sfcc.custom-apis.rw: Custom APIs scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get a list of resolved Custom API endpoints.

`GET /organizations/{organizationId}/endpoints`

Operation ID: `getEndpoints`. Security: AmOAuth2 (sfcc.custom-apis).

List resolved Custom API endpoints, including not registered endpoints.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `status` (query, EndpointStatus) Filter endpoints by registration status.

#### Responses

*   **200** Successful operation
    
    Media type: `application/json`. Schema: `CustomApiEndpointResult`.
    
    _Example: SuccessWithFilter_
    
    ```
    {
      "limit": 1,
      "total": 2,
      "filter": {
        "status": "active"
      },
      "data": [
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "my_cartridge",
          "endpointPath": "/customers",
          "status": "active"
        }
      ],
      "activeCodeVersion": "version1"
    }
    ```
    
    _Example: SuccessWithoutFilter_
    
    ```
    {
      "limit": 2,
      "total": 2,
      "data": [
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "my_cartridge",
          "endpointPath": "/customers",
          "status": "active"
        },
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "null",
          "endpointPath": "/customers",
          "errorReason": "Cartridge 'my_cartridge_2' not found.",
          "status": "not_registered"
        }
      ],
      "activeCodeVersion": "version1"
    }
    ```
    
*   **400** Invalid or malformed filter parameter
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidFilterParameter_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid value 'foo' for filter parameter 'status'."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### EndpointStatus

Type: `string`.

Allowed values: `active`, `not_registered`. Example: `active`.

### CustomApiEndpointResult

Includes all fields of `ResultBase`.

*   `filter` (_CustomApiEndpointFilter_)
*   `data` (_array of CustomApiEndpoint_)
*   `activeCodeVersion` (_string_)  
    Minimum length: 1. Maximum length: 100. Example: `version1`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomApiEndpointFilter

*   `status` (_string_)  
    Allowed values: `active`, `not_registered`. Example: `not_registered`.

### CustomApiEndpoint

*   `apiName` (_string_)  
    Pattern: ^\[a-z0-9-\]+$. Example: `loyalty-info`.
*   `apiVersion` (_string_)  
    Maximum length: 100. Example: `v1`.
*   `cartridgeName` (_string_)  
    Pattern: ^\[a-zA-Z\]\[a-zA-Z0-9\_\]\*$. Example: `test_bc_wapi`.
*   `endpointPath` (_string_)  
    Maximum length: 4000. Example: `/customers`.
*   `errorReason` (_string_)  
    Maximum length: 4000. Example: `API schema not found.`.
*   `httpMethod` (_string_)  
    Allowed values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`, `HEAD`. Example: `GET`.
*   `id` (_string_)  
    Minimum length: 36. Maximum length: 36. Example: `10bd7f2dc40ab7aede7f0d60e5c3a783abcd`.
*   `implementationScript` (_string_)  
    Maximum length: 100. Example: `script.js`.
*   `operationId` (_string_)  
    Maximum length: 100. Example: `getLoyaltyInfo`.
*   `securityScheme` (_string_)  
    Allowed values: `ShopperToken`, `AmOAuth2`. Example: `ShopperToken`.
*   `schemaFile` (_string_)  
    Maximum length: 100. Example: `schema.yaml`.
*   `siteId` (_SiteId_)
*   `status` (_EndpointStatus_)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.