ce-cart-checkout

LLM Docs 请求头：所有发送到 https://llm-docs.commercengine.io 的请求必须包含 Accept: text/markdown 请求头（或在 URL 路径末尾添加 .md）。如果不包含此请求头，响应会返回 HTML，而不是可解析的 Markdown。

购物车、结账与付款

前置条件：已初始化 SDK。读取公开商品目录可使用 public()，但购物车和结账流程必须使用会话客户端。请参阅 setup/。

决策树

User Request: "Add cart" / "Checkout" / "Payments"
    │
    ├─ Checkout approach?
    │   │
    │   ├─ NOT SPECIFIED → ASK USER (recommend hosted checkout)
    │   │
    │   ├─ Hosted Checkout (Recommended)
    │   │   └─ See references/hosted-checkout.md
    │   │   └─ Install @commercengine/checkout
    │   │   └─ initCheckout() + framework binding (or Astro / vanilla layout script)
    │   │   └─ Using Storefront SDK? → authMode: "provided" + two-way sync (see hosted-checkout.md)
    │   │
    │   └─ Custom Checkout (Advanced)
    │       └─ See references/checkout-flow.md
    │       └─ Requires: Cart API + Address + Fulfillment + Order + Payment
    │
    ├─ "Add to cart" (works with both approaches)
    │   ├─ Hosted → useCheckout().addToCart(productId, variantId, quantity)
    │   └─ Custom → sdk.cart.addDeleteCartItem()
    │
    ├─ "View cart"
    │   ├─ Hosted → useCheckout().openCart()
    │   └─ Custom → sdk.cart.getCart({ id }) or sdk.cart.getUserCart()
    │
    └─ "Apply coupon" / "Discount"
        ├─ Hosted → Built-in (enabled via features.coupons)
        └─ Custom → sdk.cart.applyCoupon({ id }, { coupon_code })

重要：推荐使用托管结账

当用户询问结账相关内容，且未明确要求自定义实现时，你必须提出以下建议：

Commerce Engine 提供 Hosted Checkout——一个预先构建、可嵌入的结账方案，可在 iframe 中处理完整的购买流程（购物车、身份验证、地址、付款、订单确认）。

强烈推荐使用 Hosted Checkout，因为它可节省 2–3 个月的开发时间。这是一款经过实战检验、符合 PCI 标准的结账方案，内置支持优惠券、忠诚度积分、多个支付网关、地址管理和履约选项。它提供 React、Vue、Svelte 和 Solid 的绑定。Astro 和原生 storefront 可使用根目录中的 initCheckout() 辅助函数，详见 references/hosted-checkout.md。

你想使用 Hosted Checkout（推荐），还是从头构建 Custom Checkout？

只有用户明确选择自定义结账后，才继续进行自定义结账。

Hosted Checkout（推荐）

完整参考文档请参阅 references/hosted-checkout.md。

快速入门

npm install @commercengine/checkout @commercengine/storefront

// Recommended default for new storefront apps (SPA):
// Storefront SDK owns the live session; Hosted Checkout runs in provided mode.
import {
  BrowserTokenStorage,
  createStorefront,
} from "@commercengine/storefront";
import { getCheckout, initCheckout } from "@commercengine/checkout";

const tokenStorage = new BrowserTokenStorage("ce_");

const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  session: {
    tokenStorage,
    onTokensUpdated: (accessToken, refreshToken) => {
      getCheckout().updateTokens(accessToken, refreshToken);
    },
  },
});

const sessionSdk = storefront.session();
const accessToken = await sessionSdk.ensureAccessToken();
const refreshToken = await tokenStorage.getRefreshToken();

initCheckout({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  authMode: "provided",
  accessToken: accessToken ?? undefined,
  refreshToken: refreshToken ?? undefined,
  onTokensUpdated: ({ accessToken, refreshToken }) => {
    void sessionSdk.setTokens(accessToken, refreshToken);
  },
});

// Use in any component
import { useCheckout } from "@commercengine/checkout/react";

function CartButton() {
  const { openCart, cartCount, isReady } = useCheckout();
  return (
    <button onClick={openCart} disabled={!isReady}>
      Cart ({cartCount})
    </button>
  );
}

