Back to Details

b2c-scapi-shopper

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Shopper Commerce APIs (SCAPI)

Shopper Commerce APIs (SCAPI)

This skill guides you through consuming standard Shopper APIs for building headless commerce experiences. Shopper APIs are RESTful endpoints designed for customer-facing storefronts.
Note: For creating custom API endpoints, see b2c-custom-api-development. This skill focuses on consuming standard Shopper APIs.
本技能将指导你如何使用标准Shopper API来构建无头商务体验。Shopper API是为面向客户的店面设计的RESTful端点。
注意： 如需创建自定义API端点，请查看b2c-custom-api-development。本技能重点介绍如何使用标准Shopper API。

Overview

概述

Shopper APIs are designed for frontend commerce applications:
  • Client: PWA Kit, composable storefronts, mobile apps
  • Authentication: SLAS (Shopper Login and API Access Service)
  • Response Time: < 10 seconds (HTTP 504 if exceeded)
  • CORS: Not supported - use a reverse proxy or BFF (Backend for Frontend)
Shopper API专为前端商务应用设计：
  • 客户端：PWA Kit、组合式店面、移动应用
  • 认证方式：SLAS（Shopper Login and API Access Service，购物者登录与API访问服务）
  • 响应时间：< 10秒（超时则返回HTTP 504）
  • CORS支持：不支持 - 请使用反向代理或BFF（Backend for Frontend，前端后端）

Base URL Structure

基础URL结构

https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}?siteId={siteId}
Example:
https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25518823M?siteId=RefArchGlobal
Note: Shopper Baskets API supports both 
v1
and 
v2
. Use 
v2
for newer features.
https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/{resource}?siteId={siteId}
示例：
https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25518823M?siteId=RefArchGlobal
注意： Shopper Baskets API同时支持
v1
和
v2
版本。建议使用
v2
以获取更新功能。

Configuration Values

配置参数

ValueDescriptionExample
shortCode
8-character API routing code
kv7kzm78
organizationId
Instance identifier
f_ecom_zzte_053
siteId
Site/channel name
RefArchGlobal
Find these in Business Manager: Administration > Site Development > Salesforce Commerce API Settings
参数说明示例
shortCode
8位字符的API路由编码
kv7kzm78
organizationId
实例标识符
f_ecom_zzte_053
siteId
站点/渠道名称
RefArchGlobal
可在Business Manager中找到这些参数：Administration > Site Development > Salesforce Commerce API Settings（管理 > 站点开发 > Salesforce Commerce API设置）

Authentication

认证

Shopper APIs require SLAS tokens. SLAS supports guest and registered shopper flows.
Shopper API需要SLAS令牌。SLAS支持访客和已注册购物者两种流程。

Create SLAS Client

创建SLAS客户端

bash
undefined
bash
undefined

Create client with default scopes for a shopping app

为购物应用创建带有默认权限范围的客户端

b2c slas client create
--tenant-id zzte_053
--channels RefArchGlobal
--default-scopes
--redirect-uri http://localhost:3000/callback

See [b2c-slas skill](../../b2c-cli/skills/b2c-slas/SKILL.md) for full client management.
b2c slas client create
--tenant-id zzte_053
--channels RefArchGlobal
--default-scopes
--redirect-uri http://localhost:3000/callback

如需完整的客户端管理说明，请查看[b2c-slas skill](../../b2c-cli/skills/b2c-slas/SKILL.md)。

Get Guest Token

获取访客令牌

javascript
const response = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/${orgId}/oauth2/token`,
    {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${btoa(clientId + ':' + clientSecret)}`
        },
        body: new URLSearchParams({
            grant_type: 'client_credentials',
            channel_id: siteId
        })
    }
);

const { access_token, refresh_token } = await response.json();
javascript
const response = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/${orgId}/oauth2/token`,
    {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${btoa(clientId + ':' + clientSecret)}`
        },
        body: new URLSearchParams({
            grant_type: 'client_credentials',
            channel_id: siteId
        })
    }
);

const { access_token, refresh_token } = await response.json();

Required Scopes

必需的权限范围

All Shopper API scopes must be configured on your SLAS client. See Scopes Reference for the complete list.
API FamilyScope
Products
sfcc.shopper-products
Search
sfcc.shopper-product-search
Baskets
sfcc.shopper-baskets-orders.rw
Orders
sfcc.shopper-baskets-orders
Customers
sfcc.shopper-customers.login
, 
sfcc.shopper-myaccount.rw
所有Shopper API的权限范围都必须在你的SLAS客户端上配置。完整列表请查看权限范围参考。
API家族权限范围
Products
sfcc.shopper-products
Search
sfcc.shopper-product-search
Baskets
sfcc.shopper-baskets-orders.rw
Orders
sfcc.shopper-baskets-orders
Customers
sfcc.shopper-customers.login
, 
sfcc.shopper-myaccount.rw

