新しいマーチャントのオンボーディング

Audience

このAPIサーフェスは、Roktネットワーク上に構築する統合パートナー向けです。Roktのeコマースパートナーが独自のチェックアウトに配置を統合する場合は、Rokt Ecommerce開発者ドキュメントを使用してください。

このレシピは、プラットフォーム上の新しいマーチャントから、ライブで収益を生み出すRoktアカウントまでの標準的なパスを案内します。すべてのステップは、APIトークンベアラートークン、X-Platform-Parent-Account-Idヘッダー、および冪等性キーを使用してバックエンドから呼び出すことができます。

備考

前提条件: 概要、認証、およびクイックスタートを読んでいること。あなたは有効なAPIトークンとplatform_parent_account_idを持っています。すべての例では、$PARENTがその値を保持していると仮定します。

また、あなたの親アカウントにカテゴリ分類がシードされている必要があります。それはRoktが実行する一度きりのプラットフォーム設定ステップであり、マーチャントごとに行うものではありません。以下のステップ1でそれを確認します。垂直分類を参照してください。

1
Confirm the merchant's category is mapped
登録は、あなたの親アカウントにシードされたマッピングを通じてマーチャントの{vertical_id, sub_vertical_id}ペアを解決し、ペアが欠落している場合は400で拒否します。最初にセットに含まれているか確認してください。
curl "https://accounts.rokt.com/v1/partnership/vertical-mappings?parent_account_id=$PARENT" \ -H "Authorization: Bearer $TOKEN"
レスポンスの形状はマッピングされているものを確認にあります。セットはめったに変更されないので、マーチャントごとに呼び出すのではなくキャッシュしてください。異なる処理が必要な2つのケース:
- 空の配列: 何もシードされていないため、マーチャントは登録されません。smb-partnerships@rokt.comに完全なカテゴリリストをメールで送り、確認を待ってください。
- 非空セットからのペアの欠如: 1行が欠落しています。ペアとカテゴリ名をメールで送り、このマーチャントを保留してください。無関係なマッピングされたカテゴリを代用して押し通さないでください。マーチャントはネットワークのブランドセーフティコントロールの外に置かれることになります。

POST /v1/accounts/register/partnershipにマーチャントのブランド、パートナー分類ID、国、ストアURL、およびあなたの安定したexternal_account_idを送信します。返されたaccount_idをdata.account_idからキャプチャしてください。すべての後続の呼び出しはそれに基づきます。

オプションのpages配列を渡して、このマーチャントがどのサーフェスで配置をレンダリングするかを宣言します。各エントリは、パートナー向けのサーフェス(confirmation, tracking, returns)をレイアウトスタイル(OverlayまたはEmbedded)にマッピングします。完全なサーフェス語彙についてはページとレイアウトを参照してください。

curl
python

curl -X POST https://accounts.rokt.com/v1/accounts/register/partnership \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Acme Apparel",
    "vertical_id": 1500,
    "sub_vertical_id": 1610,
    "country_code": "US",
    "platform_parent_account_id": "<your-platform-parent-account-id>",
    "store_identifier": "https://acme-apparel.example.com",
    "external_account_id": "partner-merchant-abc123",
    "pages": [
      { "surface": "confirmation", "layout_type": "Overlay"  },
      { "surface": "tracking",     "layout_type": "Embedded" }
    ]
  }'

import requests

r = requests.post(
    "https://accounts.rokt.com/v1/accounts/register/partnership",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent_account_id,
    },
    json={
        "brand": "Acme Apparel",
        "vertical_id": 1500,
        "sub_vertical_id": 1610,
        "country_code": "US",
        "platform_parent_account_id": "<your-platform-parent-account-id>",
        "store_identifier": "https://acme-apparel.example.com",
        "external_account_id": "partner-merchant-abc123",
        "pages": [
            {"surface": "confirmation", "layout_type": "Overlay"},
            {"surface": "tracking",     "layout_type": "Embedded"},
        ],
    },
)
body = r.json()["data"]
account_id = body["account_id"]
pages = body.get("pages", [])
# Store each entry's page_identifier per surface; you'll pass these into
# the Web SDK's selectPlacements call later.

レスポンス:

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": {
    "account_id": "<your-account-id>",
    "pages": [
      { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" },
      { "surface": "tracking",     "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" }
    ]
  }
}

注記

登録はexternal_account_idで冪等です。同じexternal_account_idで再POSTすると同じaccount_idが返され、重複したアカウントは作成されません。これを使用してオンボーディングのリトライを安全に行うことができます。

