SCAPI Admin APIs Skill | Agent Skills

SCAPI Admin APIs

This skill guides you through consuming Admin APIs for backend integrations, data synchronization, and management operations. Admin APIs are designed for server-to-server integration, not storefront use.

Note: For shopper-facing APIs (products, baskets, checkout), see b2c-scapi-shopper. This skill focuses on admin/backend operations.

Overview

Admin APIs are designed for backend systems and integrations:

Client: Backend services, ETL pipelines, management tools
Authentication: Account Manager OAuth (client credentials)
Response Time: < 60 seconds (HTTP 504 if exceeded)
Usage: Moderate frequency, batch operations preferred

Base URL Structure

https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}

Example:

https://kv7kzm78.api.commercecloud.salesforce.com/product/products/v1/organizations/f_ecom_zzte_053/products/25518823M

Note: Admin APIs typically don't require siteId parameter (unlike Shopper APIs).

Authentication

Admin APIs use Account Manager OAuth with client credentials flow.

Get Admin Token via CLI

# Get admin token (uses clientId/clientSecret from dw.json)
b2c auth token

# Get token with specific scopes
b2c auth token --auth-scope sfcc.orders --auth-scope sfcc.products

# Get token as JSON (includes expiration)
b2c auth token --json

See b2c-config skill for configuration details.

Get Token Programmatically

curl "https://account.demandware.com/dwsso/oauth2/access_token" \
  --request 'POST' \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:${TENANT_ID} ${SCOPES}"

Example:

CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TENANT_ID="zzte_053"
SCOPES="sfcc.orders sfcc.products"

TOKEN=$(curl -s "https://account.demandware.com/dwsso/oauth2/access_token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:$TENANT_ID $SCOPES" \
  | jq -r '.access_token')

Dual Scope Requirement

Admin APIs require two types of scopes:

Tenant scope: SALESFORCE_COMMERCE_API:{tenant_id} - grants access to the tenant
API-specific scopes: sfcc.catalogs, sfcc.orders.rw, etc. - grants API access

scope=SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs sfcc.products.rw

See OAuth Scopes Reference for the complete scope list.

Account Manager Setup

Log into Account Manager
Navigate to API Client > Add API Client
Configure:
- Display Name and Password (client secret)
- Assign Organizations (your B2C instances)
- Role: "Salesforce Commerce API"
- Token Endpoint Auth Method: client_secret_post
- Access Token Format: JWT
- Allowed Scopes: Add required scopes
Copy the Client ID

API Families

Products API

Manage product catalog data.

// Get product
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update product
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/${orgId}/products/${productId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            name: { default: 'Updated Product Name' },
            shortDescription: { default: 'New description' }
        })
    }
);

Required Scopes:

Read: sfcc.products
Write: sfcc.products.rw

Catalogs API

Manage catalog structure and assignments.

// List catalogs
const catalogs = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Get catalog details
const catalog = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1/organizations/${orgId}/catalogs/${catalogId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

Required Scopes:

Read: sfcc.catalogs
Write: sfcc.catalogs.rw

Orders API

Retrieve and manage orders.

// Get order by number
const order = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update order status
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1/organizations/${orgId}/orders/${orderNo}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            status: 'completed',
            shippingStatus: 'shipped'
        })
    }
);

Required Scopes:

Read: sfcc.orders
Write: sfcc.orders.rw

Inventory Availability API

Manage product inventory.

// Get inventory for a product
const availability = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records/search`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            skus: ['SKU001', 'SKU002'],
            locationIds: ['warehouse-1']
        })
    }
).then(r => r.json());

// Update inventory
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1/organizations/${orgId}/availability-records`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            records: [{
                sku: 'SKU001',
                locationId: 'warehouse-1',
                onHand: 100,
                effectiveDate: new Date().toISOString()
            }]
        })
    }
);

Required Scopes:

Read: sfcc.inventory.availability
Write: sfcc.inventory.availability.rw

Inventory IMPEX API

High-performance bulk inventory import. Use for 1000+ SKU updates.

Critical Requirements:

