---
schema_version: "1"
id: 0b366854db6afe33df1d5823b7e9675c4f7acf99c60e5d21687acac003bb9e95
title: Schemas
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/scapi-schemas.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/scapi-schemas
source_site: developer.salesforce.com
content_type: documentation
content_hash: 1f8c9b2d2b9946c7cc1fea0ea82f75bc17aaf1d9e252226dad0a91b950429600
products:
  - B2C Commerce API
  - Salesforce APIs
---
Schemas

# Schemas

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

## API Overview

The SCAPI Schema API provides programmatic retrieval of OpenAPI schema definitions for all B2C Commerce API (SCAPI) endpoints, which facilitates better integration, validation, and development workflows across the Commerce Cloud ecosystem.

This API serves as a central registry for all SCAPI schema definitions, allowing you to discover available APIs by family, name, and version, as well as retrieve detailed schema specifications for specific API endpoints.

### Authentication & Authorization

The SCAPI Schema API uses an Account Manager OAuth 2.0 bearer token for authentication. 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. The client must first authenticate against Account manager to log in.

The necessary scope for accessing the SCAPI Schema API is:

*   `sfcc.scapi-schemas`: Provides access to retrieve SCAPI schema definitions and listings.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

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

Access is typically intended for developers, integration tools, and administrative applications that need to programmatically work with SCAPI schema definitions.

### 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

#### Schema Discovery and Cataloging

Discover all available SCAPI endpoints and their current schema versions. This is particularly useful for:

*   Development Tools: IDE plugins and code generators that need to understand available APIs
*   Integration Platforms: Systems that need to dynamically discover and adapt to available Commerce Cloud APIs
*   Documentation Systems: Tools that automatically generate API documentation or SDK references
*   Governance and Compliance: Tracking which APIs are available, their versions, and deprecation status

The API allows filtering by:

*   API family, for example: "product", "checkout", "customer
*   API name, for example: "shopper-products", "orders"
*   API version, for example: "v1", "v2"
*   Cartridge name, for example: "my\_cartridge". **Only for Custom APIs.**
*   Status, for example: "current", "deprecated"

#### Schema Validation and Code Generation

Retrieve detailed OpenAPI schema specifications to enable:

*   Request/Response Validation: Validate API requests and responses against the official schema.
*   Mock Server Creation: Generate mock servers for testing and development.
*   API Contract Testing: Ensure your implementations comply with the SCAPI specifications.

#### Version Management and Migration Planning

Track schema versions and plan migrations by:

*   Version Comparison: Compare different versions of the same API to understand changes.
*   Deprecation Tracking: Identify deprecated schemas and plan migration strategies.
*   Breaking Change Detection: Analyze schema differences to identify potential breaking changes.
*   Rollback Planning: Access historical schema versions for rollback scenarios.

#### Development Workflow Integration

Integrate schema access into your development workflows:

*   CI/CD Pipeline Integration: Validate API implementations against current schemas during build processes.
*   Local Development: Provide developers with up-to-date schema definitions for better IDE support.
*   Testing Automation: Generate comprehensive test suites based on schema definitions.
*   API Gateway Configuration: Configure API gateways with current schema definitions for validation and routing.

**Version:** 1.0.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/scapi-schemas/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.scapi-schemas: SCAPI schema READONLY 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 known SCAPI schema definitions.

`GET /organizations/{organizationId}/schemas`

Operation ID: `getSchemaList`. Security: AmOAuth2 (sfcc.scapi-schemas).