警告

store_identifierは3〜400文字の有効なURLであり、スキームを含める必要があります。https://acme.myshopify.comを送信し、acme.myshopify.comは送信しないでください。ベアホスト名は400を返します。

3
Inspect default controls
パートナーシッププリセットは、アカウント作成時にデフォルトのマーケットプレイスコントロールをシードします。カスタマイズする前にそれらを読み、ベースラインを把握してください。
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
MCLレスポンスペイロード (data.translated_verticals) は、パートナー分類法でマッピングされたすべてのサブバーティカルの有効なポリシーを一覧表示します。vertical_idはサブバーティカルIDであり、それを使用して独自のカテゴリ名に戻して表示することができます。Roktの内部IDは公開されません。
4
Customize marketplace controls (optional)
完全なブロックリストをPUTします。これはSETセマンティクスです：毎回完全なリストを送信します。省略したものはブロック解除されます。SETセマンティクスおよびバーティカル分類法の概念ページを参照してください。
curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/marketplacecontrolslists \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Acme Network Controls", "blockedVerticals": [ { "partnerVerticalId": 1500, "partnerSubVerticalId": 1610, "policy": "Block", "position1Policy": "Block" }, { "partnerVerticalId": 1500, "partnerSubVerticalId": 1611, "policy": "Block", "position1Policy": "Block" } ], "domains": [ { "domain": "competitor.example.com", "policy": "Block" } ], "contentHash": null }'
ヒント
contentHash: nullは最初の書き込み時に問題ありません。後続の更新では、楽観的同時実行性チェックに参加するために、前回のGETからのハッシュを渡します。エンドツーエンドの古いハッシュ拒否はプレビューグレードです：受け入れによって検証されていますが、パートナー表面でのライブ観察はまだありません。コントロールの更新を参照してください。
5
Start Stripe Connect payout setup
POST /v1/partnership/accounts/{account_id}/payout-setupを使用してStripe Connectオンボーディングを開始します。次の2つの形状のいずれかを選択します：
- experience: "embedded": StripeのオンボーディングUIをアプリ内にレンダリングします。contactを含めないでください。含めるとサーバーは400を返します。
- experience: "hosted_invite": Roktはマーチャントにリンクをメールで送信します。contact.emailが必要です。
# Embedded: no contact block curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "provider": "stripe_connect", "experience": "embedded" }' # Hosted-invite: contact required curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "provider": "stripe_connect", "experience": "hosted_invite", "contact": { "email": "merchant@example.com", "name": "Acme Apparel" } }'
レスポンスはdata内に2つのサブ形状のいずれかを含みます：
- embeddedの場合：data.embedded.publishable_key + data.embedded.client_secret。これらをStripe.jsに接続してフローをレンダリングします。
- hosted_inviteの場合：data.hosted_invite.invite_id + data.hosted_invite.email。マーチャントは自動的にメールを受け取ります。
警告
リクエスト内に銀行口座、カード、ルーティング、SSN、IBAN、税、または外部アカウントフィールドを絶対に含めないでください。これらのフィールド名はどのネストレベルでも禁止されており、400を返します。Stripeはそれらを直接商人から収集します。
6
Wait for payout completion
/v1/partnership/accounts/{account_id}/payout-setup/statusをポーリングして、data.payouts_enabled === trueおよびdata.details_submitted === trueになるまで確認します。推奨される間隔: 30秒ごと、7日後に諦めます。Stripeのオンボーディングはパートナードリブンであり、時間がかかる場合があります。ループを厳しくしないでください。
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/payout-setup/status \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
{ "status": 200, "error": null, "message": "ok", "request_id": "...", "data": { "provider": "stripe_connect", "setup_id": "stp_...", "managed_account_id": "<your-account-id>", "manager_account_id": "<your-platform-parent-account-id>", "connected_account_id": "acct_...", "details_submitted": false, "payouts_enabled": false, "charges_enabled": false, "requirements_currently_due_count": 3, "requirements_eventually_due_count": 0, "requirements_past_due_count": 0, "disabled_reason": null, "updated_at": "2026-05-20T19:14:00Z" } }
disabled_reasonがnullでない場合、またはrequirements_past_due_count > 0の場合、それを商人に伝えて完了させることができます。
7日間のポーリングウィンドウがpayouts_enabled === trueにならずに期限切れになった場合、商人を立ち往生させないでください。このシーケンスで回復してください:
1. 新しいオンボーディングセッションを生成するためにPOST /v1/partnership/accounts/{account_id}/payout-setupを再呼び出します。 同じ商人が複数のセッションを保有することができますが、完了に関しては最新のものだけが重要ですので、古いembeddedクライアントシークレットやhosted_inviteリンクは安全に放棄できます。新しいセッションには新しいIdempotency-Keyを使用してください。
2. 基礎となるdisabled_reasonを商人にそのまま伝えてください（最新のポーリング応答のdata.disabled_reasonから）。これにより、Stripe側で修正すべき内容を正確に知ることができ、再開する前に（例: 税IDの欠如、身元確認の失敗、未確認の銀行口座）修正することができます。Stripeが定義した理由文字列は、製品内ヘルプメッセージを駆動するのに十分安定しています。
3. disabled_reasonがStripe側の問題を示しており、表面化または修正できない場合（例: requires_rokt_review、under_review、またはStripeのConnectオンボーディングドキュメントに記載されていない値）、サポートチケットを提出してください。元の支払い設定応答のX-Operation-Idと商人のaccount_idを含めてください。それにより、Roktのオペレーターが接続されたアカウントレコードを引き出して解決できます。

