Documentation

Help & Documentation

Everything you need to install Castlytics, set up campaigns, and interpret your attribution data.

01

Quick Start

Get from zero to tracking in three steps. The whole setup typically takes under 30 minutes.

1

Install the tracking script

Paste one <script> tag into the <head> of every page on your site. This sets the visitor cookie and detects vanity paths automatically.

2

Create your first campaign

Add a campaign for each creator placement. Castlytics generates a tracking link automatically. Optionally add a vanity path and promo code.

3

Record conversions

Call castlytics.conversion() on your order confirmation page. That's it — attribution is calculated automatically.

02

Installing the Tracking Script

Add this snippet to the <head> of every page on your website. Replace YOUR_PUBLIC_KEY with the key from your Settings page.

<script
  src="https://castlytics.app/tracker.js"
  data-workspace-key="YOUR_PUBLIC_KEY"
  defer>
</script>

The script does three things automatically:

  • 🍪Sets a first-party cookie (_cly_vid) with an anonymous random visitor ID
  • 📄Records every page view to build the visitor's journey
  • 🌐Detects vanity paths and fires attribution events — no per-page config needed
The script is tiny and loads with defer so it never slows your site down. It stores no personally identifiable information — only an anonymous UUID.
03

Creating Campaigns

Each creator placement gets its own campaign in Castlytics. Go to Campaigns → New Campaign and fill in:

Managing many campaigns at once? Use Campaigns → Import CSV to create dozens of campaigns in a single upload. Download the template from the import dialog to see the required format.
FieldRequiredNotes
Campaign NameYesYour internal label, e.g. 'Spring Promo — Acquired Pod'
Channel TypeYesPodcast, YouTube, Instagram, TikTok, Influencer, or Custom
Creator NameYesThe creator or show name
Destination URLYesWhere visitors land after clicking your tracking link
Tracking Link SlugNoCustom slug for your tracking domain, e.g. 'tim'
Vanity PathNoe.g. /tim — auto-detected by the tracker script
Promo CodeNoe.g. TIM10 — matched at conversion time
Ad SpendNoUsed to calculate ROAS in your dashboard
Attribution WindowNoHow long after a touch a conversion can be attributed (default 30 days)
05

Custom Domain — DNS Setup

To use links.yourbrand.com as your tracking domain, you need to add a CNAME record to your DNS.

Record TypeHost / NameValue / Points To
CNAMElinkscname.castlytics.app

Where links is whatever subdomain you chose (replace with the first part of your tracking domain). DNS changes propagate within a few minutes to 24 hours depending on your provider.

Common DNS providers:

Cloudflare

DNS → Add record → CNAME. Set 'Proxy status' to DNS Only (grey cloud).

GoDaddy

DNS Management → Add → CNAME. TTL: 1 hour.

Namecheap

Advanced DNS → Add New Record → CNAME Record.

Route 53

Hosted Zones → Create Record → CNAME. Alias: No.

06

Recording Conversions

A conversion is a purchase, signup, or lead. Record it by calling castlytics.conversion() on your confirmation page, or via a server-side API call from your webhook.

Option A — Client-side (on your order confirmation page)

<script>
  castlytics.conversion({
    type: 'purchase',   // 'purchase' | 'signup' | 'lead'
    revenue: 49.00,
    currency: 'USD'     // optional
  });
</script>

Option B — Server-side (from your checkout webhook)

fetch("https://castlytics.app/api/conversions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    publicKey: "YOUR_PUBLIC_KEY",
    visitorId: window._cly_vid,   // from the _cly_vid cookie
    type: "purchase",
    revenue: 49.00,
    currency: "USD",
    promoCode: "TIM10"            // optional: activates promo attribution
  })
})
The visitorId is automatically available as window._cly_vid after the tracking script loads. For server-side calls, read the _cly_vid cookie value from the request.

Option C — Shopify or WooCommerce (automatic, no code)