Files > 100MB MUST be gzip compressed
Use newline-delimited JSON (NDJSON), not comma-separated arrays
Don't run imports during location graph changes
Use delta imports (changed data only) for best performance
Future quantity values must be > 0

// Step 1: Initiate import
const importJob = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/${orgId}/availability-records/imports`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
    }
).then(r => r.json());

// Step 2: Prepare newline-delimited JSON
const ndjsonData = inventoryRecords
    .map(r => JSON.stringify({
        recordId: r.recordId || crypto.randomUUID(),
        sku: r.sku,
        locationId: r.locationId,
        onHand: r.quantity,
        effectiveDate: new Date().toISOString()
    }))
    .join('\n');

// Step 3: Upload data to the uploadLink
await fetch(importJob.uploadLink, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: ndjsonData
});

// Step 4: Monitor status
const status = await fetch(importJob.importStatusLink, {
    headers: { 'Authorization': `Bearer ${adminToken}` }
}).then(r => r.json());

Required Scope: sfcc.inventory.impex-inventory

Note: Inventory IMPEX logs don't appear in Log Center. Use correlation IDs and monitor import status directly.

See Integration Patterns Reference for bulk import best practices.

Customers API

Manage customer data.

// Search customers
const customers = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/customer/customers/v1/organizations/${orgId}/customer-search?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            query: {
                textQuery: { fields: ['email'], searchPhrase: 'john@example.com' }
            }
        })
    }
).then(r => r.json());

Required Scopes:

Read: sfcc.shopper-customers
Write: sfcc.shopper-customers.rw

Promotions API

Manage promotions and campaigns.

// Get promotion
const promotion = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${adminToken}` }
    }
).then(r => r.json());

// Update promotion
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1/organizations/${orgId}/promotions/${promotionId}?siteId=${siteId}`,
    {
        method: 'PATCH',
        headers: {
            'Authorization': `Bearer ${adminToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            enabled: true,
            startDate: '2024-06-01T00:00:00Z',
            endDate: '2024-06-30T23:59:59Z'
        })
    }
);

Required Scopes:

Read: sfcc.promotions
Write: sfcc.promotions.rw

Request Tracking

Correlation IDs

Include correlation IDs for tracking requests across systems:

const correlationId = crypto.randomUUID();

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'correlation-id': correlationId
    }
});

console.log(`Request ${correlationId} completed`);
// Search Log Center: externalID:({correlationId})

Verbose Logging

Enable verbose logging for debugging:

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${adminToken}`,
        'sfdc_verbose': 'true'
    }
});

Check Log Center under scapi.verbose category.

Note: Some Admin APIs (CDN Zones, Inventory, Shopper Context) don't log to Log Center.

Error Handling

Common Errors

| Status | Meaning | Action | |--------|---------|--------| | 400 | Bad Request | Check request body/parameters | | 401 | Unauthorized | Token expired - get new token | | 403 | Forbidden | Missing scope or tenant access | | 404 | Not Found | Resource doesn't exist | | 429 | Rate Limited | Implement backoff | | 500 | Server Error | Retry with backoff | | 504 | Timeout | Request took > 60 seconds |

Rate Limiting

Admin APIs have lower rate limits than Shopper APIs. For bulk operations:

Use batch endpoints when available
Implement exponential backoff for 429 responses
Consider inventory IMPEX for large data imports
Spread operations over time for non-urgent updates

Related Skills

b2c-config - Get admin tokens via CLI
b2c-scapi-shopper - Shopper-facing APIs
b2c-scapi-schemas - Browse OpenAPI schemas

Reference Documentation

OAuth Scopes Reference - Complete admin scope reference
Integration Patterns - ETL, sync, and bulk import patterns

Agent Skills: SCAPI Admin APIs

Install this agent skill to your local

Skill Files

SCAPI Admin APIs

Overview

Base URL Structure

Authentication

Get Admin Token via CLI

Get Token Programmatically

Dual Scope Requirement

Account Manager Setup

API Families

Products API

Catalogs API

Orders API

Inventory Availability API

Inventory IMPEX API

Customers API

Promotions API

Request Tracking

Correlation IDs

Verbose Logging

Error Handling

Common Errors

Rate Limiting

Related Skills

Reference Documentation