Activate the partnership

支払いが完了し、コントロールに満足したら、ステータスをactiveに切り替えます。このカスケードにより、アカウント上のすべての非アーカイブページバリアントが有効になります。

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "status": "active" }'

8
Verify the cascade
ステータスの読み取りを往復して、すべてのバリアントが切り替わったことを確認します。
curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \ -H "Authorization: Bearer $TOKEN" \ -H "X-Platform-Parent-Account-Id: $PARENT"
data.statusは"active"であるべきで、data.variants[]のすべてのエントリは"active"を示すべきです。"mixed"が表示された場合、カスケードがいくつかのバリアントを見逃したことを示します。応答エンベロープからのIdempotency-Keyとrequest_idを使用してサポートチケットを提出してください。
9
Wire the Web SDK on the merchant's pages
Roktはアカウント、ページ、およびレイアウトをプロビジョニングしました。残りのステップは商人のサイトで行われます: 各ページに一度Rokt Web SDKをロードし、登録応答からの一致するpage_identifierを渡して各サーフェスでselectPlacementsを呼び出します。
<script type="module"> await window.RoktLauncherScriptPromise; const launcher = await window.Rokt.createLauncher({ accountId: "<account_id from registration>", sandbox: true }); // Confirmation page: await launcher.selectPlacements({ identifier: "confirmation_page", // ← from registration response's pages[].page_identifier attributes: { email, firstname, lastname, confirmationref, amount, currency, country } }); </script>
埋め込みサーフェス（Embeddedレイアウトタイプ）はページ上にアンカー要素を必要とします。デフォルトではSDKは<div id="rokt-container"></div>を探します。完全なセットアップにはSDK Integrationを参照してください。ローダースニペット、属性カバレッジ、およびSPAノートが含まれています。

マーチャントの体験をカスタマイズするマーチャントの体験をカスタマイズするへの直接リンク

登録時に、すべてのマーチャントにはパートナーシッププリセットのデフォルトテーマとサーフェスセットが提供されます。インテグレーションがライブになった後、再登録せずにそのベースラインを進化させるための3つのエンドポイントがあります。視覚的なテーマ設定のための5トークンレイアウトPATCH、新しいサーフェス（例：マーチャントが最初にconfirmationのみで開始した後にtrackingを追加する）の追加のためのadd-page POST、既存のページをレイアウトタイプ間で移動するためのpage-switch PUTです。これらはすべてパートナーが呼び出せ、冪等で、同じ管理アカウントにスコープされています。Rokt側の介入は必要ありません。

Customize a merchant's layout

マーチャントのレイアウトを5トークンPATCH（背景、プライマリ、セカンダリ、フォント、ボーダー半径）でテーマ設定します。

Add pages after registration

ライブのマーチャントに新しいサーフェス（確認、追跡、返品）を再登録せずに追加します。

Switch a page's layout type

既存のページをオーバーレイと埋め込みの間で移動します。テーマ編集とページ識別子は保持されます。

マーチャントはライブです。次に:

Updating Controls

状態を失わずに継続的なマーケットプレイスコントロールの編集を行うためのGET-modify-PUTパターン。

Pausing & Resuming

マーチャントリクエスト、詐欺ホールド、または紛争解決のための粗い一時停止/再開。

マーチャントの体験をカスタマイズするマーチャントの体験をカスタマイズする への直接リンク

マーチャントの体験をカスタマイズするマーチャントの体験をカスタマイズするへの直接リンク