Ops Lab Playbook: Campaign Control

Last updated: 2026-03-12

1. Purpose and when to use this

Use this module to launch and validate a campaign end to end: create the campaign record, bind it to a tracked link, generate at least one real click and ctx token, run a synthetic conversion, and confirm campaign analytics.

2. User roles and auth modes

[Creator] [Operator] JWT: campaign create/list, link binding, health check, test conversion, and analytics verification.
Public/visitor (no auth): one real short-link click is required if you want health to confirm click and ctx generation.
[Escalation] If destination trust policy blocks the link target or health stays red after confirmed traffic, capture artifacts and escalate through support.

3. Prerequisites checklist

Primer completed: Onboarding and API Primer
HANDLE, JWT_TOKEN, and API_BASE configured.
Either an existing link slug or a destination URL for primaryLink.
PUBLIC_DOMAIN is known for the public short-link click step.
Use a test destination that safely accepts a ?ctx= query parameter.

4. UI onboarding flow

Open https://app.10x.in/creator/campaign-control.
Create the campaign and either create an inline primary link or reuse an existing link slug.
Open the campaign short URL once to seed click and context telemetry.
Run campaign health and verify the readiness checks move toward PASS.
Run a test conversion.
Confirm funnel analytics and, when segment data exists, segment analytics for the campaign.

5. API workflow map

CC-01: POST /v2/handles/{handle}/campaigns (JWT)
CC-02: PUT /v2/handles/{handle}/links/{slug} (JWT, optional when binding or updating an existing link)
CC-03: GET https://{handle}.10x.in/{slug} (public click seeds click + ctx)
CC-04: GET /v2/handles/{handle}/campaigns/{campaignId}/health (JWT)
CC-05: POST /v2/handles/{handle}/campaigns/{campaignId}/test-conversion (JWT)
CC-06: GET /v2/handles/{handle}/analytics?funnel=true&campaignId=... (JWT)
CC-07: GET /v2/handles/{handle}/analytics?groupBy=segment&campaignId=... (JWT, optional)

6. cURL examples

Set module variables:

export CAMPAIGN_ID="spring-launch"
export SLUG="spring-launch"
export DESTINATION_URL="https://example.com/products/spring-drop"

CC-01 Create campaign with inline primary link

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/campaigns" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "campaignId":"'"${CAMPAIGN_ID}"'",
    "goalType":"PRODUCT_SALE",
    "status":"ACTIVE",
    "conversionEventType":"purchase",
    "primaryLink":{
      "slug":"'"${SLUG}"'",
      "destinationUrl":"'"${DESTINATION_URL}"'",
      "title":"Spring Drop",
      "enabled":true,
      "tracking":{
        "mode":"DIRECT",
        "appendContextParam":true
      }
    }
  }'

CC-02 Attach or rebind an existing link to the campaign (optional)

curl -sS -X PUT "${API_BASE}/v2/handles/${HANDLE}/links/${SLUG}" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "destinationUrl":"'"${DESTINATION_URL}"'",
    "campaignId":"'"${CAMPAIGN_ID}"'",
    "trackingPolicy":{
      "mode":"DIRECT",
      "appendContextParam":true
    }
  }'

CC-03 Generate one real click and capture the redirect headers

curl -sS -D - -o /dev/null "https://${HANDLE}.$10x.in/${SLUG}"

CC-04 Campaign health

curl -sS "${API_BASE}/v2/handles/${HANDLE}/campaigns/${CAMPAIGN_ID}/health" \
  -H "authorization: Bearer ${JWT_TOKEN}"

CC-05 Test conversion

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/campaigns/${CAMPAIGN_ID}/test-conversion" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "eventType":"purchase",
    "value":1499,
    "currency":"INR",
    "metadata":{"source":"playbook","test":true}
  }'

CC-06 Funnel analytics for the campaign

curl -sS "${API_BASE}/v2/handles/${HANDLE}/analytics?funnel=true&campaignId=${CAMPAIGN_ID}" \
  -H "authorization: Bearer ${JWT_TOKEN}"

CC-07 Segment analytics for the campaign (optional)

curl -sS "${API_BASE}/v2/handles/${HANDLE}/analytics?groupBy=segment&campaignId=${CAMPAIGN_ID}" \
  -H "authorization: Bearer ${JWT_TOKEN}"

7. Expected success outputs and verification checks

Campaign create returns 201 with campaign and quickStart; campaign.primarySlug and campaign.primaryLink identify the bound short URL.
Public click returns 302; Location should include ctx= when trackingPolicy.appendContextParam is enabled.
Health returns overallStatus, checks, clickCount, conversionCount, and timestamps. A fully validated path typically shows primary_link, click_seen, ctx_generated, conversion_recorded, and conversion_event_config as PASS.
Test-conversion returns 201 with ok, conversionId, idempotencyKey, eventType, value, and currency.
Funnel analytics returns campaign rows with clicks, qualifiedClicks, conversions, revenue, and confidence.
Segment analytics returns rows only after segment rollups exist for the handle/campaign scope.

8. Failure modes and remediation

400 invalid_campaign_id or 400 invalid_primary_slug:
Remediation: use lowercase campaign IDs and a valid slug format.
404 primary_link_not_found during campaign create with primarySlug:
Remediation: create or repair the link first, then retry campaign create.
404 campaign_not_found during link bind, health, or test-conversion:
Remediation: confirm the handle and campaignId pair is correct.
409 campaign_conflict:
Remediation: choose a new campaign ID or reuse the existing campaign record.
Health stays NEEDS_ATTENTION:
Remediation: click the short URL once, ensure the link is enabled, and confirm the redirect appends ctx.
400 invalid_tracking_policy or destination trust rejection on link upsert:
Remediation: reduce the tracking payload to supported keys (mode, appendContextParam, optional template refs) or use an allowed destination domain.

9. Async behavior notes

Campaign create, link upsert, health, and test-conversion are synchronous (SYNC).
Public redirect writes click events and campaign rollups immediately, then emits link.routed and link.context_created.
Health emits campaign.health_changed; test-conversion emits conversion.tested.
Analytics is rollup-based and may lag by up to 1 hour.