タグを使ってリードステータスを自動更新する

紹介パートナーが共有した紹介リンク経由でサービスにアクセスしたユーザーが、無料トライアルを経て数カ月後に有料転換した際、利用料の一定割合を報酬としてパートナーに自動還元する運用を実現できます。

無料トライアルの段階ではまだ報酬を支払わず、有料転換が確定した時点で「取引成立」として処理し、報酬を自動発生させたい——そのような運用を、タグとサーバー間 API の組み合わせで実現できます。

イベント	Jolt のステータス	報酬
無料トライアル申し込み	新規 → 適格	発生しない
有料プランへの転換	取引成立 ← サーバー間 API で更新	発生する ✅

タグの基本的な設置方法

①ページビュー・②フォーム・③コンバージョンといった基本タグの設置手順は「タグ設定について」をご覧ください。本記事では、この基本タグに加えて ⑤ ステータス更新タグ を設置して 適格（qualified） へ更新し、有料転換時にはサーバー間 API で 取引成立（won） へ更新する方法を説明します。

⚠️

取引成立（won） はブラウザのタグからは送信できません。

タグの初期化に使うパブリックトークンは、ページのソースを見れば誰でも取得できる公開値です。一方 取引成立 は顧客レコードの作成・報酬の発生・成約としての表示を伴うため、ブラウザから送られた won は受け付けない仕様になっています（HTTP 400 を返します）。

有料転換の連携は、API キー認証のあるサーバー間 API から行ってください（STEP 3 を参照）。

サンプル構成とタグの対応

以下のような構成を例に、各ページへ設置するタグを整理します。

サービスサイト（LP・紹介リンクの着地先）：https://example.com

申し込みフォーム：https://example.com/signup

プロダクト管理画面 TOP（申し込み後の初回ログイン先）：https://app.example.com

アップグレード完了ページ：https://app.example.com/upgrade/complete

対象	URL例	設置するタグ
サービスサイト（全ページ）	`example.com/*`	① ページビュータグ
└ うち申し込みフォーム	`example.com/signup`	＋② フォームタグ
管理画面（全ページ）	`app.example.com/*`	④ ページビュータグ
└ うち TOP（ログイン直後）	`app.example.com`	＋③ コンバージョンタグ／＋⑤ ステータス更新タグ（`qualified`）
└ うちアップグレード完了	`app.example.com/upgrade/complete`	タグの設置は不要（サーバー間 API で `won` に更新）

太字の「全ページ」行が各サイトの土台となるタグ（①／④）です。その下の └ うち … 行は、そのページに追加で載せるタグ（＋）を表します。

💡

④ ページビュータグを管理画面にも設置する理由

③ コンバージョンタグは Cookie を読んでリードを作成します。この Cookie は紹介リンクをクリックした時点で登録ドメイン全体（例：.example.com）に対して発行されるため、同じ登録ドメインのサブドメイン（app.example.com など）でも参照できます。コンバージョンタグが確実に Cookie を参照できるよう、遷移先のページにページビュータグを設置してください。どのページから流入するか特定できない場合は、全ページへの設置を推奨します。

ドメイン構成の前提

このタグ連携は、リード作成のフェーズとステータス更新のフェーズでドメインの要件が異なります。

フェーズ1：リード作成（① → ② → ③）｜ドメイン一致が必要

紹介リンクの着地からリード作成までは、Cookie で「誰の紹介で来たユーザーか」を紐付けます。Cookie をセットする①②のページと、Cookie を読み取る③のページが、Cookie を共有できるドメイン構成である必要があります。

構成例	可否
フォーム `example.com` ／コンバージョン `app.example.com`	✅ 可
フォーム `example.com` ／コンバージョン `example-app.com`	❌ 不可

同一の登録ドメイン配下（例：example.com と app.example.com）であれば、サブドメインが異なっても Cookie を共有できます。一方、別々の登録ドメイン（例：example.com と example-app.com）では Cookie を共有できず、紹介経由のユーザーとしてリードを作成・追跡できません。

フェーズ2：ステータス更新｜ドメインは異なっていてもOK

一度リードが作成され、organization_id またはメールアドレスを取得できていれば、以降のステータス更新はサーバー側でその値を照合して行います。Cookie を使わないため、⑤ ステータス更新タグ（qualified）を設置するページは、①②③とドメインが異なっていても問題ありません（例：課金基盤が billing.example.io のような別ドメインでも動作します）。