Connect your store under Settings → Integrations. Castlytics will automatically import orders as conversions and match coupon codes to the right campaigns. No JavaScript needed on your confirmation page.

Shopify

Connect via Custom App admin token. Sync the last 30 days on demand, or register the webhook for real-time ingestion.

WooCommerce

Connect via Consumer Key + Consumer Secret from WooCommerce → Settings → Advanced → REST API.

07

Attribution Models

When a conversion arrives, Castlytics looks back at all creator campaign touches within the attribution window and assigns credit. You can switch between models at any time — no data is lost.

ℹ️ Castlytics attributes conversions to your tracked creator and podcast campaigns only — not to Google, Meta, or organic traffic. For full cross-channel attribution, use Castlytics alongside GA4.

First Touch

100% credit to the first creator campaign touch. Best for understanding which creators introduce your brand to new audiences.

Last Touch

100% credit to the most recent creator campaign touch before conversion. Best for understanding which creators close the sale.

Equal Split

Credit split equally across all creator campaign touches. Best for a balanced view when a customer encountered multiple creators.

A touch can be a click (tracking link), a vanity path visit, or a promo code match. Promo code attribution only fires if no click or vanity visit was recorded — so there's never double-counting.

08

Incrementality Testing

Attribution tells you which campaigns got credit for conversions. Incrementality tells you which campaigns actually caused them. A visitor might have converted through Google regardless of hearing your podcast ad — attribution credits the campaign; true incrementality would not.

Castlytics is an attribution tool, not an experimentation platform. It provides the data you need for an incrementality analysis — the experimental design comes from you.

Method 1: CVR Comparison (quickest)

Compare the conversion rate of campaign-attributed visitors against all other visitors during the same period.

  1. In Castlytics: note attributed visitors and attributed conversions → compute attributed CVR
  2. In your analytics (GA, Plausible, etc.): get total visitors and total conversions for the same date range
  3. Subtract attributed figures from totals → compute baseline CVR for non-attributed visitors
  4. The gap is your directional lift signal
Attributed CVR: 4.2%−Baseline CVR: 2.8%=~1.4pp lift signal

⚠️ Directional only — attributed visitors self-selected (they clicked a link), so some of the gap is selection bias.

Method 2: Dark Period Test (most practical)

Best for ongoing creator relationships. Pause the campaign for one period and compare overall site CVR with and without it running.

  1. Run the campaign for 4 weeks — note your total site CVR each week from your analytics tool
  2. Pause the campaign for 2–4 weeks (change nothing else — no new campaigns, no sales)
  3. Compare total site CVR during the dark period vs. the campaign-on period
  4. The drop = incremental lift from the campaign

Cross-check: Castlytics attributed conversions should drop close to zero during the dark period. If they don't, investigate what's still triggering attribution signals.

Method 3: Geographic Holdout (most rigorous)

Use a market where the creator has little reach as a control group against a market where they have strong reach.

  1. Pick a creator with audience concentrated in one country (e.g. US-heavy podcast)
  2. Define a control market with minimal creator exposure (e.g. Australia, Canada)
  3. Run the campaign and track CVR by country in your analytics tool
  4. Test CVR minus control CVR = incremental lift estimate

If Castlytics shows attributed conversions from your "control" market, the creator has more reach there than expected — revise your control.

Start with Method 1 as a quick sanity check. If you see a meaningful lift signal, run Method 2 the following month to validate it with cleaner data. Method 3 is best for one-off campaigns where you can't go dark.
09

Post-Purchase Survey

The post-purchase survey adds a "How did you hear about us?" widget to your order confirmation page. Responses are automatically matched to campaigns, capturing sales that link clicks and vanity paths miss — especially important for word-of-mouth and offline mentions.

Step 1 — Configure the survey

Go to Settings → Post-Purchase Survey. Toggle it on, customise the question and answer options (one per line), and save.

Step 2 — Add the survey attribute to your snippet

If you already have the tracker script installed, add data-survey="true" to the existing tag on your order confirmation page:

