# エージェントを通じて販売

Agentic Commerce Suite を使えば、AI エージェント経由で商品を販売できます。

> Agentic Commerce Suite はアメリカで利用できます。

Agentic Commerce Suite (ACS) を使用すると、単一の導入でエージェント経由の販売を開始できます。ACS を使用すると、商品を見つけやすくし、複数のコマースプロトコルでエージェント型の決済を受け付けることができます。また、既存のコマースシステムへの変更を最小限に抑えながら、商品、価格、在庫状況の情報をエージェントと共有できます。

プラットフォームを運営している場合は、[プラットフォーム向けガイド](https://docs.stripe.com/connect/saas/tasks/enable-in-context-selling-on-ai-agents.md)を参照してください。

## Stripe アカウントを設定する

Stripe アカウントをまだお持ちでない場合は、アカウントを[作成](https://stripe.com/register)します。メールを確認したら、ビジネスと個人情報の入力、入金用の銀行口座のリンク、二段階認証の設定を行って、決済を有効にします。次に、Stripe ダッシュボードで[エージェンティックコマースアカウント登録](https://dashboard.stripe.com/agentic-commerce)に移動します。このガイドに従って、[Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md)の作成とエージェンティックコマースの設定を行います。

## 税を設定する

[Stripe Tax](https://docs.stripe.com/tax.md) を使用して税を管理し、個々の商品に設定を適用します。[税設定ガイド](https://docs.stripe.com/tax/set-up.md?dashboard-or-api=api)に従って Stripe Tax を設定してください。[カタログフィードを作成](https://docs.stripe.com/agentic-commerce/for-sellers.md#upload-feed)する際は、商品を税務処理に関連付けるため、`stripe_product_tax_code` 列を設定します。税計算に [Anrok](https://www.anrok.com) を使用する場合は、代わりにカタログフィードの `third_party_tax_code` 列を設定してください。これらのフィールドの詳細については、[価格とプロモーションのフィールドリファレンス](https://docs.stripe.com/agentic-commerce/product-feed.md#price-and-promotions)を参照してください。

## サポートおよびリーガルポリシーの設定

[エージェンティックコマース設定](https://dashboard.stripe.com/settings/agentic-commerce)ページで、**返金および返品ポリシー**、**利用規約**、**プライバシーポリシー**へのリンクを追加します。任意で**ストアポリシー**へのリンクも追加できます。

## カタログフィードを作成

[カタログフィード](https://docs.stripe.com/agentic-commerce/product-feed.md)を作成すれば、商品と在庫のデータをエージェントと共有できます。ダッシュボードまたは API を使用してデータを送信してください。データを最新の状態に保つため、商品データは 1 日 1 回アップロードし、在庫と価格については更新頻度を高めた差分更新を送信することを推奨します。

> フィードのアップロードは、独立した非同期タスクとして処理されます。アップロードが送信された順に処理または完了するとは限りません。複数のファイルを連続してすばやくアップロードすると、後からアップロードされたものが先にアップロードされたものより先に完了することがあります。

#### API

Stripe API を使用して、商品データ CSV をアップロードします。本番更新を有効にする前に、サンドボックスを使用して解析、フィールドマッピング、データ品質を検証することをお勧めします。

> [制限付き API キー](https://docs.stripe.com/keys.md#create-restricted-api-key)を使用する場合、**商品カタログのインポート**の書き込み権限が必要です。この権限がない場合、API リクエストは `403` エラーを返します。

### インポートを作成する

`ProductCatalogImport` オブジェクトを、[商品カタログインポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して作成します。リクエストが成功すると、[ProductCatalogImport オブジェクト](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/object.md) が返され、その状態は `awaiting_upload` になります。レスポンスの `status_details.awaiting_upload.upload_url.url` フィールドには、ファイルアップロード用の署名付き URL が含まれます。

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "feed_type": "product",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_product_upload.csv"
    }
  }'
```

```json
{
  "id": "pcimprt_xxx",
  "object": "v2.commerce.product_catalog_import",
  "created": "2026-03-26T00:35:01.000Z",
  "feed_type": "product",
  "status": "awaiting_upload",
  "status_details": {
    "awaiting_upload": {
      "upload_url": {
        "expires_at": "2026-03-26T00:40:02.000Z",
        "url": "https://stripeusercontent.com/files/us-west-2/upload/wksp_xxx"
      }
    }
  },
  "livemode": true
}
```

### CSV をアップロードする

CSV を署名付き URL にアップロードします。ファイルは CSV または TSV 形式にする必要があります。各行は 1 つの商品またはバリエーションを表します。最大ファイルサイズは 4 GB です。

```curl
curl -X PUT \
  -H "Content-Type: text/csv" \
  --data-binary @"/path/to/your/file.csv" \
  "{{PRESIGNED_URL}}"
```

Stripe がファイルを受信すると、インポートは `awaiting_upload` から `processing` に移行します。Stripe はファイルを検証し、項目を取り込みます。

### フィードステータスを監視し、エラーを解決する

Stripe は商品データを処理し、検証とクリーンアップを行い、AI エージェントに送信できる形式でインデックスを作成します。インデックス作成の進捗状況は、次の 2 つの方法で監視できます。

#### API

`GET` リクエストを使用してインポートオブジェクトをポーリングし、`status` フィールドを確認します。オブジェクトが最終状態 (`succeeded`、`succeeded_with_errors`、または `failed`) になるまで、ポーリングを続けます。

```curl
curl https://api.stripe.com/v2/commerce/product_catalog/imports/{{PRODUCTCATALOGIMPORT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview"
```

インポートがエラーなしで完了すると、`succeeded` になります。ファイルが構造的には有効でも行レベルのエラーが含まれている場合、`succeeded_with_errors` になります。インポートを完了できない場合 (たとえば、ファイルがアップロードされなかった、読み取り不能である、内部エラーが発生したなどの理由で) は、`failed` になります。

インポートのステータスが `succeeded_with_errors` の場合は、エラーファイルをダウンロードできます。

1. レスポンスの `status_details.succeeded_with_errors.error_file.url` フィールドを確認します。
1. 有効期限が切れる前に、その URL から CSV を直接ダウンロードします。
1. CSV には失敗した行のみが含まれ、先頭の `stripe_error_message` 列で各エラーが説明されます。

> エラーファイル URL の有効期限は 5 分後に切れます。新しい URL を取得するには、[取得エンドポイント](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/retrieve.md)を再度呼び出してください。

#### Webhook

商品データのインデックス作成が完了すると、Stripe は最終状態を示すウェブフックイベントを送信します。`v2.commerce.product_catalog.imports.succeeded`、`v2.commerce.product_catalog.imports.succeeded_with_errors`、`v2.commerce.product_catalog.imports.failed` の各イベントをリッスンするエンドポイントを設定します。各イベントには `v2.commerce.product_catalog_import` オブジェクトが含まれます。手順について詳しくは、[ウェブフックガイド](https://docs.stripe.com/webhooks.md)を参照してください。

`v2.commerce.product_catalog.imports.succeeded` ウェブフックペイロードの例を次に示します。

```javascript
{
  "id": "evt_65THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8B",
  "object": "v2.core.event",
  "type": "v2.commerce.product_catalog.imports.succeeded",
  "created": "2026-03-26T00:40:00.000Z",
  "livemode": true,
  "reason": null,
  "related_object": {
    "id": "pcimprt_61THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8K",
    "type": "v2.commerce.product_catalog.imports",
    "url": "/v2/commerce/product_catalog/imports/pcimprt_61THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8K"
  },
  "changes": {
    "before": {"status": "PROCESSING"},
    "after": {"status": "SUCCEEDED"}
  },
  "data": {}
}
```

ウェブフックにはインポートオブジェクト全体は含まれません。`related_object.url` を使用して取得します。

```curl
curl https://api.stripe.com/v2/commerce/product_catalog/imports/{{PRODUCTCATALOGIMPORT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview"
```

インポートのステータスが `succeeded_with_errors` の場合は、エラーファイルをダウンロードできます。

1. レスポンスの `status_details.succeeded_with_errors.error_file.url` フィールドを確認します。
1. 有効期限が切れる前に、その URL から CSV を直接ダウンロードします。
1. CSV には失敗した行のみが含まれ、先頭の `stripe_error_message` 列で各エラーが説明されます。

> エラーファイル URL の有効期限は 5 分後に切れます。新しい URL を取得するには、取得エンドポイントを再度呼び出してください。

#### ダッシュボード

ダッシュボードの[フィード履歴](https://dashboard.stripe.com/agentic-commerce/feed-history)ページに移動し、商品データの CSV をアップロードします。

## カスタム注文 URL を設定する

デフォルトでは、注文が確定すると、Stripe は顧客に[支払領収書](https://docs.stripe.com/receipts.md)を返します。セルフホストの注文 URL を指定するには、以下のようにします:

1. ダッシュボードの[エージェンティックコマース設定](https://dashboard.stripe.com/settings/agentic-commerce)ページで、**領収書タイプ**ドロップダウンで**カスタムページ**を選択します。
1. **カスタムページの URL** フィールドに注文 URL を入力します。URL は `{CHECKOUT_SESSION_ID}` テンプレート変数を含んでいる必要があります。注文が確定されると、Stripe は自動的に Checkout セッション ID でこれを置き換えます。この ID を使用して Checkout Session を検索し、注文情報を表示することができます。

## 購入への対応と注文のフルフィルメント

AI チャットエージェントを介して行われた注文は、次の 3 つの方法で監視できます。

#### ダッシュボード

ダッシュボードの[取引ページ](https://dashboard.stripe.com/payments)で注文を表示します。注文は元のエージェントでタグ付けされています。エージェント名で取引をフィルタリングすることもできます。

#### Webhook

エージェントが注文を完了すると、Stripe は `checkout.session.completed` を送信します。注文ごとに一意の `checkout.session.completed` イベントを生成します。Webhook には [CheckoutSession](https://docs.stripe.com/api/checkout/sessions/object.md) オブジェクトが含まれます。`checkout.session.completed` イベントをリッスンするエンドポイントを設定します。詳細な手順については、[Webhook ガイド](https://docs.stripe.com/webhooks.md) を参照してください。

```javascript
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

// Use the secret provided by Stripe CLI for local testing
// or your webhook endpoint's secret
const endpointSecret = 'whsec_...';

app.post('/webhook', (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    // Fulfill the order using the session data
    fulfillCheckout(session.id);
  }

  response.status(200).send();
});
```

`checkout.session.completed` の webhook ペイロードの例は以下のとおりです。

```javascript
{
  "id": "evt_1SUz6YRhxngcl2jFHhAi1Wiu",
  "object": "event",
  "api_version": "2025-10-29.clover",
  "created": 1763511518,
  "data": {
    "object": {
      "id": "cs_test_a1exHOZ77Pg40P1hPtcWe2oT2xI8G9ruoQohXq6jkKldIPQaGsNSPQmOGZ",
      "object": "checkout.session",
       ...
      "total_details": {
        "amount_discount": 0,
        "amount_shipping": 0,
        "amount_tax": 0
      }
    }
  },
  "livemode": false,
  ...
  "type": "checkout.session.completed"
}
```

Webhook を受信したら、1 回の API コールですべての必須フィールドを取得します。複数のリクエストを回避するには、`Stripe-Version: 2025-12-15.preview` のプレビューヘッダーを指定して、[expand](https://docs.stripe.com/api/expanding_objects.md) リクエストパラメーターを使用してサブリソースを展開します。

```curl
curl https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}}?expand[]=line_items.data.price.product&expand[]=line_items.data.taxes&expand[]=payment_intent.latest_charge \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2025-12-15.preview"
```

`amount_total`、quantity、SKU ID など、拡張された [CheckoutSession](https://docs.stripe.com/api/checkout/sessions/object.md) のフィールドをご覧ください。

### Checkout セッションのフィールドリファレンス

| 注文フィールド                        | 利用可能なリソース                                     | API パス                                                                              |
| ------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **注文日**                        | `CheckoutSession.PaymentIntent.LatestCharge`  | `CheckoutSessions.PaymentIntent.LatestCharge.created`                               |
| **注文数量**                       | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].quantity`                                         |
| **SKU**                        | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.external_reference`                         |
| **商品説明**                       | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.description`                        |
| **単価**                         | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.unit_amount`                                |
| **税額**                         | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].Taxes[].amount`                                   |
| **税種別**                        | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].Taxes[].Rate.tax_type`                            |
| **税率**                         | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].Taxes[].Rate.percentage`                          |
| **ShippingAddress**            | `CheckoutSessions`                            | `CheckoutSessions.CollectedInformation.shipping_details`                            |
| **BillingAddress**             | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.billing_details`                       |
| **Last4**                      | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.last4`     |
| **ExpMonth**                   | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.exp_month` |
| **ExpYear**                    | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.exp_year`  |
| **CreditCardType**             | `CheckoutSessions.PaymentIntent.LatestCharge` | `CheckoutSessions.PaymentIntent.LatestCharge.payment_method_details.card.brand`     |
| **最終金額**                       | `CheckoutSessions`                            | `CheckoutSessions.amount_total`                                                     |
| **GTIN** (Private preview)     | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.identifiers.gtin`                   |
| **MPN** (Private preview)      | `CheckoutSessions`                            | `CheckoutSession.LineItems.Data[].price.product.identifiers.mpn`                    |
| **エージェント詳細** (Private preview) | `CheckoutSession.PaymentIntent`               | `CheckoutSessions.PaymentIntent.agent_details`                                      |
| **OrderNo**                    | `CheckoutSession.PaymentIntent.LatestCharge`  | `CheckoutSessions.PaymentIntent.LatestCharge.receipt_number`                        |

#### バッチ処理

各注文を個別にフルフィルメントする代わりに、[List CheckoutSessions エンドポイント](https://docs.stripe.com/api/checkout/sessions/list.md) を使用して注文を一括フルフィルメントします。

```curl
# List all successful CheckoutSessions in the last hour
curl https://api.stripe.com/v1/checkout/sessions?created[gt]={{TIMESTAMP}}&status=complete \
  -u <<YOUR_SECRET_KEY>>:
```

フルフィルメントの重複を回避するには、`starting_after` パラメーターを使用します。

```curl
curl https://api.stripe.com/v1/checkout/sessions?created[gt]={{TIMESTAMP}}&status=complete&starting_after={{LAST_SESSION_ID}} \
  -u <<YOUR_SECRET_KEY>>:
```

## 実装のテスト

ダッシュボードから[サンドボックス](https://docs.stripe.com/sandboxes.md)で直接インテグレーションをテストできます。

1. [エージェンティックコマース](https://dashboard.stripe.com/agentic-commerce)ページに移動し、 **フィードを表示** をクリックします。
1. テストする商品にカーソルを合わせ、 **テスト** をクリックします。

## AI チャットエージェントでの販売の有効化

AI インターフェース経由で販売する準備ができたら、エージェント規約を確認し、ダッシュボードでエージェントを有効にしてください。Stripe はエージェントに承認リクエストを送信し、エージェントはこれを承認する必要があります。AI チャットエージェントでの販売を一時停止または停止するには、ダッシュボードでエージェントを無効にします。

## Optional: 手動キャプチャを設定する

デフォルトでは、Stripe は購入後すぐに決済をキャプチャーします。手動キャプチャーを使用するには、ダッシュボードの[エージェンティックコマース設定](https://dashboard.stripe.com/settings/agentic-commerce)ページを開き、キャプチャーモードを手動に設定します。手動キャプチャーを有効にすると、`capture` メソッドを `PaymentIntent` で呼び出します。

```curl
curl -X POST https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/capture \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2025-09-30.preview"
```

## Optional: 注文承認フックを設定する

Stripe は、決済を確定する前に、お客様の商品カタログデータに基づいて在庫を確認し、[Radar](https://docs.stripe.com/radar.md) の設定によっては不正利用チェックを実行する場合があります。購入を完了するかどうかを制御するには、注文承認フックを設定します。決済フローを完了する前に、Stripe はお客様のサービスに承認リクエストを送信します。このリクエストは承認または拒否する必要があります。

Stripe はフックに 4 秒のタイムアウトを適用します。この時間内にフックが応答しない場合、Stripe は支払いを拒否します。

注文承認フックを設定するには:

1. ダッシュボードの [Agentic コマース設定](https://dashboard.stripe.com/settings/agentic-commerce)ページでエンドポイントを指定します。
1. **Order approvals** を有効にします。
1. エンドポイントにロジックを実装し、以下のリクエストとレスポンスの形式を使用します。

> エンドポイントが `2xx` 以外のステータスコードを返すと、Stripe はエージェントに `424` ステータスコードを返します。一部のエージェントはこれらの API リクエストを再試行する可能性があるため、エンドポイントが冪等であることを確認する必要があります。

### リクエスト形式

Stripe はエンドポイントに次のリクエストを送信します。

```typescript
{
  type: "v1.delegated_checkout.finalize_checkout",
  id: string,
  livemode: boolean,
  // account ID
  context?: string,
  // request specific data
  data: {
    amount_subtotal?: number,
    amount_total?: number,
    billing_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    currency: string,
    email?: string,
    line_items_details: Array<{
      id: string,
      unit_amount: number,
      quantity: number,
      name: string
    }>,
    payment_method_details?: {
      type: "card" | ...,
      card?: {
        brand: "amex" | "visa" | "master_card" | ...,
        country?: string,
        exp_month: number,
        exp_year: number,
        fingerprint?: string,
        funding: "credit" | "debit" | "prepaid" | "unknown",
        iin?: string,
        last4: string,
        wallet?: {
          type: "apple_pay" | "google_pay" | ...
        }
      }
    },
    phone?: string,
    shipping_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      },
    },
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}
```

### 応答形式

エンドポイントは、次の形式で `200` HTTP 応答を返す必要があります。

```typescript
{
  manual_approval_details: {
    type: "approved" | "declined",
    declined?: {
      reason: string
    }
  },
  // Connect only: set an application fee for the transaction
  application_fee_details?: {
    application_fee_amount: number,
    transfer_data?: {
      amount?: number,
    }
  }
}
```

## Optional: 決済カスタマイズフックを設定する

デフォルトでは、Stripe は[商品カタログ](https://docs.stripe.com/agentic-commerce/product-feed.md)に定義されているオプションに基づいて、商品の税金と配送オプションを計算します。

税金または配送オプションとコストをロジックで動的に計算するには、以下のようにします。

1. ダッシュボードの [Agentic コマース設定](https://dashboard.stripe.com/settings/agentic-commerce)ページでエンドポイントを指定します。
1. **カスタム税率**または**カスタム配送オプション**を有効にします。
1. エンドポイントにロジックを実装し、以下のリクエストとレスポンスの形式を使用します。

> エンドポイントが `2xx` 以外のステータスコードを返すと、Stripe はエージェントに `424` ステータスコードを返します。一部のエージェントはこれらの API リクエストを再試行する可能性があるため、エンドポイントが冪等であることを確認する必要があります。

### リクエスト形式

Stripe はエンドポイントに次のリクエストを送信します。

```typescript
{
  type: "v1.delegated_checkout.customize_checkout",
  id: string,
  livemode: boolean,
  // Connected account ID
  context?: string,
  // Request specific data
  data: {
    // Used by the seller to determine whether they can set manual tax rates on line items
    automatic_tax: {
      enabled: boolean,
    },
    currency: string,
    line_item_details?: Array<{
      id: string,
      sku_id: string,
      unit_amount: number,
      amount_discount: number,
      amount_subtotal: number,
      amount_tax: number,
      amount_total: number,
      quantity: number,
      name: string,
      tax_rates: Array<{
        rate: {
          id: string,
          display_name: string,
          percentage: number,
          inclusive: boolean,
        }
        // Amount of tax applied for this rate.
        amount: number
      }>
    }>,
    shipping_details?: {
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rate?: {
        id: string,
        display_name?: string,
        metadata?: Map<string,string>,
        tax_code?: string ,
        tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rates?: Array<{
        id: string,
        display_name?: string,
        metadata?: Map<string,string>,
        tax_code?: string,
        tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'inclusive' | 'exclusive',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    amount_total?: number,
    amount_subtotal?: number,
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}
```

### 応答形式

エンドポイントは、次の形式で `200` HTTP レスポンスを返す必要があります。

```typescript
{
  shipping_options?: Array<{
    // ID of the shipping rate, or data provided to create the shipping rate. Only provide one; not both
    shipping_rate?: string,
    shipping_rate_data: {
      display_name?: string,
      fixed_amount: {
        amount: number,
        currency: 'usd' | 'cad' | etc.,
      },
      metadata?: Map<string,string>,
      tax_code?: string ,
      tax_behavior?: 'unspecified' | 'inclusive' | 'exclusive',
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/create#create_shipping_rate-delivery_estimate
      delivery_estimate?: {
        maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
        minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
      }
    },
  }>,
  line_items?: Array<{
    // Corresponding ID of the line item to update
    id: string,
    // List of tax rates to apply to this line item
    // Provide either `rate` or `rate_data`
    tax_rates: Array<{
      // ID of a v1 tax rate
      rate?: string,
      // Or `rate_data`.
      // This will use an existing tax rate that matches the params or will create one if a matching rate does not exist
      rate_data?: {
        display_name: string,
        inclusive: boolean,
        // percentage out of 100
        percentage: number,
      }
    },
  }>
}
```

## Optional: フックをテストする

`POST` メソッドでフックリクエストを受け付けられる、一般にアクセス可能なエンドポイントを提供することで、注文承認または決済のカスタマイズフックをテストできます。エンドポイント関数を設定して、以下を行います。

1. JSON ペイロードで `POST` リクエストを処理する
1. 成功ステータスコード (`200`) を返す

ローカル開発では、[ngrok](https://ngrok.com/) などのトンネリングツールを使用してローカルエンドポイントを公開します。

### エンドポイントの例

このコードスニペットは、`v1.delegated_checkout.finalize_checkout` リクエストを受信して `200` レスポンスを返すエンドポイント関数を示しています。署名シークレットは、Webhook 設定の **Agentic Commerce Extension** イベント送信先にある [開発者ダッシュボード](https://docs.stripe.com/development/dashboard.md) から確認できます。

#### Ruby

```ruby
require 'json'
require 'sinatra'
require 'stripe'

set :port, 4242

# Replace with your endpoint's secret from your webhook settings
endpoint_secret = 'whsec_...'

# Using Sinatra
post '/hooks' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  # Verify the webhook signature
  begin
    Stripe::Webhook::Signature.verify_header(
      payload, sig_header, endpoint_secret
    )
  rescue Stripe::SignatureVerificationError => e
    status 400
    return
  end

  # Handle the payload
  payload = JSON.parse(payload)
  case payload['type']
  when 'v1.delegated_checkout.finalize_checkout'
    # Check inventory and accept payment
    data = { manual_approval_details: { type: 'approved' } }
  end

  status 200
  body data.to_json
end
```

## Optional: 在庫の増分更新を送信する

商品データのアップロードに加えて、[Imports API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して個々の商品の在庫更新を送信します。商品データのアップロードと同じアップロードプロセスを使用しますが、`feed_type` を `inventory` に設定します。在庫フィードは `upsert` モードのみをサポートします。

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "feed_type": "inventory",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_inventory_upload.csv"
    }
  }'
```

## Optional: 価格の増分更新を送信する

商品データをアップロードしてから、[インポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用して個別の価格更新を送信します。商品データのアップロード時と同じアップロードプロセスを使用し、`feed_type` を `pricing` に設定します。価格フィードは `upsert` モードにのみ対応しています。

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-04-22.preview" \
  --json '{
    "feed_type": "pricing",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_pricing_upload.csv"
    }
  }'
```

## Optional: 返金と不審請求の申し立てに対応する

決済が完了した後に顧客がウェブサイトまたはカスタマーサービスを通じて注文をキャンセルした場合は、返金を開始します。すでに Checkout Sessions または PaymentIntent API を利用している場合は、既存の返金フローをエージェント型決済でも変更せずに使用できます。返金と不審請求の申し立ては、ダッシュボードの[取引ページ](https://dashboard.stripe.com/payments)で管理するか、[Refunds API](https://docs.stripe.com/api/refunds.md) を使用してキャンセルと返金をプログラムで処理できます。

## See also

- [共有決済トークン](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md)