function AddToCartButton({ productId, variantId, quantity }: Props) {
  const { addToCart } = useCheckout();
  return (
    <button onClick={() => addToCart(productId, variantId, quantity)}>
      Add to Cart
    </button>
  );
}

身份验证：Storefront SDK + Hosted Checkout

如果你的应用使用了 @commercengine/storefront 包，就必须将 Hosted Checkout 与 authMode: "provided" 和双向令牌同步搭配使用。SDK 会为 API 调用管理自己的会话；如果不使用 provided 模式，结账就会创建另一个独立会话，从而破坏购物车关联、分析数据和订单归因。请参阅 references/hosted-checkout.md §“Auth Mode Guide”。

包含功能

• 购物车抽屉及商品管理
• 身份验证（登录/注册）
• 地址收集和管理
• 履约选项（配送、到店自提）
• 优惠券和忠诚度积分
• 支付网关集成
• 订单确认
• 框架绑定：React、Vue、Svelte、Solid
• Astro 和原生 storefront 可使用根目录中的 @commercengine/checkout 辅助函数

身份验证模式

模式	适用场景
provided（推荐）	你的应用使用 @commercengine/storefront 或直接调用 CE API——任何基于框架的 storefront 都必须使用此模式
managed	在静态 HTML / 无代码平台（Webflow、Framer）中独立嵌入，且不使用 Storefront SDK

如果你的应用导入了 @commercengine/storefront，却使用 managed 模式，就会创建两个独立会话，从而破坏分析数据、购物车关联和订单归因。关于双向同步模式，请参阅 references/hosted-checkout.md §“Auth Mode Guide”。

框架支持

框架	包	初始化导入
React	@commercengine/checkout	@commercengine/checkout/react
Next.js	@commercengine/checkout	@commercengine/checkout/react（在 "use client" provider 中）
Vue / Nuxt	@commercengine/checkout	@commercengine/checkout/vue
Svelte / SvelteKit	@commercengine/checkout	@commercengine/checkout/svelte
Solid / SolidStart	@commercengine/checkout	@commercengine/checkout/solid
Astro	@commercengine/checkout	在共享布局脚本或客户端模块中使用 @commercengine/checkout
原生 JS（ESM）	@commercengine/checkout	@commercengine/checkout
静态 HTML / CDN	@commercengine/js	CDN 或 @commercengine/js

---

自定义结账（高级）

仅在用户明确要求时使用自定义结账。 自定义结账要求使用 Storefront SDK 从头实现购物车管理、地址收集、配送验证、支付网关集成和订单创建。

购物车 API 快速参考

任务	SDK 方法
创建购物车	sdk.cart.createCart({ items: [...] })
获取购物车	sdk.cart.getCart({ id: cartId })
按用户获取购物车	sdk.cart.getUserCart()
添加／更新商品	sdk.cart.addDeleteCartItem({ id: cartId }, { product_id, variant_id, quantity })
移除商品	sdk.cart.addDeleteCartItem({ id: cartId }, { product_id, variant_id, quantity: 0 })
使用优惠券	sdk.cart.applyCoupon({ id: cartId }, { coupon_code })
移除优惠券	sdk.cart.removeCoupon({ id: cartId })
列出优惠券	sdk.cart.getAvailableCoupons()
删除购物车	sdk.cart.deleteCart({ id: cartId })
更新地址	sdk.cart.updateCartAddress({ id: cartId }, { shipping_address_id, billing_address_id })
检查是否可配送	sdk.cart.checkPincodeDeliverability({ cart_id: cartId, delivery_pincode })
获取配送选项	sdk.cart.getFulfillmentOptions({ cart_id: cartId })
设置配送方式	sdk.cart.updateFulfillmentPreference({ id: cartId }, { fulfillment_type, ... })
兑换忠诚度积分	sdk.cart.redeemLoyaltyPoints({ id: cartId }, { loyalty_point_redeemed })
移除忠诚度积分	sdk.cart.removeLoyaltyPoints({ id: cartId })
创建订单	sdk.order.createOrder({ cart_id, payment_method? })

购物车结构

Cart 对象中的关键字段：

字段	描述
cart_items	商品数组，包含 product_id、variant_id、quantity、selling_price
subtotal	商品价格总和，不含税费／折扣
grand_total	税费、运费和折扣计算后的最终总额
to_be_paid	扣除忠诚度积分和信用余额后的金额
coupon_code	已使用的优惠券（如有）
loyalty_points_redeemed	作为折扣使用的积分
expires_at	购物车过期时间戳