取引成立（won） はサーバー間 API で更新するため、そもそもブラウザのドメインとは無関係です。

💡

まとめると、Cookie に依存するのはリード作成まで。リードさえ作られていれば、その後のステータス更新はドメインをまたいでも organization_id／メールアドレスで確実に更新されます。

ユーザーの流れとタグの動き

💡

① 紹介リンクをクリック → サービスサイトに着地 └ ページビュータグが発火 → Cookie をセット（「誰の紹介で来たか」を記憶）

② 無料トライアル申し込みフォームへ └ フォームタグが発火 → メールアドレス・会社名等の入力情報を Jolt に送信

③ フォーム送信 → プロダクト管理画面 TOP へ遷移（初回ログイン） └ ページビュータグが発火 → Cookie を管理画面でも参照可能に └ コンバージョンタグが発火 → Cookie を読んでリードを作成 └ ステータス更新タグが発火 → organization_id を登録＋ 適格（qualified） に更新

④ 無料トライアル期間中（2 回目以降のログイン） └ ステータス更新タグが発火 → 登録・更新はすでに完了しているため自動スキップ

⑤ 有料プランへアップグレード完了 └ 自社サーバーから Jolt の API を呼び出す → organization_id でリードを特定 → 取引成立（won） に更新 └ ブラウザのタグからは won を送れません（STEP 3 を参照）

⑤ ステータス更新の設定手順

STEP 1：ライブラリの読み込みと初期化（管理画面全ページ共通 `<head>`）

Jolt のタグライブラリを読み込み、パブリックトークンで初期化するスニペットです。このスニペットがない状態では Jolt('updateLeadStatus', ...) は動作しません。

html

<script>
  (function(w, d) {
    w.Jolt = w.Jolt || function() {
      (w.Jolt.q = w.Jolt.q || []).push(arguments);
    };
    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://tag.jolt.me/v1/tag.js';
    d.head.appendChild(s);
  })(window, document);

  Jolt('init', 'pub_xxxxxxxxxxxxxxxxxx'); // パブリックトークンに置き換えてください
</script>

💡

統合タグの初期化 Jolt('init', 'pub_xxx...') に使う パブリックトークン（pub_ で始まる書き込み専用トークン）は、プログラム設定＞連携設定＞基本設定 の「パブリックトークン」から取得できます。

STEP 2：管理画面 TOP ページに設置

ログイン後に必ず通るページに設置します。organization_id の登録と 適格（qualified） への更新が目的です。毎回ログインのたびに発火しますが、登録済みの値や同じステータスへの更新は自動でスキップされるため副作用はありません。

html

<script>
  Jolt('updateLeadStatus', {
    organization_id: 'org_12345', // サーバー側で組織IDを動的に出力
    email: 'user@example.com',    // サーバー側でメールアドレスを動的に出力
    status: 'qualified'
  });
</script>

STEP 3：有料転換をサーバー間 API で連携する

取引成立（won） はブラウザのタグからは送信できません。有料転換が確定したタイミングで、自社のサーバーから Jolt の API を呼び出してください。指定するのは STEP 2 のタグで送ったのと同じ organization_id だけです。

項目	内容
メソッド・URL	`PUT` `https://external-api.jolt.me/referrals/leads/status`
認証	`X-Jolt-API-Key` ヘッダーに API キーを指定
ボディ	下記の JSON

{
  "organization_id": "org_12345",
  "status":          "won"
}

💡

API キーは、パブリックトークンと同じ プログラム設定＞連携設定＞基本設定 から取得できます。API の詳細は v1 External API をご覧ください。

リードの指定は organization_id ／ referral_id ／ lead_id ／ custom_field_id ＋ custom_field_value のいずれか1つだけを使います（複数指定するとエラーになります）。タグと同じ値をそのまま使える organization_id を推奨します

X-Dry-Run: true ヘッダーを付けると、認証と入力チェックだけを行い、ステータス更新も報酬の発生もせずに疎通確認ができます

決済手段（クレジットカード／銀行振込など）や決済システムの種類には依存しません。有料転換を確定できるシステムから呼び出してください

⚠️

STEP 2 の設置が前提です。

organization_id は「組織ID」カスタムフィールドで突合します。このフィールドは STEP 2 のタグで organization_id が 1 回でも送信された時点で自動作成されます。STEP 2 を設置していないと突合する値が存在せず 404 になるため、必ず STEP 2 → STEP 3 の順に導入してください。

