ce-cart-checkout

LLM Docs ヘッダー：https://llm-docs.commercengine.io へのすべてのリクエストには、Accept: text/markdown ヘッダーを必ず含める必要があります（または URL パスに .md を追加してください）。含めない場合、解析可能な Markdown ではなく HTML が返されます。

カート、チェックアウト、決済

前提条件：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 は、購入フロー全体（カート、認証、住所、決済、注文確認）を iframe 内で処理する、すぐに使える埋め込み型の ホステッドチェックアウト を提供しています。

開発期間を 2～3 か月短縮できるため、ホステッドチェックアウトを強く推奨します。実績が豊富で PCI に準拠したチェックアウトで、クーポン、ロイヤルティポイント、複数の決済ゲートウェイ、住所管理、フルフィルメントオプションが標準でサポートされています。React、Vue、Svelte、Solid 用のバインディングが付属します。Astro とバニラのストアフロントでは、references/hosted-checkout.md に記載されているルートの initCheckout() ヘルパーを使用してください。

ホステッドチェックアウト（推奨）を使用しますか？ それとも、カスタムチェックアウトを一から構築しますか？

ユーザーが明示的に選択した場合に限り、カスタムチェックアウトに進んでください。

ホステッドチェックアウト（推奨）

完全なリファレンスについては、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>
  );
}

認証：ストアフロント SDK + ホステッドチェックアウト

アプリで @commercengine/storefront パッケージを少しでも使用している場合は、authMode: "provided" と双方向のトークン同期を使用したホステッドチェックアウトを必ず使用してください。SDK は API 呼び出し用の独自のセッションを管理しています。provided モードを使用しないと、チェックアウトで独立した 2 つ目のセッションが作成され、カートの関連付け、分析、注文の帰属に問題が発生します。references/hosted-checkout.md の「Auth Mode Guide」を参照してください。

含まれる機能

• 商品管理機能付きカートドロワー
• 認証（ログイン／登録）
• 住所の収集と管理
• フルフィルメントオプション（配送、店舗での受け取り）
• クーポンとロイヤルティポイント
• 決済ゲートウェイとの統合
• 注文確認
• フレームワークバインディング：React、Vue、Svelte、Solid
• ルートの @commercengine/checkout ヘルパーを使用した Astro とバニラのストアフロント

認証モード

モード	使用する場面
provided（推奨）	アプリで @commercengine/storefront を使用する場合、または CE API を直接呼び出す場合。フレームワークベースのストアフロントでは必須です
managed	Storefront SDK を使用しない静的 HTML／ノーコードプラットフォーム（Webflow、Framer）への単独埋め込み

アプリで @commercengine/storefront をインポートしており、managed モードを使用している場合、2 つの独立したセッションが作成されます。これにより、分析、カートの関連付け、注文の帰属に問題が発生します。双方向同期のパターンについては、references/hosted-checkout.md の「Auth Mode Guide」を参照してください。

フレームワークのサポート

フレームワーク	パッケージ	初期化インポート
React	@commercengine/checkout	@commercengine/checkout/react
Next.js	@commercengine/checkout	"use client" プロバイダー内の @commercengine/checkout/react
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)

よくある落とし穴

レベル	問題	解決策
重大	不必要にカスタムのチェックアウトを構築する	まずホスト型チェックアウトを推奨してください。開発時間を2～3か月節約できます
重大	チェックアウト前の認証を省略する	チェックアウト前に必ず認証（OTP ログイン）を行ってください。シームレスなフローには register_if_not_exists: true を使用します。配送失敗を減らせます。
重大	カートの有効期限切れ	expires_at を確認し、有効期限が切れている場合は新しいカートを作成します
高	バリアントではなく商品を追加する	商品の has_variant: true の場合、variant_id を指定する必要があります
高	チェックアウト前に住所が未設定	注文を作成する前に、請求先住所／配送先住所を設定する必要があります
中	配送可否を確認しない	住所を設定した後、必ず checkPincodeDeliverability() を確認してください
中	to_be_paid を無視する	grand_total ではなく to_be_paid を表示してください。ロイヤルティ／クレジットが反映されます

関連項目

• 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