このガイドでは、Universal Commerce Protocol（UCP）ネイティブ チェックアウトのバージョン 2026-01-23 の技術 API リファレンスとペイロード スキーマについて説明します。
エンドポイントを構築する前に、ネイティブ チェックアウトの概要で、購入手続きのフローの概要、認証要件、デベロッパー ツールを確認してください。
購入手続きセッションを作成する
このエンドポイントを使用すると、ユーザーが購入を希望する商品を含むチェックアウト セッションを作成できます。
- エンドポイント:
POST /checkout-sessions - トリガー: ユーザーが商品の [今すぐ購入] またはカートの [Google で購入手続き] をクリックします。
リクエスト: Google は、広告申込情報と購入者の限定的な住所情報（市区町村、都道府県、郵便番号）を送信します。
// Request Example: Create checkout with multiple items.
{
"line_items": [
{
"item": {
// Must match ID in product feed
"id": "product_12345"
},
"quantity": 1
},
{
"item": {
// Must match ID in product feed
"id": "product_67890"
},
"quantity": 1
}
],
"context": {
"language": "en"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Sunnyvale",
"address_region": "CA",
"postal_code": "94089",
"address_country": "US"
}
],
"selected_destination_id": "addr_1"
}
]
}
}
レスポンス: 合計、税金（最初は推定）、支払い機能を含む初期化されたセッションを返します。
// Response Example: Initialize Session with multiple items.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
"dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
},
"payment_handlers": {
"com.google.pay": [
{
"id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"version": "2026-01-23",
"spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
"schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
"config": {
"api_version": 2,
"api_version_minor": 0,
"environment": "TEST",
"merchant_info": {
"merchant_name": "Example Merchant",
"merchant_id": "KWMZPRLQFTYNXSDB",
"merchant_origin": "checkout.merchant.com"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
"allowed_card_networks": [
"AMEX",
"DISCOVER",
"JCB",
"MASTERCARD",
"VISA"
],
"billing_address_required": true,
"billing_address_parameters": {
"format": "FULL",
"phone_number_required": true
}
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "example",
"gatewayMerchantId": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
}
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "incomplete",
"messages": [
{
"type": "error",
"code": "missing_buyer_info",
"path": "$.buyer",
"content_type": "plain",
"content": "Buyer information is required for checkout",
"severity": "recoverable"
},
{
"type": "error",
"code": "missing_fulfillment_info",
"path": "$.fulfillment.methods[0].destinations[0]",
"content_type": "plain",
"content": "Shipping address is incomplete",
"severity": "recoverable"
}
],
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{
"type": "subtotal",
"amount": 10000
},
{
"type": "total",
"amount": 10000
}
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{
"type": "subtotal",
"amount": 2500
},
{
"type": "total",
"amount": 2500
}
]
}
],
"totals": [
{
"type": "subtotal",
"display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
"amount": 12500 // Tax-inclusive markets: Amount must include tax.
},
{
"type": "fulfillment",
"display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
"amount": 500
},
{
"type": "tax", // Tax-inclusive markets: Omit this entry.
"display_text": "Estimated Tax",
"amount": 100
},
{
"type": "total",
"amount": 13100
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Sunnyvale",
"address_region": "CA",
"postal_code": "94089",
"address_country": "US"
}
],
"selected_destination_id": "addr_1",
"groups": [
{
"id": "group_1",
"line_item_ids": [
"line_1",
"line_2"
],
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ {"type": "total", "amount": 500} ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ {"type": "total", "amount": 1500} ]
}
],
"selected_option_id": "ship_ground"
}
]
}
]
},
"links": [
{
"type": "terms_of_service",
"url": "https://m.com/terms",
"title": "Terms of Service"
},
{
"type": "privacy_policy",
"url": "https://m.com/privacy",
"title": "Privacy Policy"
}
]
}
税込み価格
税金が個別に項目化されず、表示される小計に含まれている市場では、決済セッション データを提供するときに、実装が次の要件に準拠している必要があります。
- 小計に税金を含める:
subtotalエントリのamountフィールドには、適用されるすべての税金を含める必要があります。 - 税金の個別のエントリを省略する:
totals配列にtype: "tax"を含む専用のオブジェクトを含めないでください。 - カスタム表示テキストを指定する: 小計オブジェクト内に、税金が含まれていることを明示的に示す
display_text属性（"Subtotal (including taxes)"など）を含める必要があります。また、フルフィルメント エントリのdisplay_text属性（"Shipping"など）も指定する必要があります。
例: 税込み合計の配列
次の例は、税込み市場の販売者の totals 配列を示しています。
"totals": [
{
"type": "subtotal",
"display_text": "Subtotal (including taxes)",
"amount": 12500
},
{
"type": "fulfillment",
"display_text": "Shipping",
"amount": 399
},
{
"type": "total",
"display_text": "Total",
"amount": 12899
}
]
決済セッションを取得する
このエンドポイントを使用すると、購入手続きセッションを取得できます。
- エンドポイント:
GET /checkout-sessions/{id}
リクエスト: Google は購入手続きセッションの ID を送信します。グローバル ID（gid://merchant.example.com/Checkout/session_abc123 など）を使用する場合、リクエスト パスの ID はこの ID の最後のコンポーネント（session_abc123 など）のみになります。
レスポンス: 完全なチェックアウト オブジェクトを返します。バージョン 2026-01-23 以降で作成された複数アイテム セッションの場合、line_items 配列には複数のアイテム エントリが含まれます。
購入手続きセッションを更新する
このエンドポイントを使用すると、購入手続きセッションを更新できます。配送先住所が更新された場合は、税金と配送オプションを再計算して返す必要があります。
- エンドポイント:
PUT /checkout-sessions/{id}
お届け先住所を更新してください
- トリガー: ユーザーが配送先住所を選択または変更したとき。
リクエスト: ユーザーが配送先住所を変更すると、Google はフルフィルメント アドレスを更新します。
// Request Example: Update shipping address with multiple items.
{
"line_items": [
{
// line_items id from Create Checkout response
"id": "line_1",
"item": {
"id": "product_12345"
},
"quantity": 1
},
{
// line_items id from Create Checkout response
"id": "line_2",
"item": {
"id": "product_67890"
},
"quantity": 1
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": [
"line_1",
"line_2"
],
"destinations": [
{
"id": "addr_1",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US"
}
],
"selected_destination_id": "addr_1",
"groups": [
{
"id": "group_1",
"selected_option_id": "ship_ground"
}
]
}
]
}
}
レスポンス: 必要に応じて税金と配送オプションを再計算し、完全な購入手続きオブジェクトを返します。
// Response Example: Updated session with new address for multiple items.
{
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"currency": "USD",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "total", "amount": 10000 }
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 2500 },
{ "type": "total", "amount": 2500 }
]
}
],
"totals": [
{ "type": "subtotal", "amount": 12500 },
// Shipping cost might change based on new address
{ "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
// Tax will likely change based on new address
{ "type": "tax", "amount": 1120 },
{ "type": "total", "amount": 14220 }
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1", "line_2"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 600 } ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 1600 } ]
}
]
}
]
}
]
}
// ... other fields like ucp, status, messages, links
}
完全な checkout オブジェクトのハイドレーション
リクエスト: 購入者が [GPay で支払う] をクリックすると、Google は更新された情報（配送先住所と購入者の連絡先を含む）を含む完全なチェックアウト オブジェクトを送信します。
// Request Example: full checkout object hydration for multiple items.
{
"buyer": {
"first_name": "John",
"last_name": "Buyer",
"email": "johnbuyer@example.com",
"phone_number": "+18888888888"
},
"line_items": [
{
"id": "line_1",
"item": { "id": "product_12345" },
"quantity": 1
},
{
"id": "line_2",
"item": { "id": "product_67890" },
"quantity": 1
}
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"first_name": "Alice",
"last_name": "Receiver",
"street_address": "1600 Amphitheatre Pkwy",
"extended_address": "Suite #60",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US",
"phone_number": "+18888888888"
}
],
"groups": [
{
"id": "group_1",
"selected_option_id": "ship_ground"
}
]
}
]
}
}
レスポンス: 必要に応じて税金と配送オプションを再計算し、完全な購入手続きオブジェクトを返します。
// Response Example: Session after full hydration with multiple items.
{
"ucp": {
"version": "2026-01-23",
"capabilities": {
"dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
"dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "extends": "dev.ucp.shopping.checkout" } ]
},
"payment_handlers": {
"com.google.pay": [
{
"id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"version": "2026-01-23",
"spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
"schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
"config": {
"api_version": 2,
"api_version_minor": 0,
"environment": "TEST",
"merchant_info": {
"merchant_name": "Example Merchant",
"merchant_id": "KWMZPRLQFTYNXSDB",
"merchant_origin": "checkout.merchant.com"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
"allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
"billing_address_required": true,
"billing_address_parameters": {
"format": "FULL",
"phone_number_required": true
}
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "example",
"gatewayMerchantId": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
}
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "ready_for_complete",
"currency": "USD",
"buyer": {
"first_name": "John",
"last_name": "Buyer",
"email": "johnbuyer@example.com",
"phone_number": "+18888888888"
},
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000,
"image_url": "https://merchant.example.com/images/product_12345.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "total", "amount": 10000 }
]
},
{
"id": "line_2",
"item": {
"id": "product_67890",
"title": "T-Shirt",
"price": 2500,
"image_url": "https://merchant.example.com/images/product_67890.png"
},
"quantity": 1,
"totals": [
{ "type": "subtotal", "amount": 2500 },
{ "type": "total", "amount": 2500 }
]
}
],
"totals": [
{ "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
{ "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
{ "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
{ "type": "total", "display_text": "Total", "amount": 14220 }
],
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1", "line_2"],
"selected_destination_id": "addr_1",
"destinations": [
{
"id": "addr_1",
"first_name": "Alice",
"last_name": "Receiver",
"street_address": "1600 Amphitheatre Pkwy",
"extended_address": "Suite #60",
"address_locality": "Mountain View",
"address_region": "CA",
"postal_code": "94043",
"address_country": "US",
"phone_number": "+18888888888"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1", "line_2"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 600 } ]
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
"totals": [ { "type": "total", "amount": 1600 } ]
}
]
}
]
}
]
},
"links": [
{
"type": "terms_of_service",
"url": "https://m.com/terms",
"title": "Terms of Service"
},
{
"type": "privacy_policy",
"url": "https://m.com/privacy",
"title": "Privacy Policy"
}
]
}
購入手続きセッションを完了する
このエンドポイントを使用すると、購入手続きセッションを完了して注文できます。完了した購入手続きセッションを返し、注文情報を含める必要があります。この呼び出しを受信したら、支払いの処理を開始する必要があります。
- エンドポイント:
POST /checkout-sessions/{id}/complete - トリガー: ユーザーが [GPay で支払う] をクリックし、Google が完全にハイドレートされたチェックアウト更新から成功レスポンスを受け取ります。
リクエスト: Google は、選択されたお支払い方法を、認証情報（Google Pay のトークン化データなど）と購入者に関するリスクシグナルを含めてお支払いハンドラから送信します。これにより、独自の不正行為検出を実行できます。トークンの内容は、お使いの決済サービス プロバイダによって異なります。
{
"payment": {
"instruments": [
{
"billing_address": {
"first_name": "John",
"last_name": "Buyer",
"street_address": "100 Main St",
"extended_address": "Apt 4B",
"address_locality": "San Francisco",
"address_region": "CA",
"postal_code": "94105",
"address_country": "US",
"phone_number": "+18888888888"
},
"credential": {
"token": "examplePaymentMethodToken",
"type": "PAYMENT_GATEWAY"
},
"display": {
"brand": "VISA",
"description": "Visa •••• 1234",
"last_digits": "1234"
},
"handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
"selected": true,
"type": "card"
}
]
},
"signals": {
"com.google.authentication_triggered": "",
"com.google.authorization_processed_with_3ds": "",
"com.google.avs_full_result": "",
"com.google.cvv_result": "",
"com.google.ip_address": "203.0.113.1",
"dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
"dev.ucp.buyer_ip": "203.0.113.1"
}
}
購入手続きを完了するために必要な必須情報が購入手続きセッションで提供されていない場合は、レスポンスで完了以外のステータスを返すことで、購入手続きの完了を阻止し、その情報をリクエストできます。
Google が UCP で定義されたフィールド（購入者のメールアドレスなど）を使用して不足している情報を収集できる場合は、status を incomplete に設定し、severity が recoverable に設定された 1 つ以上のメッセージを messages 配列に含めて、不足している情報を示します。
{
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "incomplete",
"messages": [
{
"type": "error",
"code": "missing_buyer_info",
"severity": "recoverable",
"content": "Buyer email is required"
},
{
"type": "error",
"code": "missing_fulfillment_info",
"severity": "recoverable",
"content": "Select delivery window for your purchase"
}
]
}
Google Pay の支払い方法を受け取ったら、次のことを行う必要があります。
- Validate ハンドラ:
handler_idが構成で定義されている Google Pay 支払いハンドラに対応していることを確認します。 - トークンを抽出: 生成された支払い方法トークンを
payment.instruments[0].credential.tokenから取得します。 - 支払いを処理する: トークンと取引明細を使用して支払いを完了します。トークン化の仕様と処理に関する詳細なドキュメントについては、Google Pay API ドキュメントを参照してください。
レスポンス: 購入手続きを完了でき、支払いを処理した場合は、注文が完了したことを示す完全な購入手続きオブジェクトを返します。これには、確認済みの支払い方法（機密性の高い credential トークンまたは signals を含まない、支払い方法のメタデータと請求先住所のエコー）、注文 ID、注文へのパーマリンク URL が含まれます。
{
"ucp": {
"version": "2026-01-23",
"capabilities": [...]
},
"id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"payment": {
"instruments": [
{
"id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
"handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
"type": "card",
"selected": true,
"display": {
"brand": "VISA",
"description": "Visa •••• 1234",
"last_digits": "1234"
},
"billing_address": {
"first_name": "John",
"last_name": "Buyer",
"street_address": "100 Main St",
"extended_address": "Apt 4B",
"address_locality": "San Francisco",
"address_region": "CA",
"postal_code": "94105",
"address_country": "US",
"phone_number": "+18888888888"
}
}
]
},
"order": {
"id": "ORD1773956535.2727807",
// Example customer-facing order number
"label": "#100",
"permalink_url": "https://merchant.example.com/orders/789"
}
}
決済セッションをキャンセルする
このエンドポイントは、チェックアウト セッションをキャンセルします。
- エンドポイント:
POST /checkout-sessions/{id}/cancel
リクエスト: Google は決済セッションの ID を送信します。
レスポンス: ステータスが canceled に更新された完全なチェックアウト オブジェクトを返します。
エラー処理
エラー メッセージの形式設定方法と、プロトコル エラーとビジネス ロジック エラーの違いに関する完全なガイドラインについては、エラーコードの概要をご覧ください。
修復不可能なエラー
バージョン 2026-01-23 では、回復不能なビジネス ロジック エラーによってチェックアウト セッションの作成が妨げられた場合（すべてのアイテムが在庫切れなど）、HTTP 200 OK を返します。
バージョン 2026-01-23 では、決済セッション ID を省略し、messages 配列内で "severity": "unrecoverable" を指定することで、端末の障害を示す必要があります。これは、リクエストは有効だったが、ビジネスルールによってセッションの作成がブロックされたことを Google に伝えます。
HTTP/1.1 200 OK
Content-Type: application/json
{
"ucp": {
"version": "2026-01-23"
},
"messages": [
{
"type": "error",
"code": "out_of_stock",
"content": "All requested items are currently out of stock",
"severity": "unrecoverable"
}
],
"continue_url": "https://merchant.com/"
}