Cello

View saved version →

---
name: cello-get-integration-guide
description: Generate a tailored, step-by-step guide for integrating Cello (referral/attribution tracking) into a specific application. Use this whenever a developer says they want to "integrate Cello," "add Cello to my app," "set up referral tracking," or "add attribution tracking," especially when they haven't integrated it yet or are starting from scratch. Also trigger if someone asks "how do I add Cello to [React/Next.js/Rails/etc]" or pastes their codebase/repo and asks for an integration plan. This analyzes the actual app (frontend framework, mobile vs. web, payment gateway, signup flow) before generating the guide — it does not just paste the generic docs. Do not use this for debugging an *existing* integration (use cello-integration-health-check for that instead).
compatibility: Requires the Cello MCP server (cello_search_documentation, and ideally cello_get_integration_status for the final verification step). Works best with read access to the target codebase (package.json, requirements.txt, webhook handlers, etc.) so the stack can be detected automatically instead of asked about.
---

# Cello Integration Guide Generator

Produces a step-by-step Cello integration plan customized to the app you're actually integrating into — not a copy of the generic docs. The generic path (docs.cello.so/integration-overview) has 4 steps that apply to everyone, but steps 2 and 4 branch hard depending on the app's stack, and most of the actual work is picking the right branch.

## Step 1: Analyze the app

Before writing any guide, figure out:

