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

Cart API

概要概要 への直接リンク

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

  1. バックエンドのカート/チェックアウトシステムを Rokt Cart API と統合します。
  2. Web SDK を カートフロントエンド に統合します。

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

最小限の統合最小限の統合 への直接リンク

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

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

アイテムの予約アイテムの予約 への直接リンク

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

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

確認済みアイテムのキャンセル確認済みアイテムのキャンセル への直接リンク

確認済みのアイテムをキャンセルするための次のエンドポイントがあります。

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

トランザクション内リクエストフロートランザクション内リクエストフロー への直接リンク

顧客の注文を完了するには、パートナーは次のトランザクションフローに従う必要があります。

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

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

AuthenticationAuthentication への直接リンク

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

API EndpointsAPI Endpoints への直接リンク

POST Any PlacementsPOST Any Placements への直接リンク

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

DescriptionDescription への直接リンク

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

Sample request

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"
}

RequestRequest への直接リンク

Path

POST /v1/Placements/any

Parameters

NameInDescriptionRequiredExample
rokt-api-keyheaderAPI認証キーtrueskeletonkey
Content-Typeheaderリクエストのメディアタイプ、現在サポートされている唯一の値は'application/json'です application/json
Acceptheaderレスポンスの期待されるメディアタイプ、現在サポートされている唯一の値は'application/json'です application/json
rokt-session-idheaderRoktが内部で追跡、参照、ログ、デバッグに使用するSessionId。このエンドポイントではオプションです（提供されない場合はsessionIdが生成されます）。 ca75f48-ebbd-4d8e-83c3-fdd70893294d
rokt-tag-idheaderユニークなRoktタグIDtrue253_439d21r21r21321
Accept-Languageheader消費者の期待されるロケール。これは言語と国を含む完全なロケール、または言語のみを持つ中立的なロケールであることができます。ロケールが指定されると、そのロケールに一致する配置とオファーのみが検討されます。 en-US

Request body

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

ResponseResponse への直接リンク

200 OK

{
  "result": true
}

ErrorError への直接リンク

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 カートアイテムの予約POST カートアイテムの予約 への直接リンク

パートナーが購入を完了し、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 カートアイテムの確認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"
  }
}

ResponseResponse への直接リンク

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 購入済みアイテムのキャンセル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 カートアイテムの解放POST カートアイテムの解放 への直接リンク

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

説明説明 への直接リンク

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

サンプルリクエスト

 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-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",
      "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 Aug 4, 2026