SCAPI Schema API

The SCAPI Schema API provides developers with programmatic access to OpenAPI Specification (OAS) definitions for both System and Custom APIs. This powerful tool enables:

API discovery: Find available APIs, their versions, and endpoints in a structured format.
Schema validation: Validate API requests and responses against defined schemas.
Client generation: Generate client libraries and stubs for faster integration.
Documentation: Create interactive API documentation from schema definitions.
Data model introspection: Understand data structures across APIs for transformations and migrations.

The SCAPI Schema API provides two main endpoints:

List endpoint: Returns a directory of available API schemas with filtering options
Detail endpoint: Returns the complete OpenAPI schema for a specific API

These endpoints allow you to access schema information for both System APIs (built-in SCAPI endpoints) and Custom APIs (your own API implementations).

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 SCAPI Schema API requires authentication using the Account Manager OAuth 2.0 flow with the required scope: sfcc.scapi-schemas (read-only). You must include the relevant scope(s) in the client ID used to generate the token. For details, see the Authorization Scopes Catalog.

For detailed setup instructions, see the Authorization for Admin APIs guide.

Use this endpoint to discover available API schemas and filter by various criteria.

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`
`apiFamily`	Query	No	Filter by API family, for example: `checkout`
`apiName`	Query	No	Filter by API name, for example: `shopper-baskets`
`apiVersion`	Query	No	Filter by API version, for example: `v1`
`status`	Query	No	Filter by status: `current` or `deprecated`

The endpoint returns a JSON object containing:

total: Total number of schemas available in the system
limit: Number of schemas included in this response (after filtering)
filter: Object containing applied filters (only present when filters are used)
data: Array of schema objects with summary information

Each schema object in the list includes:

Field	Description
`schemaVersion`	Version of the schema specification, for example: `1.0.25`
`apiFamily`	API family name, for example: `checkout`
`apiName`	API name, for example: `shopper-baskets`
`apiVersion`	API version, for example: `v1`
`status`	Schema status: `current` or `deprecated`
`link`	URL to access the complete schema definition

Use this endpoint to retrieve the complete OpenAPI schema for a specific API.

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`
`apiFamily`	Path	Yes	API family name, for example: `checkout`
`apiName`	Path	Yes	API name, for example: `shopper-baskets`
`apiVersion`	Path	Yes	API version, for example: `v1`
`expand`	Query	No	Controls which metadata fields are included in the schema response. Accepts multiple comma-separated values. See "Expansion Parameters" section below for details.

The endpoint returns the complete OpenAPI schema definition in JSON format, including:

API information (title, version, description)
Server configurations
Path definitions
Operation details
Parameter specifications
Request/response schemas
Security requirements

The expand query parameter allows you to include additional metadata and information in the OpenAPI schema response. By default, the API returns a streamlined schema optimized for code generation and validation. Use expansions to add documentation, examples, and other metadata fields.

Supported Expansion Values:

Value	Description	What It Adds
`all`	Complete schema with all available metadata	Includes all metadata fields - descriptions, examples, summaries, titles, tags, and external documentation links.
`descriptions`	Detailed field descriptions	Adds `description` properties throughout the schema to document fields, operations, and parameters.
`examples`	Example values and data	Adds `example` and `examples` properties to illustrate expected values and request/response structures.
`external_docs`	External documentation links	Adds `externalDocs` properties with links to additional documentation resources.
`summaries`	Operation summaries	Adds `summary` properties to operations providing brief descriptions of what they do.
`tags`	API organization tags	Adds `tags` properties to categorize and organize operations.
`titles`	Human-readable titles	Adds `title` properties throughout the schema for better readability.
`custom_properties`	Custom attribute definitions	Adds custom attribute definitions (properties prefixed with `c_`) for System APIs - enables validation of custom fields.

Using Multiple Expansions:

Combine multiple expansion values by separating them with commas to customize exactly which metadata you need:

Important Notes:

Default response: Returns a streamlined schema with core structure and data types, optimized for validation and code generation
all expansion: Convenient way to get the complete schema with all available metadata
custom_properties expansion: Only applicable to System APIs; adds custom attribute definitions to component schemas
Invalid values: Result in a 400 Bad Request error with details about the invalid parameter

Examples:

expand=all - Returns schema with all metadata fields included.
expand=descriptions,examples - Returns schema with descriptions and examples only.
expand=custom_properties - Returns schema enriched with custom attribute definitions.
expand=descriptions,custom_properties - Returns schema with descriptions and custom attributes.

Get information about all available API schemas:

Response:

Get schemas for a specific API family:

Response:

Retrieve the complete OpenAPI schema for a specific API:

Response:

Retrieve a schema with custom properties:

Retrieve a schema with multiple metadata fields:

Retrieve a schema with all metadata fields included:

Combine custom attribute enrichment with descriptive metadata:

If you provide an invalid expansion parameter, the API returns a detailed error:

Response:

The API returns these standard HTTP status codes:

200: Successful request
400: Invalid filter parameter or invalid expansion parameter
401: Authentication required
403: Insufficient permissions (missing required scope)
404: Schema not found

Generate interactive API documentation:

Retrieve schema definitions using the SCAPI Schema API.
Feed the schema into documentation tools like Swagger UI or Redocly.
Host the documentation for your development team.

Generate client libraries for your APIs:

Retrieve schema definitions using the SCAPI Schema API.
Use OpenAPI code generators to create client SDKs in languages like JavaScript, Java, or Python.
Distribute these SDKs to your development teams.

Implement robust API testing:

Retrieve schema definitions using the SCAPI Schema API.
Import schemas into testing tools like Postman or SoapUI.
Validate requests and responses against the schema definitions.

Build an API catalog for your organization:

Retrieve all schema definitions using the SCAPI Schema API.
Index the APIs by family, name, version, and endpoints.
Create a searchable registry for developers to discover available APIs.

Custom APIs: Overview of Custom API development
Custom API Status Report: Monitor the registration status of your Custom API endpoints.
Authorization for SCAPI Admin APIs: Set up authentication for Schema API endpoints.