Skip to content

ClickBank

ClickBank is the first integrated affiliate network in Brandvelia, but the architecture is designed so it can be decoupled and extended to other networks (INS, MarketHealth, Stevemcd, Brainborn, etc.) and to the operator's own products.

What's integrated

Everything below lives in packages/integrations/src/clickbank/:

Capability Adapter
Link builder ClickBankLinkBuilder / buildClickBankLink — HopLinks with extclid (unique click id) + named parameters (campaign, adgroup, ad, creative, trafficSource, trafficType) mirrored to aff_sub1-5.
INS 8.0 decryptInsNotification (AES-256-CBC, key = first 32 chars of SHA-1(secret)), normalizeInsOrder, insDedupKey, insTrackingCodes, insCampaignName, parseInsTimestamp.
QuickStats ClickBankQuickStatsClient (listAccounts, listDaily, count) — requires CLICKBANK_API_KEY_1/_2 (Developer/Clerk keys).
Marketplace feed fetchSampleMarketplaceCatalog — a static sample catalog (14 items, source: sample_catalog) used only as Radar seed/demo; real-data ingestion is pending verified source access (see below).
Opportunity Score calculateOpportunityScore — deterministic 0–100 score feeding the Radar.

Webhook → attribution

ClickBank-style webhooks (POST /api/webhooks/clickbank) drive the whole funnel:

  1. The raw body is decrypted/decoded from INS (decryptInsNotification).
  2. insTrackingCodes(order) resolves the click_id to a bv_visits row.
  3. That visit points to a landing page → campaign → offer, all inside the workspace.
flowchart LR
    CB[ClickBank<br/>webhook] --> INS[INS decrypt]
    INS --> VIT[bv_visits<br/>click_id]
    VIT --> LP[landing_page]
    LP --> CAM[campaign]
    CAM --> OFF[offer]
    VIT --> ORD[bv_transactions]

Vendored API reference

The ClickBank REST API is documented as JSON schemas in clickbank-api/:

File Coverage
products-v2.json Offer/product catalog.
orders-v2.json Order flow (full request/response flow, normal order, incomplete order, missing fields).
analytics-v1.json Analytics definitions.

Vendored credentials

ClickBank credentials are handled specially:

  • They can be vendored to known trusted links, but are never committed to the repository.
  • Rotated + tracked — every secret rotation has its own tag, so rotation is auditable.
  • The credential may be on a limited lifetime and can be destroyed (memory-only) or held as a file in the deployment pipeline.

Marketplace data sources (verified 2026-08-20)

The Radar needs real marketplace data (gravity, payouts, rebill). Verified facts:

  • No anonymous public XML feed exists. The URLs historically cited for a daily marketplace XML feed (marketplace.clickbank.net, marketplace-downloads.clickbank.net) do not resolve (NXDOMAIN). Do not build ingestion against them.
  • The marketplace web UI (www.clickbank.com/marketplace → accounts.clickbank.com/marketplace.htm) requires an authenticated affiliate session.
  • The REST API (api.clickbank.com/rest/1.3/...) exists and returns 401 without Developer/Clerk keys — generating those keys is an operator action in the ClickBank account and is the official path to structured data (QuickStats, Orders v2, Analytics v1.3 — schemas vendored in clickbank-api/).

Authorized ingestion paths for Brandvelia:

  1. ClickBank REST API once Developer/Clerk keys are provisioned (CLICKBANK_API_KEY_1 / CLICKBANK_API_KEY_2).
  2. Operator-provided snapshots (CSV/JSON export imported via SnapshotImportDialog / importMarketplaceSnapshotsAction) — validated with Zod, score computed deterministically on import.
  3. Configured feed URL (MARKETPLACE_FEED_URL env) — if ClickBank exposes an authenticated feed file for the account, the daily cron ingests it; without it the cron records a skipped_no_source run instead of failing.

Every snapshot row keeps source, captured_at and (for imports) the operator as provenance — marketplace data is never invented, and scraping is out of scope unless an official export/API path exists (master plan §7).