API Families

API家族

Shopper Products

Shopper Products

Retrieve product details, pricing, and availability.
javascript
// Get product by ID
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products/${productId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

// Get multiple products
const products = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products?ids=prod1,prod2,prod3&siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());
获取产品详情、价格和库存状态。
javascript
// 根据ID获取产品
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products/${productId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

// 获取多个产品
const products = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products?ids=prod1,prod2,prod3&siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

Shopper Search

Shopper Search

Product search and suggestions.
javascript
// Search products
const results = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/${orgId}/product-search?siteId=${siteId}&q=shirt&limit=25`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

// Get search suggestions
const suggestions = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/${orgId}/search-suggestions?siteId=${siteId}&q=shi`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());
产品搜索和搜索建议。
javascript
// 搜索产品
const results = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/${orgId}/product-search?siteId=${siteId}&q=shirt&limit=25`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

// 获取搜索建议
const suggestions = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/${orgId}/search-suggestions?siteId=${siteId}&q=shi`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

Shopper Baskets

Shopper Baskets

Create and manage shopping carts. See Checkout Flow Reference for the complete flow.
javascript
// Create basket
const basket = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/${orgId}/baskets?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
    }
).then(r => r.json());

// Add item to basket
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/${orgId}/baskets/${basketId}/items?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify([{
            productId: '25518823M',
            quantity: 1
        }])
    }
);
创建和管理购物车。完整流程请查看结账流程参考。
javascript
// 创建购物车
const basket = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/${orgId}/baskets?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({})
    }
).then(r => r.json());

// 向购物车添加商品
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/${orgId}/baskets/${basketId}/items?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify([{
            productId: '25518823M',
            quantity: 1
        }])
    }
);

Shopper Orders

Shopper Orders

Submit orders and retrieve order history.
javascript
// Create order from basket
const order = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-orders/v1/organizations/${orgId}/orders?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            basketId: basket.basketId
        })
    }
).then(r => r.json());
提交订单和获取订单历史。
javascript
// 从购物车创建订单
const order = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/checkout/shopper-orders/v1/organizations/${orgId}/orders?siteId=${siteId}`,
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            basketId: basket.basketId
        })
    }
).then(r => r.json());

Shopper Customers

Shopper Customers

Customer registration, login, and account management.
javascript
// Get customer profile (registered shopper)
const customer = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/${orgId}/customers/${customerId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());
客户注册、登录和账户管理。
javascript
// 获取客户资料（已注册购物者）
const customer = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/${orgId}/customers/${customerId}?siteId=${siteId}`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

Shopper Context API

Shopper Context API

Maintain personalization state across requests using the Shopper Context API. The 
siteId
query parameter is required for all Shopper Context operations.
javascript
// Set shopper context
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/${orgId}/shopper-context/${usid}?siteId=${siteId}`,
    {
        method: 'PUT',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            effectiveDateTime: new Date().toISOString(),
            sourceCode: 'SUMMER2024',
            customerGroupIds: ['VIP', 'Loyalty']
        })
    }
);
使用Shopper Context API在请求之间维护个性化状态。所有Shopper Context操作都必须携带
siteId
查询参数。
javascript
// 设置购物者上下文
await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/${orgId}/shopper-context/${usid}?siteId=${siteId}`,
    {
        method: 'PUT',
        headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            effectiveDateTime: new Date().toISOString(),
            sourceCode: 'SUMMER2024',
            customerGroupIds: ['VIP', 'Loyalty']
        })
    }
);

When to Set Context

何时设置上下文

  • Initial visit/login: Immediately after obtaining SLAS token
  • Token refresh: Reuse existing USID for session continuity
  • Login transitions: When shopper changes from guest to registered (or vice versa)
  • Logout: Clear context explicitly
  • 首次访问/登录：获取SLAS令牌后立即设置
  • 令牌刷新：复用现有USID以保持会话连续性
  • 登录状态切换：购物者从访客转为已注册（或反之）时
  • 登出：显式清除上下文

Quota Limits

配额限制