<script
  src="https://castlytics.app/tracker.js"
  data-workspace-key="YOUR_PUBLIC_KEY"
  data-survey="true"
  defer>
</script>

The survey appears 1.5 seconds after page load as a fixed widget in the bottom-right corner. It shows only once per session.

How responses are matched to campaigns

Castlytics uses case-insensitive substring matching: if the visitor's answer contains the campaign name, creator name, handle, or promo code, the response is attributed to that campaign. For example, "I heard it on The Leverage Pod" will match a campaign named "The Leverage Pod Q1".

Viewing results

Survey responses appear in Dashboard → Surveys. You'll see total responses, the match rate, and a breakdown of answers. Matched responses also appear in the relevant campaign's attribution data.

Use a mix of preset options (podcast, YouTube, Instagram, Google search, a friend) and an "Other" free-text option to capture unexpected sources. Free-text answers are still auto-matched against your campaign names.
10

E-commerce Integrations

Connect Shopify or WooCommerce to automatically import orders as conversions and match coupon codes to campaigns — no JavaScript needed on your store. Go to Settings → Integrations to connect.

S

Shopify

Uses a Shopify Custom App with a read-only Admin API token. No Shopify Partner account required.

Setup:

  1. In Shopify admin: Settings → Apps and sales channels → Develop apps → Create an app
  2. Under Admin API access scopes, enable read_orders and read_customers
  3. Click Install app and copy the Admin API access token
  4. In Castlytics: Settings → Integrations → Shopify — enter your shop URL and token, click Connect
  5. Click Sync orders (last 30 days) to import historical data
For real-time ingestion without manual syncing, register https://castlytics.app/api/webhooks/shopify as a webhook in Shopify Admin → Settings → Notifications → Webhooks. Subscribe to Order creation and Order cancellation.
W

WooCommerce

Uses the WooCommerce REST API v3 with a Consumer Key and Consumer Secret. Read permissions only.

Setup:

  1. In WordPress admin: WooCommerce → Settings → Advanced → REST API → Add key
  2. Set Description to "Castlytics", User to an admin, Permissions to Read
  3. Click Generate API key and copy both the Consumer key and Consumer secret
  4. In Castlytics: Settings → Integrations → WooCommerce — enter your store URL and keys, click Connect
  5. Click Sync orders (last 30 days) to import historical data
For real-time ingestion, create two webhooks in WooCommerce → Settings → Advanced → Webhooks with topics Order created and Order updated. Set the Delivery URL to https://castlytics.app/api/webhooks/woocommerce.

How orders are matched: When an order contains a coupon code that matches a campaign's Promo Code field (case-insensitive), the order is attributed to that campaign. Orders without a matching coupon are still imported as unattributed conversions, contributing to your total revenue figures.

Customer quality metrics — refund rate and repeat buyer rate — appear on each campaign's detail page once you have Shopify connected and synced. These help you identify which creators drive your best long-term customers.
11

Billing & Cancellation

Simple, transparent billing — and cancellation that's genuinely hassle-free.

How billing works

Castlytics bills monthly, starting the day you upgrade. Your invoice is issued automatically and charged to your saved payment method. You can view and download all past invoices in Settings → Billing → Manage billing & invoices.

How to cancel — no strings attached

Go to Settings → Billing, scroll to the bottom, and click Cancel subscription. There's no form to fill in, no call to book, and no waiting period.

  • You keep full access until the end of your current billing period
  • You won't be charged again after that date
  • Your data is preserved — it will be there if you come back
  • A “Cancels at period end” badge appears on your plan card so you always know the exact end date

Changed your mind? Reactivate instantly

If you cancel and then change your mind before the billing period ends, go back to Settings → Billing and click Keep my subscription. Your subscription is immediately restored — no new checkout, no gap in access.

Need to switch to a different plan? Upgrades take effect immediately and are prorated. To downgrade, use Settings → Billing → Manage billing & invoices to access the Stripe billing portal, or contact us at hello@castlytics.app.