メインコンテンツまでスキップ

カート API

概要​

カート API を使用すると、Rokt のパートナーは取引中に顧客のカートに追加の製品を追加できます。カート API は Web SDK と連携して、フロントエンドの配置をレンダリングし、顧客のカートを更新するためのフックを提供します。Rokt を通じてアップセルを実現するためには、次の2つの統合が必要です:

  1. バックエンドのカート/チェックアウトシステムを Rokt カート API と統合する（このドキュメント）。
  2. Web SDK を カートフロントエンド に統合する。

駐車場は Rokt のカート追加製品の良い例です。例えば、チケット販売のパートナーは、イベントチケットを購入する際に顧客に駐車場をアップセルすることができます。これらの駐車場は、サードパーティの駐車場プロバイダーを通じて提供されます。

最小限の統合​

顧客の注文を完了するには、次のフックと API エンドポイントと統合する必要があります。

  1. V2_CART_ITEM_UPDATED イベントを購読して、ユーザーがカートにアイテムを追加したときに通知を受け取ります。
  2. アイテムの購入が成功したことを確認するために、/cart/confirm を呼び出します。

アイテムの予約​

一部のアイテムは、チェックアウト時に予約する必要があります。これは、最終的に確認された際に在庫がまだ利用可能であることを保証するためです。予約を処理するために、以下のエンドポイントを使用してください。

  1. アイテムを一定期間予約するために、/cart/reserve を呼び出します。
  2. オプションで、予約をキャンセルし、他の顧客がそのアイテムを予約できるようにするために、/cart/release を呼び出します。

確認済みアイテムのキャンセル​

確認後のアイテムをキャンセルするためのエンドポイントが利用可能です。

  1. /confirmation/cancel を呼び出します。

トランザクション内リクエストフロー​

顧客の注文を履行するために、パートナーは以下のトランザクションフローに従う必要があります。

In-Transaction Request Flow

  1. (オプション) /placements/any を呼び出して、表示するプレースメントがあるかどうかを判断します。関連するオファーがない場合は、クロスセル/アップセルステージをスキップできます。
  2. /placements/any が true または false を返すかに基づいて、トランザクションフローでアップセルページを表示するかスキップするかを選択できます。アップセルページでは、利用可能なプレースメントをリクエストして表示する Web SDK を初期化する必要があります。
  3. 顧客がオプトインすると、Web SDK は V2_CART_ITEM_UPDATED メッセージを送信してパートナーのフロントエンドに通知します。その後、通常の購入プロセスが続行されます。
  4. (オプション) アイテムを一定期間予約するために、/cart/reserve を呼び出します。この期間内に購入を完了し、Rokt で確認する必要があります。
  5. 顧客がアイテムの支払いを完了したら、/cart/confirm を呼び出して、アイテムの購入が成功したことを確認します。その後、Rokt は商品の履行のために関連するプロバイダーに通知します。
    1. 予約をキャンセルするには、/cart/release を呼び出します。これは、確認されなかった予約アイテムがタイムアウト後に自動的に解放されるため、オプションです。これは、予約アイテムの迅速な解放を必要とする高トラフィックのパートナーに適しています。
    2. 確認済みアイテムをキャンセルするには、/confirmation/cancel を呼び出します。これは、確認後にアイテムをキャンセルしたいパートナーに適しています。

認証​

認証の設定については、Roktのアカウントマネージャーにお問い合わせください。

API エンドポイント​

POST 任意のプレースメント​

パートナーが表示するプレースメントがあるかどうかを判断し、該当する場合はアップセル/クロスセルステージをスキップする可能性があります。

説明​

Roktのカート追加プレースメントを含むページを表示する価値があるかどうかを決定します。これがtrueまたはfalseを返すかに基づいて、パートナーはトランザクションフローでアップセルページを表示するかスキップするかを選択できます。

サンプルリクエスト

