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