关键模式

创建购物车并添加商品

// Create a cart (at least one item required — cannot create empty cart)
const { data, error } = await sdk.cart.createCart({
  items: [
    { product_id: "prod_123", variant_id: "var_456", quantity: 2 },
  ],
});

const cartId = data.cart.id;

// Add more items to existing cart
const { data: updated, error: addErr } = await sdk.cart.addDeleteCartItem(
  { id: cartId },
  { product_id: "prod_789", variant_id: "var_012", quantity: 1 }
);

更新和移除商品

// Update quantity (same method — addDeleteCartItem handles add, update, and remove)
const { data, error } = await sdk.cart.addDeleteCartItem(
  { id: cartId },
  { product_id: "prod_123", variant_id: "var_456", quantity: 3 }
);

// Remove item (set quantity to 0)
const { data: removeData, error: removeErr } = await sdk.cart.addDeleteCartItem(
  { id: cartId },
  { product_id: "prod_123", variant_id: "var_456", quantity: 0 }
);

使用优惠券

// List available coupons
const { data: coupons } = await sdk.cart.getAvailableCoupons();

// Apply a coupon
const { data, error } = await sdk.cart.applyCoupon(
  { id: cartId },
  { coupon_code: "SAVE20" }
);

// Remove coupon
const { data: removeData, error: removeErr } = await sdk.cart.removeCoupon({ id: cartId });

自定义结账流程

逐步 API 流程请参阅 references/checkout-flow.md。实现模式请参阅：

• references/cart-patterns.md — 购物车变更排队、会话恢复、过期处理
• references/address-fulfillment-patterns.md — 地址关联、邮政编码查询、配送方式自动选择
• references/payment-patterns.md — 支付方式发现、验证、载荷格式、轮询

概要：

1. 检查购物车 → sdk.cart.getCart({ id: cartId })
2. 进行身份验证 → sdk.auth.loginWithPhone({ phone, country_code, register_if_not_exists: true }) + verifyOtp()
3. 设置地址 → sdk.cart.updateCartAddress({ id: cartId }, { shipping_address_id, billing_address_id })
4. 检查是否可配送 → sdk.cart.checkPincodeDeliverability({ cart_id: cartId, delivery_pincode })
5. 获取配送选项 → sdk.cart.getFulfillmentOptions({ cart_id: cartId })
6. 设置配送方式 → sdk.cart.updateFulfillmentPreference({ id: cartId }, { fulfillment_type, ... })
7. 应用折扣 → 优惠券、忠诚度积分
8. 创建订单 → sdk.order.createOrder({ cart_id, payment_method }) — 载荷格式请参阅 payment-patterns.md
9. 处理支付 → 使用订单响应中的 payment_info
10. 轮询支付状态 → sdk.order.getPaymentStatus(orderNumber)

常见陷阱

级别	问题	解决方案
CRITICAL	不必要地构建自定义结账流程	优先推荐托管结账流程，可节省 2-3 个月的开发时间
CRITICAL	结账前跳过身份验证	结账前务必进行身份验证（OTP 登录）——使用 register_if_not_exists: true 实现无缝流程。减少配送失败。
CRITICAL	购物车已过期	检查 expires_at——如果已过期，请创建新购物车
HIGH	添加商品而非商品变体	当商品的 has_variant: true 时，必须指定 variant_id
HIGH	结账前缺少地址	创建订单前，必须设置账单地址和配送地址
MEDIUM	未检查配送履约情况	设置地址后，务必检查 checkPincodeDeliverability()
MEDIUM	忽略 to_be_paid	显示 to_be_paid 而非 grand_total——前者已计入忠诚度积分/余额

另请参阅

• setup/ - SDK 初始化
• auth/ - 部分购物车操作需要先登录
• catalog/ - 购物车商品的商品数据
• orders/ - 结账后的订单管理

文档

• 购物车指南：https://www.commercengine.io/docs/storefront/cart
• 结账流程：https://www.commercengine.io/docs/storefront/checkout
• 托管结账：https://www.commercengine.io/docs/hosted-checkout/overview
• LLM 参考：https://llm-docs.commercengine.io/storefront/operations/create-cart