#### 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
    ```
    
*   `apiFamily` (query, ApiFamily) The API family
*   `apiName` (query, ApiName) The API name
*   `apiVersion` (query, ApiVersion) The API version
*   `cartridgeName` (query, CartridgeName) The cartridge name
*   `status` (query, string) The schema status  
    Allowed values: `current`, `deprecated`. Example: `current`.

#### Responses

*   **200** List of known SCAPI schema definitions successfully retrieved.
    
    Media type: `application/json`. Schema: `SchemaListResult`.
    
    _Example: SchemaListSuccess_
    
    ```
    {
      "limit": 1,
      "total": 3,
      "filter": {
        "apiFamily": "product",
        "apiName": "shopper-products",
        "apiVersion": "v1",
        "status": "current"
      },
      "data": [
        {
          "schemaVersion": "1.0.25",
          "apiFamily": "product",
          "apiName": "shopper-products",
          "apiVersion": "v1",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
        }
      ]
    }
    ```
    
    _Example: SchemaListSuccessNoFilter_
    
    ```
    {
      "limit": 3,
      "total": 3,
      "data": [
        {
          "schemaVersion": "1.0.25",
          "apiFamily": "product",
          "apiName": "shopper-products",
          "apiVersion": "v1",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
        },
        {
          "schemaVersion": "2.1.0",
          "apiFamily": "checkout",
          "apiName": "shopper-baskets",
          "apiVersion": "v2",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/checkout/shopper-baskets/v2"
        },
        {
          "schemaVersion": "1.5.12",
          "apiFamily": "customer",
          "apiName": "customers",
          "apiVersion": "v1",
          "status": "deprecated",
          "link": "https://api.example.com/scapi/schemas/customer/customers/v1"
        }
      ]
    }
    ```
    
*   **400** Value constraint violation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/value-constraint-violation",
      "title": "Bad Request",
      "detail": "Value for parameter 'apiFamily' violates API constraint '^[a-z0-9-]+$'"
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get a SCAPI schema specification.

`GET /organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}`

Operation ID: `getSchemaDetails`. Security: AmOAuth2 (sfcc.scapi-schemas).

#### 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
    ```
    
*   `apiFamily` (path, ApiFamily, required) The API family
*   `apiName` (path, ApiName, required) The API name
*   `apiVersion` (path, ApiVersion, required) The API version
*   `expand` (query, array of string, style: form, explode: false) Optional schema expansion e.g. 'custom\_properties'.  
    Items: Allowed values: `custom_properties`. Example: `custom_properties`.
    
    _Example_
    
    ```
    [
      "custom_properties"
    ]
    ```
    

#### Responses

*   **200** SCAPI schema specifications successfully retrieved.
    
    Media type: `application/json`. Schema: `any`.
    
    Type: `any`.
    
    _Example_
    
    ```
    {}
    ```
    
*   **400** Value constraint violation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as GET /organizations/{organizationId}/schemas 400 response._
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ResourceNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Resource Not Found",
      "detail": "Could not find requested resource"
    }
    ```
    

## 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`.

### ApiFamily

The API family name

Type: `string`.

Maximum length: 50. Pattern: ^\[a-z0-9-\]+$. Example: `product`.

### ApiName

The API name

Type: `string`.

Maximum length: 200. Pattern: ^\[a-z0-9-\]+$. Example: `shopper-products`.

### ApiVersion

The API version

Type: `string`.

Pattern: ^v\\d+$. Example: `v1`.

### CartridgeName

The cartridge name

Type: `string`.

Pattern: ^\[a-z\_\]\[a-z0-9\_\]\*$. Example: `my_cartridge`.

### SchemaListResult

Includes all fields of `ResultBase`.

*   `filter` (_ScapiSchemaFilter_)
*   `data` (_array of SchemaListItem_) List containing all filtered schema entries.

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

### ScapiSchemaFilter

*   `apiFamily` (_ApiFamily_)
*   `apiName` (_ApiName_)
*   `apiVersion` (_ApiVersion_)
*   `cartridgeName` (_CartridgeName_)
*   `status` (_string_)  
    Allowed values: `current`, `deprecated`. Example: `current`.

### SchemaListItem

*   `schemaVersion` (_string_) Semantic OAS schema version  
    Pattern: ^\\d+\\.\\d+\\.\\d+$. Example: `1.0.0`.
*   `apiFamily` (_string_) The API family name  
    Maximum length: 50. Pattern: ^\[a-z0-9-\]+$. Example: `product`.
*   `apiName` (_string_) The API name  
    Maximum length: 200. Pattern: ^\[a-z0-9-\]+$. Example: `shopper-products`.
*   `apiVersion` (_string_) The API version  
    Pattern: ^v\\d+$. Example: `v1`.
*   `cartridgeName` (_string_) The cartridge name (only for Custom APIs)  
    Pattern: ^\[a-z\_\]\[a-z0-9\_\]\*$. Example: `my_cartridge`.
*   `status` (_string_)  
    Allowed values: `current`, `deprecated`. Example: `deprecated`.
*   `link` (_string_) The URL to the SCAPI schema detail endpoint  
    Maximum length: 2048. Example: `https://api.example.com/scapi/schemas/customer/customers/v1`.

### 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`.