EnvironmentLimit
Non-production5,000 records
Production1,000,000 records
Strategies to manage quota:
  • Use lower TTL (1-2 days for registered shoppers)
  • Reuse USIDs for the same shopper
  • Explicitly log out shoppers to delete context
环境限制
非生产环境5,000条记录
生产环境1,000,000条记录
配额管理策略：
  • 使用更短的TTL（已注册购物者设置1-2天）
  • 为同一购物者复用USID
  • 购物者登出时显式删除上下文

Best Practices

最佳实践

  • Set context immediately after obtaining SLAS token
  • Use the USID from the SLAS token response
  • Context TTL: 1 day (guest), 7 days (registered)
  • Security: Use private SLAS clients only, call from BFF (not browser)
  • Don't use Shopper Context for data that's automatically set (like geolocation)
  • 获取SLAS令牌后立即设置上下文
  • 使用SLAS令牌响应中的USID
  • 上下文TTL：访客设为1天，已注册购物者设为7天
  • 安全注意：仅使用私有SLAS客户端，从BFF（而非浏览器）调用
  • 不要使用Shopper Context存储自动设置的数据（如地理位置）

Performance Optimization

性能优化

Use 
select
Parameter

使用
select
参数

Return only needed fields to reduce response size:
javascript
// Only return specific product fields
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products/${productId}?siteId=${siteId}&select=(id,name,price,images)`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());
仅返回所需字段以减小响应体积：
javascript
// 仅返回特定产品字段
const product = await fetch(
    `https://${shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/${orgId}/products/${productId}?siteId=${siteId}&select=(id,name,price,images)`,
    {
        headers: { 'Authorization': `Bearer ${accessToken}` }
    }
).then(r => r.json());

Use 
expand
Carefully

谨慎使用
expand
参数

Expansions increase response time and reduce cache effectiveness:
javascript
// Expand availability (60-second cache TTL)
const product = await fetch(
    `...?expand=availability,images,prices`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());
Consider separate requests instead of low-cache expansions.
展开操作会增加响应时间并降低缓存效率：
javascript
// 展开库存状态（缓存TTL为60秒）
const product = await fetch(
    `...?expand=availability,images,prices`,
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
).then(r => r.json());
建议使用单独请求替代低缓存的展开操作。

Enable Compression

启用压缩

Always enable HTTP compression in your client for faster responses.
See Common Patterns Reference for more optimization patterns.
请始终在客户端启用HTTP压缩以加快响应速度。
更多优化模式请查看通用模式参考。

Debugging

调试

Correlation IDs

关联ID

Include correlation IDs for request tracking:
javascript
const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${accessToken}`,
        'correlation-id': crypto.randomUUID()
    }
});

// Check response header for SCAPI-generated ID
const scapiCorrelationId = response.headers.get('sfdc_correlation_id');
Search Log Center with: 
externalID:({correlation-id})
包含关联ID以追踪请求：
javascript
const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${accessToken}`,
        'correlation-id': crypto.randomUUID()
    }
});

// 检查响应头中的SCAPI生成ID
const scapiCorrelationId = response.headers.get('sfdc_correlation_id');
在日志中心搜索：
externalID:({correlation-id})

Verbose Logging

详细日志

Enable verbose logging for debugging:
javascript
const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${accessToken}`,
        'sfdc_verbose': 'true'
    }
});
Find logs in Log Center under 
scapi.verbose
category.
启用详细日志以进行调试：
javascript
const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${accessToken}`,
        'sfdc_verbose': 'true'
    }
});
可在日志中心的
scapi.verbose
分类下找到相关日志。

Related Skills

相关技能

  • b2c-slas - Create and manage SLAS clients
  • b2c-slas-auth-patterns - Advanced auth: OTP, passkeys, session bridge
  • b2c-scapi-schemas - Browse OpenAPI schemas
  • b2c-custom-api-development - Create custom endpoints
  • b2c-slas - 创建和管理SLAS客户端
  • b2c-slas-auth-patterns - 高级认证：OTP、密钥、会话桥接
  • b2c-scapi-schemas - 浏览OpenAPI schema
  • b2c-custom-api-development - 创建自定义端点

Reference Documentation

参考文档

  • Checkout Flow - Complete basket to order workflow
  • Common Patterns - Error handling, pagination, field selection
  • Scopes Reference - Complete shopper scope reference by API family
  • 结账流程 - 从购物车到订单的完整工作流
  • 通用模式 - 错误处理、分页、字段选择
  • 权限范围参考 - 按API家族分类的完整购物者权限范围参考