POST /v1/placements/any
{
    "cartId": "1580265846172",
    "attributes": {
        "eventId": "1100526195FA115A",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36",
        "venueName": "Madison Square Garden",
        "eventdate": "20311212",
        "country": "US",
        "locale": "en-US"
    },
"pageIdentifier": "checkout.upsell"
}

リクエスト​

パス

POST /v1/Placements/any

パラメータ

名前場所説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ、現在サポートされている唯一の値は'application/json'です application/json
Acceptヘッダーレスポンスの期待されるメディアタイプ、現在サポートされている唯一の値は'application/json'です application/json
rokt-session-idヘッダーRoktが内部でトラッキング、リファラル、ログ、デバッグに使用するSessionId。このエンドポイントではオプションです（提供されない場合はsessionIdが生成されます）。 ca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idヘッダー一意のRoktタグIDtrue253_439d21r21r21321
Accept-Languageヘッダーコンシューマの期待されるロケール。言語と国を含む完全なロケール、または言語のみの中立的なロケールを指定できます。ロケールが指定されると、そのロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "pageIdentifier": "string",
  "url": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "result": true
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Reserve Cart Items​

パートナーがアイテムを一定期間予約/保持することを可能にし、その期間中に購入が完了し、Roktと確認される必要があります。これにより、パートナーは在庫を確保し、予約期間中の価格を固定することができます。

説明​

ユーザーがカタログアイテムの選択を確定したが、まだ支払いをしていない場合、カートアイテムを予約することで、在庫の供給を確保し、返された値に従って価格を固定します。 このメソッドに複数のカートアイテムが渡された場合、一部が正常に予約され、一部が拒否されることがあります。

サンプルリクエスト

    POST /v1/cart/reserve
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": 1
            }
        ]
    }

リクエスト​

パス

POST /v1/cart/reserve

パラメータ

名前場所説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ、現在サポートされている値は'application/json'のみ application/json
Acceptヘッダーレスポンスの期待されるメディアタイプ、現在サポートされている値は'application/json'のみ application/json
rokt-session-idヘッダーRoktが内部でトラッキング、紹介、ログ、デバッグに使用するSessionId。trueca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idヘッダーユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageヘッダー消費者の期待されるロケール。これは言語と国を含む完全なロケール、または言語のみの中立ロケールであることができます。ロケールが指定されると、そのロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "quantity": 0
    }
  ],
  "isPayPalPayment": true,
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0,
      "unitPrice": 0,
      "totalPrice": 0,
      "currency": "string",
      "expirationDateTimeUtc": "2025-10-04T10:00:00.000Z",
      "success": true
    }
  ],
  "payPalOrderId": "string"
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST カートアイテムの確認​

パートナーがアイテムの購入成功を確認することを可能にします。Roktはその後、製品の履行のために関連するプロバイダーに通知します。

説明​

カート内のすべてのアイテムの支払いが処理された後に呼び出されます。Roktは、すべての購入イベントに対して、すべてのプラットフォーム、デバイス、環境（ウェブ/アプリ）、国、およびチャネルでこれが呼び出されることを推奨します。

サンプルリクエスト #1

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

サンプルリクエスト #2

    POST /v1/cart/confirm
    {
        "cartId": "1580265846172",
        "orderId": "1580265885747",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "quantity": "15"
            }
        ]
    }

items コレクションには少なくとも以下のいずれかを含める必要があります - cartItemId と itemReservationId または - cartItemId と quantity

リクエスト​

パス

POST /v1/cart/confirm

パラメータ

名前場所説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ、現在サポートされている値は'application/json'のみ application/json
Acceptヘッダー応答の期待されるメディアタイプ、現在サポートされている値は'application/json'のみ application/json
rokt-session-idヘッダーRoktが内部でトラッキング、リファラル、ログ、デバッグに使用するSessionId。アイテムが含まれていない場合はオプション（指定されていない場合はsessionIdが生成されます）。 ca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idヘッダーユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageヘッダー消費者の期待されるロケール。言語と国を含む完全なロケール、または言語のみの中立ロケールを指定できます。ロケールが指定されている場合、そのロケールに一致するプレースメントとオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "quantity": 0
    }
  ],
  "payPalOrderId": "string",
  "merchantId": "string",
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "orderId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "itemConfirmationId": "string",
      "itemConfirmationUrl": "string",
      "success": true
    }
  ]
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST 購入済みアイテムのキャンセル​