また、リードのステータスが 新規 のままだと 取引成立 へは直接遷移できません。STEP 2 で 適格 になっていることが前提です。リードの他の指定方法

⚠️

自社システムで Jolt の ID を保持している場合は、organization_id の代わりに referral_id や lead_id でも指定できます（Webhook の lead.created のペイロードに含まれています）。

組織ID 以外のカスタムフィールド（自社で作成した項目）で突合したい場合は custom_field_id ＋ custom_field_value を使います。

updateLeadStatus で送るフィールド（タグ）

フィールド	必須	説明
`organization_id`	どちらか必須	外部サービス上の組織 ID（推奨）
`email`	どちらか必須	リードのメールアドレス
`status`	必須	`qualified`（適格）のみ。`won` はブラウザのタグからは送信できません

organization_id はどこに保存されますか？

organization_id が送信されると、Jolt のリード詳細画面のカスタムフィールドに「組織ID」という項目が自動で作成され、値が保存されます。

手動でフィールドを作成する必要はありません。プログラムに対して初めて organization_id が送信されたタイミングで自動作成されます

ベンダーの管理画面（リード詳細）でのみ確認できます

パートナーの画面・リードフォームには表示されません

このカスタムフィールドは編集・削除することはできません

リードの特定ロジック（タグの場合）

タグ（STEP 2）から送信された情報をもとに、以下の順番でリードを検索します。（STEP 3 のサーバー間 API は指定した値で完全一致検索を行い、該当が無ければ 404、複数あれば 409 を返します）

organization_id が送られた場合 → 組織 ID でリードを検索

見つからない・未指定の場合 → メールアドレスで検索

複数該当する場合 → 最も新しく作成されたリードを対象

💡 organization_id を推奨する理由： メールアドレスだけでは、無料トライアルのサインアップ担当者と有料プランへのアップグレード担当者が異なる場合（担当者変更など）に正しくリードを特定できないケースがあります。組織 ID を使うことでこのような場合でも確実に照合できます。

仕様・制約

エラーにならないケース（サイレント処理）

以下はエラーを返さず正常終了（HTTP 200）として扱われます。ツール側でエラーが出ていなくても Jolt 側が更新されていない場合があるため、動作確認は Jolt 管理画面のリード詳細でご確認ください。

ケース	動作
`organization_id` / `email` に一致するリードが存在しない	スキップ
すでに同じステータスが設定されている	スキップ
`取引成立` から他のステータスへの後退	スキップ（`取引成立` は最終状態）

エラーになるケー

上記のサイレント処理はタグ（STEP 2）の振る舞いです。STEP 3 のサーバー間 API はサイレント処理ではなく、失敗をステータスコードで返します。呼び出し側で必ず確認してください。

コード	経路	意味
`400`	タグ	ブラウザのタグから `won` を送った（この経路では受け付けられません）
`401`	API	API キーが未指定または不正
`404`	API	指定したリードが見つからない（値の不一致など）
`409`	API	指定した条件に複数のリードが一致した
`422`	API	許可されていないステータス遷移（`新規` から `取引成立` など）

よくある質問

Q. 初回ログイン時に organization_id が登録されないことはありますか？

あります。コンバージョンタグがリードを作成する処理と、ステータス更新タグの処理がほぼ同時に走る場合、タイミングによっては初回ログイン時に失敗する場合があります。2 回目以降のログイン時に自動で登録されます。アップグレードまでに複数回ログインすることがほとんどのため、実用上の問題はありません。

Q. 有料転換したのに Jolt 上のステータスが変わらない

まず、アップグレード完了ページにタグを設置して won を送っていないかをご確認ください。ブラウザのタグからの won は受け付けられず、タグはエラーを画面に出さないため、見た目上は何も起きないままになります。STEP 3 のサーバー間 API に切り替えてください。

次に、Jolt 管理画面のリード詳細で「組織ID」フィールドに値が入っているか確認してください。入っていなければ STEP 2 のタグが発火していない可能性があります。

その上で、STEP 3 の API のレスポンスコード（上記の「エラーになるケース」）をご確認ください。

Q. 適格（qualified） を飛ばして最初から 取引成立（won） にできますか？

できません。リードのステータスは 新規 → 適格 → 取引成立 の順に遷移します。新規 のまま 取引成立 を指定すると、サーバー間 API は 422（許可されていない遷移）を返します。STEP 2 のタグで 適格 にしてから STEP 3 を呼び出してください。