1. **Platform**: Web app, mobile app (iOS/Android/React Native), or both?
2. **Frontend framework**: Plain JS/HTML, React, Vue, Angular, Next.js, etc. (Cello's referral component is a script tag + JS API, so it works with all of these — but the mount pattern differs, e.g. SPA re-render timing matters for custom launchers.)
3. **Signup flow**: Does the user sign up on a web form the app controls, via a form tool (HubSpot, Typeform), or via mobile?
4. **Payment/billing system**: Stripe, Chargebee, or something else (custom billing, Paddle, etc.)? And critically: is the gateway customer object created at signup, or only later at purchase/checkout? This timing question — not just "which gateway" — is what actually determines the step 4 path (see Step 2 below), so don't skip it even if Stripe/Chargebee is confirmed.
5. **Auth/user identity**: Where does a stable user ID (or email) live at signup time, that can be attached to Cello as the `ucc` (unique customer code) reference?
6. **Buying persona — user or organization?**: Does the app have organizations/teams/workspaces, and does the *purchase* happen at the org level rather than the individual level (e.g. a workspace admin pays for the whole team)? This determines whether attribution needs to run on the user or the organization, which changes what ID gets passed at several points — don't skip this even for straightforward B2B SaaS apps, since it's easy to assume user-level by default when the actual buyer is the org.
7. **New user discount wanted?**: Does the app want to offer referred users a discount at signup/checkout? This is optional and separate from the core 4 steps — ask if unclear rather than assuming yes or no.

**How to gather this:**
- If you have codebase access: check `package.json`/`requirements.txt`/`Gemfile` for frontend framework and payment SDKs (`stripe`, `chargebee`), grep for webhook handler routes, check for existing auth/session code.
- If you don't have codebase access, or something's ambiguous (e.g. multiple payment integrations found, or none): ask the developer directly rather than guessing. Getting the payment gateway wrong wastes their whole step 4.

## Step 2: Map findings to the 4 setup steps

Use `cello_search_documentation` to pull the exact, current content for each — don't rely on memory, since Cello's docs and snippets change. Map based on what Step 1 found:

| Setup step | Branch on |
|---|---|---|
| 1. Referral component | Web → JS quickstart. Mobile → iOS / Android / React Native SDK. |
| 2. Capture referral codes (`ucc`) on landing | Web signup → web signup flow guide. Mobile → mobile signup flow. Form tool → HubSpot/Typeform guide. |
| 3. Track signups | Same for everyone at this stage — POST /events or the tracking-signups guide — but the exact call site depends on where Step 1 found the signup happens (frontend vs backend). |
| 4. Track purchases | See three-way branch below. |

Step 4 has a real three-way branch — get this one right, it's the highest-cost step to redo:

1. **Stripe/Chargebee, gateway customer created at signup** → full prebuilt webhook quickstart (Stripe/Chargebee Webhook Quickstart). Fastest path, mostly config not code, ~1-2 days guided.
2. **Stripe/Chargebee, gateway customer created at purchase (not signup)** → use the Cello API directly for signup events, and only the Stripe/Chargebee webhook for purchase events. The gateway customer must carry `cello_ucc` (and `new_user_id` matching the `productUserId` used to boot the widget) as metadata at creation time — if the customer is created at purchase, that metadata has to be set right there, not inherited from an earlier signup step.
3. **Any other gateway** → generic tracking-purchases guide via the Cello API, called manually from the app's own payment success handler.

Say which of the three applies, explicitly and early — developers often assume "we use Stripe" alone determines the path, when actually *when* the customer object is created is what matters.

## User-level vs. organization-level attribution

If Step 1 found the buying persona is the organization (a workspace/team pays, not the individual), attribution must run at the org level — this touches the widget boot, the signup event, and the purchase event, not just step 4. Always call this out as its own consideration in the generated guide when it applies, since it's easy to wire only part of it and end up with inconsistent attribution.

- **Widget boot**: pass `orgIds` (the list of organizations the logged-in user belongs to) in the boot/token payload, alongside `productUserId`. This enables automatic attribution for org-based referrals — without it, Cello has no way to associate the individual user with their organization at boot time.
- **Signup event** (`new-signup` via Cello API — only relevant if you're not using the Stripe/Chargebee webhook path): set `payload.newUserId` to the **organization ID**, not the individual user's ID, when the referrer should be rewarded for organization account expansion rather than a single seat. The individual's own ID still goes in `context.newUser.id` (must match `productUserId` used to boot the widget) — only the top-level `newUserId` used for attribution switches to the org ID. Optionally also set `context.newUser.organizationId` alongside it.
- **Stripe/Chargebee path**: there's no separate "purchase event" to set fields on — metadata is set **once, on the customer object**, at creation (or update, for the purchase-first flow) via `new_user_organization_id` (Chargebee) or the equivalent Stripe customer metadata field, alongside `cello_ucc` and `new_user_id`. Every subsequent `invoice.paid`/`invoice-paid` webhook event inherits attribution from that customer record automatically — you don't touch anything per-purchase.
- **Cello API path** (no Stripe/Chargebee webhook — e.g. custom billing, or sending purchase events manually): here purchase events (`invoice-paid`, `charge-refunded`) genuinely are sent individually, and each one needs `payload.newUserId` set to the organization ID directly in that event's payload, the same way the signup event does.
- **Rule of thumb to state plainly in the guide**: wherever `newUserId` normally goes, the org ID goes there instead when attributing at the org level. Where that setting actually happens depends on the integration method — once on the customer object for Stripe/Chargebee, or per-event for the Cello API — so be explicit about which one applies rather than saying "purchase event" generically.

Ground this section in the live doc rather than memory (`cello_search_documentation` query on "organization level attribution"), and reference: https://docs.cello.so/attribution/introduction#how-it-works

## New user discounts (optional)

Only include this section if the developer wants to offer referred users a discount — it's a genuine add-on, not a required part of the 4-step setup, so don't assume it's wanted just because signup/purchase tracking is being built. Ask if it's unclear.

There are two independent halves — don't conflate them:

**1. Displaying the discount on the landing page.** Uses the Attribution JS methods already installed for step 2 (`getUcc`/`getReferrerName`). Add `getCampaignConfig()`, which returns `{ newUserDiscountPercentage, newUserDiscountMonth }`, and render it inline (banner/CTA copy) on the landing or signup page. This is purely cosmetic — it doesn't apply anything, it just shows the visitor what they'd get.

**2. Actually applying the discount at checkout.** This is a separate integration step that happens in the subscription platform, not in Cello:
   - First, discount coupons must be configured directly in Stripe/Chargebee/etc. (plan-level, with coupon IDs stored in the app's config) — this is a one-time platform setup step, not something Cello does.
   - Then, at the moment of subscription creation, the app needs to check whether the new user is a Cello referral and, if so, apply the matching coupon. There are three ways to check eligibility, and the developer only needs one:
     - **New User Reward API** (`GET /new-users/{productUserId}/reward`) — the recommended, explicit approach. Call it before checkout (i.e. before the user/org hits the subscription/payment step) with the user's `productUserId`. Returns `eligible`, and if true, `reward.percentage`/`reward.intervalCount` plus the `referralUcc` and campaign info. This is the cleanest option because it doesn't require the app to have already stored or synced any referral data itself.
     - **Check the Stripe/Chargebee customer object directly** — if `cello_ucc` was already added to the customer at signup/creation (per the attribution setup in earlier steps), the app can just read it off the customer record it already has, with no extra API call.
     - **Check the app's own stored signup data** — if the app cached the `ucc`/eligibility info itself during signup tracking, it can rely on that instead of calling anything at checkout time.
   - This eligibility check is optional infrastructure, not a hard requirement — say this explicitly in the guide: the Reward API exists to make it easier when the app doesn't already have the referral data on hand at checkout, not because it's the only way to do this.
   - Apply the resolved coupon at subscription creation: Stripe uses the `discounts` array or `coupon` parameter on the Checkout Session; Chargebee applies `coupon_ids` on the Subscription (or via Hosted Pages) — not at customer creation, at subscription creation specifically.

Reference these when generating this section: https://docs.cello.so/guides/user-experience/new-user-discounts, https://docs.cello.so/attribution/apply-discounts, https://docs.cello.so/api-reference/new-users/get-reward

## Step 3: Generate the guide

Output an ordered, numbered guide — not a dump of every doc link. For each of the 4 steps:

- State what it does in one line and why it matters for that specific app (e.g. "Since you're using Next.js, mount the referral launcher in a persistent layout component, not per-page, so the SPA client re-render on route change doesn't fight fresh initialization of it.")
- Give the concrete action (code snippet, config location, or webhook URL to register) pulled from the doc content fetched in Step 2 — not paraphrased from general Cello knowledge, since exact field names and snippet syntax matter here.
- Flag any prerequisite from a prior step it depends on (e.g. step 3 needs the `ucc` captured in step 2 to actually attribute the signup).

End with a verification note: once implemented, they can run an integration health check (the `cello-integration-health-check` skill, if installed) against `cello_get_integration_status` and `cello_get_events` to confirm signups/purchases are actually being attributed — don't just trust that the code is right.

## Output format

```
## Cello Integration Plan for [app name/stack]

**Detected:** [platform] · [frontend framework] · [payment gateway] · [signup flow] · [user-level or org-level attribution]
**Fast path available:** [yes/no — Stripe/Chargebee webhook note if relevant]

### Step 1: Referral Component
[why this shape for this app]
[snippet/action]

### Step 2: Capture referral codes
...

### Step 3: Track signups
...

### Step 4: Track purchases
...

### New user discounts (if applicable)
[landing page display + checkout-time eligibility check + coupon application]

### Verify it worked
Run an integration health check once deployed to confirm events are actually attributing.
```

## Edge cases

- **Mixed or unclear payment setup** (e.g. Stripe SDK present but also custom invoicing code): ask rather than assume — this is the highest-cost branch to get wrong.
- **No payment gateway at all yet (pre-monetization app)**: still do steps 1-3, note that step 4 can be added later, and point to the generic tracking-purchases guide as the eventual path once billing exists. Or recommend to reach out to Cello Support to clarify.
- **Docs conflict with what's actually in `cello_search_documentation`'s live result**: always trust the live fetch over anything remembered from a prior guide generation — Cello's docs change.
- **Org-level attribution requested but only some touchpoints wired** (e.g. org ID used in the purchase event but the widget still boots without `orgIds`): flag the gap explicitly rather than treating partial org-level setup as done — inconsistent attribution across the three touchpoints is a common failure mode here.

View saved version →

---
name: cello-get-program-performance
description: Analyze Cello's referral program health, trends, industry benchmarks, prioritized recommendations, and top-performing referrers into one performance readout. Use this whenever someone asks how their referral program is doing, wants a performance summary, asks "how are we trending," "how do we compare to industry," "what should we improve," "who are our top referrers," or wants a recurring digest (weekly/monthly) of program health. Also trigger for questions like "why did signups drop" or "are we above/below benchmark" — this pulls metrics, recommendations, and top referrers together rather than answering from any single tool alone. Do not use this for integration/technical debugging (use cello-integration-health-check) or for a deep fraud/anomaly investigation into a specific referrer (this skill flags an obviously odd top-referrer ratio in passing, but a dedicated referrer-analysis skill should do the actual investigation).
compatibility: Requires the Cello MCP server (cello_get_program_metrics, cello_get_recommendations, and cello_get_top_referrers tools).
---

# Get Program Performance

Turns raw metrics and recommendation data into a readout that actually says something — not just a table of numbers. The core value-add is connecting the two: a metrics dip is more useful paired with the specific recommendation that addresses it, and a recommendation is more convincing paired with the number it would move.

## Workflow

1. **Call `cello_get_program_metrics`.** This returns lifetime totals, weekly/monthly history, and industry benchmarks in one call.

2. **Call `cello_get_top_referrers`.** This returns the top 10 referrers ranked by revenue, with signups, recurring purchases, ARR, days active, and days sharing per referrer.

3. **Call `cello_get_recommendations`.** This returns a prioritized (impact-weighted) list of improvement actions and their completion status.

4. **Connect them — this is the actual analysis, not just reporting each tool's output separately:**
   - Identify the most significant trend(s) in the metrics: compare last-30d vs. prior-30d across referrers enabled, active referrers, sharing activity, signups, and recurring purchases. Note when a headline number (e.g. ARR) is moving opposite to the underlying activity metrics — lagging revenue recognition can mask a cooling funnel, and that gap is often the most important thing to surface, not the ARR figure alone.
   - Check each metric against its industry benchmark where available. Being above benchmark doesn't mean "nothing to improve" — say so if the trend is declining even while still above benchmark, since trajectory matters as much as the snapshot.
   - Cross-reference declining metrics against the recommendation list: does an unfinished recommendation directly address the metric that's slipping? If so, lead with that pairing — it's the most actionable insight in the whole readout ("sharing is down 10% and 3 of 3 Sharing-category recommendations are still open").
   - Note top completed vs. incomplete recommendations by impact weight, so the highest-leverage open item is never buried.
   - From the top referrers list, note whether a small number of referrers account for a disproportionate share of revenue/signups (concentration risk for the program, independent of any individual fraud question) — this matters for performance framing even without flagging fraud specifically.
   - While reviewing top referrers, do a light plausibility check on the ratio of `daysActive` to `daysSharing` versus signup volume — a referrer with very few sharing days but outsized signups is worth one flagged line (not a full writeup) since it's the kind of thing worth a closer look. Keep this brief: name the referrer and the specific ratio, then suggest a dedicated referrer/fraud-analysis pass if one is available, rather than investigating further here — that's a different skill's job.

## Output format

Keep it to a short readout, not a dashboard dump — lead with what changed and what to do about it, not a wall of metrics:

```
## Program Performance: [headline — e.g. "cooling activity despite rising ARR"]

**Trend:** [most important month-over-month shift, with the benchmark comparison if relevant]
**Why it matters:** [connect to lagging indicators if headline metric is masking it]

### Top opportunity
[highest-impact-weight open recommendation, tied explicitly to the metric it would move]

### Other notable shifts
- [metric]: [change] (benchmark: [industry figure], you: [your figure])
- ...

### Recommendations status
[x/y done] — remaining gaps by category

### Top performing referrers
[top 2-3 by revenue, with signups/ARR]
[one-line concentration note if a small handful dominate]
[flag only if a ratio genuinely looks off — otherwise omit this line entirely]
```

Don't just list every metric returned by the tool — pick the ones that moved meaningfully or sit near/below benchmark. A flat, healthy number doesn't need a line.

## Edge cases

- **ARR/revenue rising while activity metrics fall:** always call this out explicitly rather than leading with the revenue figure — it's the single most common way a program looks healthier than it is, since revenue recognition lags the referrer activity that drives it.
- **All recommendations in one category are open (e.g. all of Sharing):** treat this as a pattern, not three separate line items — say the category is the gap, then name the top one or two by impact weight.
- **No benchmark data available for a given metric:** just report your own trend without forcing a comparison; don't imply a benchmark exists if the tool didn't return one.
- **Recurring/digest use** (e.g. "give me my weekly program update"): keep the same structure, but explicitly note what changed since the last readout if that context is available in conversation; otherwise treat it as a fresh snapshot rather than guessing at a prior baseline.

View saved version →

---
name: cello-integration-health-check
description: Diagnose whether a Cello referral/attribution integration is working correctly, right from the IDE. Use this whenever a developer asks if their Cello integration is set up correctly, why referral or attribution events aren't showing up, why signups or purchases aren't being attributed, or reports symptoms like "referral widget isn't loading," "attribution isn't tracking," "UCC not found," or "events aren't firing." Also trigger when someone is mid-integration and asks "is this working?", "why isn't this tracking?", or wants a pre-launch sanity check before shipping a Cello integration. Proactively suggest this skill if a developer pastes Cello SDK/webhook code and expresses uncertainty about whether it's correct.
compatibility: Requires the Cello MCP server (cello_get_integration_status and cello_get_events tools). If these tools are not available, tell the user to connect the Cello MCP server first.
---
 
# Cello Integration Health Check
 
A diagnostic skill that turns a raw Cello integration status check into a clear, actionable report a developer can act on without leaving their editor.
 
## When to use this
 
Use this skill whenever someone wants to know if their Cello integration is healthy, or is debugging why referral tracking / attribution / signup / purchase events aren't showing up as expected. This is a "help me right now, mid-debugging" tool — it should feel fast and concrete, not like a dashboard export.
 
## Workflow
 
1. **Call `cello_get_integration_status`** first. This checks all four integration components in one shot:
   - Referral Widget (cello.js)
   - Attribution Widget (cello-attribution.js)
   - Signup tracking
   - Purchase tracking
2. **Call `cello_get_events`** next, regardless of whether step 1 found problems. The events feed often explains *why* a component is flagged — e.g. a component can show "connected with warnings" because events are arriving but failing validation (missing required fields), which status alone won't reveal.
3. **Cross-reference the two.** For each component that isn't fully healthy:
   - Check the events feed for related event types (signup, purchase/invoice, attribution) with `status: error` or `issuesCount > 0`.
   - If you find matching errors, name the specific missing/invalid field(s) — don't just say "there's an issue."
   - If no related errors appear in the events feed but the component is still flagged, it's likely a "no recent activity" warning rather than a broken integration — say so explicitly, since these read the same but mean different things to a developer mid-build.
4. **If something is broken or missing, use `cello_search_documentation`** to pull the specific fix — don't send the developer to go search for it themselves. Surface the doc link inline with the specific action needed.
## Output format
 
Keep it scannable — a developer is context-switching from their code, not reading a report. Structure as:
 
```
## Integration Health: [X/4 healthy]
 
### ⚠️ [Component name]
**What's happening:** [plain-language diagnosis]
**Likely cause:** [root cause if found in events feed, otherwise "no recent activity" vs "broken" distinction]
**Fix:** [specific action + doc link]
 
### ✅ [Component name]
Working correctly, no issues.
```
 
If event errors are found, always name the exact field(s) involved (e.g. "the `interval` field is missing from your `invoice-paid` payload") — this is the single most useful detail for a dev fixing webhook code, and it's exactly what the raw event payload gives you.
 
## Edge cases
 
- **All components flagged, but events feed is empty or all-valid:** this usually means low/no recent traffic rather than a broken integration. Say this plainly — don't alarm the developer over a quiet period.
- **Some events are errors but the affected component shows as healthy:** mention it anyway as a heads-up (e.g. a webhook occasionally sends bad payloads even if enough valid ones get through to pass the health check).
- **Developer pastes SDK/webhook code and asks "does this look right?":** run the two tools anyway to check the *live* result rather than only reviewing the code — code can look correct and still be misconfigured (wrong UCC field name, wrong event name string, etc.), and the events feed is ground truth.
- **No live signups yet if a fresh implementation is still local/staging:** clarify whether the developer expects a live event to have fired; if not, this isn't a bug and the skill should say that framing explicitly instead of reporting "0 events" as a failure.

## Tone
 
Be direct and specific. Developers debugging an integration want the diagnosis and the fix, not a course on Cello's architecture. Lead with what's broken (if anything), not with a summary of what the tool checked.