Skip to content

Latest commit

 

History

History
229 lines (160 loc) · 7.38 KB

scapi-schemas.md

File metadata and controls

229 lines (160 loc) · 7.38 KB

SCAPI Schemas

Commands for browsing and retrieving SCAPI (Salesforce Commerce API) schema specifications.

Global SCAPI Schemas Flags

These flags are available on all SCAPI Schemas commands:

Flag Environment Variable Description
--tenant-id SFCC_TENANT_ID (Required) Organization/tenant ID
--short-code SFCC_SHORTCODE SCAPI short code

Authentication

SCAPI Schemas commands require an Account Manager API Client with OAuth credentials.

Required Scopes

The following scopes are automatically requested by the CLI:

Scope Description
sfcc.scapi-schemas Access to SCAPI Schemas API
SALESFORCE_COMMERCE_API:<tenant_id> Tenant-specific access scope

Configuration

# Set credentials via environment variables
export SFCC_CLIENT_ID=my-client
export SFCC_CLIENT_SECRET=my-secret
export SFCC_TENANT_ID=zzxy_prd
export SFCC_SHORTCODE=kv7kzm78

# Or provide via flags
b2c scapi schemas list --client-id xxx --client-secret xxx --tenant-id zzxy_prd

For complete setup instructions, see the Authentication Guide.

b2c scapi schemas list

List available SCAPI schemas with optional filtering.

Usage

b2c scapi schemas list --tenant-id <TENANT_ID>

Flags

Flag Description Default
--tenant-id (Required) Organization/tenant ID
--api-family Filter by API family (e.g., product, checkout, search)
--api-name Filter by API name (e.g., shopper-products, shopper-baskets)
--api-version Filter by API version (e.g., v1)
--status, -s Filter by schema status (current, deprecated)
--columns, -c Columns to display (comma-separated)
--extended, -x Show all columns including extended fields false
--json Output results as JSON false

Available Columns

Default columns: apiFamily, apiName, apiVersion, status

Extended columns (shown with --extended): schemaVersion, link

Examples

# List all available SCAPI schemas
b2c scapi schemas list --tenant-id zzxy_prd

# Filter by API family
b2c scapi schemas list --tenant-id zzxy_prd --api-family product

# Filter by API name
b2c scapi schemas list --tenant-id zzxy_prd --api-name shopper-products

# Filter by status
b2c scapi schemas list --tenant-id zzxy_prd --status current
b2c scapi schemas list --tenant-id zzxy_prd --status deprecated

# Show extended columns
b2c scapi schemas list --tenant-id zzxy_prd --extended

# Output as JSON
b2c scapi schemas list --tenant-id zzxy_prd --json

Output

Default table output:

Found 15 schema(s):

API Family  API Name          Version  Status
───────────────────────────────────────────────
product     shopper-products  v1       current
checkout    shopper-baskets   v2       current
search      shopper-search    v1       current
customer    shopper-customers v1       current
...

b2c scapi schemas get

Get a specific SCAPI schema with optional selective expansion.

Usage

b2c scapi schemas get <apiFamily> <apiName> <apiVersion> --tenant-id <TENANT_ID>

Arguments

Argument Description
apiFamily API family (e.g., product, checkout, search)
apiName API name (e.g., shopper-products, shopper-baskets)
apiVersion API version (e.g., v1)

Flags

Flag Description Default
--tenant-id (Required) Organization/tenant ID
--expand-paths Paths to fully expand (comma-separated)
--expand-schemas Schema names to fully expand (comma-separated)
--expand-examples Example names to fully expand (comma-separated)
--expand-custom-properties Expand custom properties true
--no-expand-custom-properties Do not expand custom properties
--expand-all Return full schema without collapsing false
--list-paths List available paths and exit false
--list-schemas List available schema names and exit false
--list-examples List available example names and exit false
--yaml Output as YAML instead of JSON false
--json Output wrapped JSON with metadata false

Schema Collapsing

By default, schemas are output in a collapsed/outline format optimized for context efficiency (ideal for agentic use cases and LLM consumption):

  • Paths: Show only HTTP methods available: {"/products": ["get"], "/products/{id}": ["get"]}
  • Schemas: Show only schema names: {"Product": {}, "ProductResult": {}}
  • Examples: Show only example names: {"product-example": {}}

Use the --expand-* flags for selective expansion or --expand-all for the full, unmodified schema.

Examples

# Get collapsed/outline schema (default - context efficient)
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd

# Get full schema without collapsing
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-all

# Expand specific paths only
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-paths /products,/products/{productId}

# Expand specific schemas only
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-schemas Product,ProductResult

# Expand specific examples only
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-examples product-example

# Combine selective expansions
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --expand-paths /products --expand-schemas Product

# List available paths in the schema
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-paths

# List available schema names
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-schemas

# List available examples
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --list-examples

# Output as YAML
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --yaml

# Output wrapped JSON with metadata
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --json

# Disable custom properties expansion
b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --no-expand-custom-properties

Output Formats

Default (raw JSON to stdout): The schema is output directly to stdout as JSON. Use shell redirection to save to a file:

b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd > schema.json

YAML format (--yaml): Output as YAML for readability:

b2c scapi schemas get product shopper-products v1 --tenant-id zzxy_prd --yaml > schema.yaml

Wrapped JSON (--json): Output includes metadata wrapper:

{
  "apiFamily": "product",
  "apiName": "shopper-products",
  "apiVersion": "v1",
  "schema": { ... }
}

Notes

  • The collapsed output significantly reduces context size while preserving structure, making it ideal for AI/LLM consumption
  • Use --list-paths to discover available paths before using --expand-paths
  • Use --list-schemas to discover available schema names before using --expand-schemas
  • Custom properties expansion is enabled by default and fetches tenant-specific custom attributes