パートナーが以前に購入（確認済み）のアイテムをキャンセルできるようにします。Roktは関連するプロバイダーにキャンセルを依頼し、その応答を返します。

説明​

サンプルリクエスト

    POST /v1/confirmation/cancel
    {
        "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
    }

リクエスト​

パス

POST /v1/confirmation/cancel

パラメータ

名前所在説明必須例
rokt-api-keyヘッダーAPI認証キーtrueskeletonkey
Content-Typeヘッダーリクエストのメディアタイプ、現在サポートされている値は'application/json'のみ application/json
Acceptヘッダー応答の期待されるメディアタイプ、現在サポートされている値は'application/json'のみ application/json
Accept-Languageヘッダーコンシューマーの期待されるロケール。言語と国を含む完全なロケール、または言語のみの中立ロケールを指定できます。ロケールが指定されると、そのロケールに一致する配置とオファーのみが考慮されます。 en-US

リクエストボディ

{
  "itemReservationId": "string"
}

レスポンス​

200 OK

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

POST Release Cart Items​

パートナーが一連のアイテムの予約をキャンセルできるようにします。これはオプションであり、確認されていない予約アイテムはタイムアウト後に自動的にリリースされます。これは、予約アイテムの迅速なリリースを必要とする非常にバースト性のあるトラフィックを持つパートナーに適しています。

説明​

ユーザーが予約されたアイテムをカートから削除したり、カート/トランザクション全体をキャンセルした場合。予約されたカートアイテムは最終的にタイムアウトし、自動的にリリースされますが、バースト性のあるまたは高トラフィック環境を持つパートナーは、供給の早期または一時的な枯渇を防ぐためにこのプロセスを迅速化したい場合があります。

サンプルリクエスト

 POST /v1/cart/release
    {
        "cartId": "1580265846172",
        "items": [
            {
                "cartItemId": "30d0a389-5f63-4e20-9553-13ff40f8b11c",
                "itemReservationId": "rokt_item_reservation_id.63a94103-75da-4d71-8c14-84674d286b98"
            }
        ]
    }

リクエスト​

パス

POST /v1/cart/release

パラメータ

名前場所説明必須例
rokt-api-keyheaderAPI認証キーtrueskeletonkey
Content-Typeheaderリクエストのメディアタイプ、現在サポートされている値は'application/json'のみ application/json
Acceptheaderレスポンスの期待されるメディアタイプ、現在サポートされている値は'application/json'のみ application/json
rokt-session-idheaderRoktが内部でトラッキング、リファラル、ログ、デバッグに使用するSessionId。trueca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idheader一意のRoktタグIDtrue253_439d21r21r21321
Accept-Languageheader消費者の期待されるロケール。これは言語と国を含む完全なロケール、または言語のみの中立的なロケールであることができます。ロケールが指定されると、そのロケールに一致する配置とオファーのみが考慮されます。 en-US

リクエストボディ

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string"
    }
  ],
  "attributes": {
    "attribute": "string"
  }
}

レスポンス​

200 OK

{
  "cartId": "string",
  "items": [
    {
      "cartItemId": "string",
      "itemReservationId": "string",
      "success": true
    }
  ]
}

エラー​

400 BadRequest

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

401 Unauthorized

403 Forbidden

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

422 UnprocessableEntity

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

500 InternalServerError

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}

504 GatewayTimeout

{
  "description": "string",
  "errors": [
    {
      "code": "string",
      "message": "string",
      "value": {}
    }
  ]
}
この記事は役に立ちましたか？
Last updated Oct 29, 2025