> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Cello + Cursor integration
> How to add user referrals to your app using Cello with Cursor
Cursor can implement Cello user referrals end-to-end if you give it the **right guide** and force it to create a plan before coding.
## Prerequisites
Before integrating Cello, ensure the following prerequisites are met:
* User signup and authentication is functional
* Stripe subscription flow is functional
* You have a Cello account and API keys at hand.
You can integrate directly on production - your account stays in **pre-launch phase** until you launch, so all events are recorded as test data and nothing is paid out. A sandbox is optional if you prefer a separate environment.
## Connect the Cello MCP
Connect the [Cello MCP server](/mcp/introduction) before you start. It gives Cursor direct access to Cello's documentation, your integration status, your incoming events, and best-practice recommendations, so Cursor can look up the right docs itself, verify your setup as it goes, and follow best practices automatically instead of relying only on the guide link you paste.
Open **My account → MCP Server** in the [Cello Portal](https://app.cello.so/mcp), turn the server on, and use the one-click connect for your tool - or the generic option if it doesn't have its own card yet. There's no token to generate or paste. See [Connect your client → Cursor](/mcp/connect#cursor) for more detail.
## Cello user referrals integration
For a step-by-step technical implementation (source of truth + acceptance criteria), follow the detailed guide:
* [React + Node.js Integration Guide](/resources/react-nodejs-integration)
The guide uses React + Node.js as an example, but it can be any other combination - the steps stay the same.
* Signup and authentication flow is functional
* Stripe subscription flow is functional
* Cello API keys are handy
* Get your webhook URL from [Cello Portal](https://app.cello.so/developers/webhooks)
* Add a Webhook endpoint in Stripe (Log into your Stripe Dashboard -> Go to Developer Mode -> Add a Webhook endpoint and enter endpoint URL -> Select the events to send -> Click "Add endpoint")
* Secure the Webhook with "Signing secret"
Events to send:
* `charge.refunded`, `charge.succeeded`, `charge.updated`
* `customer.created`, `customer.deleted`, `customer.updated`
* `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
* `invoice.paid`
See [Stripe Webhook Integration](/integrations/webhooks/stripe-webhook#steps) for more details.
Switch Cursor to **Plan mode**, then paste this prompt:
```text theme={null}
I want to add user referrals to my app using Cello.
Use the Cello MCP to search the integration documentation, check my current integration status, and create a thorough implementation plan. Follow all best-practice recommendations from Cello.
```
Cursor pulls the relevant guides, checks what's already set up, and tailors the plan to your project, asking you guiding questions before it writes any code.
Paste the guide URL instead. Cursor gets the documentation, but no integration status and no event inspection, so you'll have to verify the integration yourself.
```text theme={null}
I now want to add user referrals. I chose platform Cello for this.
I added a Cello integration guide according to which you should do the implementation. parsed the documentation more carefully from the start rather than assuming standard patterns would work. create a thorough implementation plan based on guidance, patterns and AC from the provided guide. Don't skip any content, it is all relevant
Guide: https://docs.cello.so/resources/react-nodejs-integration
```
Review the plan carefully. It should cover:
* Cello JS SDK initialization and user authentication
* Referral component placement and configuration
* Attribution setup for tracking referred signups
* Stripe webhook integration for conversion tracking
If it looks correct, tell Cursor to proceed and start implementing it.
Don't wait until the end. As Cursor finishes each part, ask it to check that part before moving on:
*"Use Cello to check my integration status - is the attribution library connected yet?"*
The four things the plan covers are the same four the health check reports on, and the same four you'll test later in the [pre-launch testbook](/guides/integration/pre-launch-testbook#test-by-area):
| What you just built | In the health report | Testbook section |
| - | - | - |
| SDK initialization and referral component placement | Referral component | [Referral component](/guides/integration/pre-launch-testbook#referral-component) |
| Attribution setup | Attribution library | [Capturing the referral code](/guides/integration/pre-launch-testbook#capturing-the-referral-code) |
| Signup tracking | Signups tracking | [Signup tracking](/guides/integration/pre-launch-testbook#signup-tracking) |
| Purchase and conversion tracking | Purchases tracking | [Purchase tracking](/guides/integration/pre-launch-testbook#purchase-tracking) |
Two things to expect, so a partial result doesn't look like a failure:
* **All four components are reported every time.** The ones you haven't built yet read **Not connected**, which is correct at this stage. Only judge the one you just finished.
* **Status lags behind your code.** A component turns **Connected** once a successful event reaches Cello within the health window, which can take up to \~10 minutes. Re-check before concluding anything is broken.
If a component comes back with a warning, ask for the events behind it. The health check tells you *which* component is failing; the events tell you *why*:
*"Show me my recent Cello events and tell me which fields are failing validation."*
The [Pre-launch Testbook](/guides/integration/pre-launch-testbook) covers the manual, front-end checks no automated tool can see for you: whether the referral component sits well in your UI, whether the new-user banner reads correctly, and whether the discount math is right on both monthly and yearly plans.
Cursor can fetch it and walk you through it, because the testbook is part of the documentation the Cello MCP server searches:
*"Pull the Cello pre-launch testbook and walk me through the signup tracking section."*
Run your app and test the end-to-end flow. If everything was implemented correctly, you should see events coming in to the [Cello Dashboard](https://app.cello.so/performance/referrer-activity), marked as testing until you launch your program.
Events reach **Developers → Events** within a few minutes, but dashboards refresh hourly - see [when each surface updates](/guides/integration/pre-launch-testbook#when-each-surface-updates) before assuming something is missing.
## After you're live
If you have the Cello MCP connected, it continues to be useful after the initial integration:
| Prompt | What happens |
| - | - |
| *"Is my Cello integration working?"* | Checks all four integration components and reports which are connected or broken |
| *"Why aren't referral rewards being triggered?"* | Inspects recent events to find missing or malformed fields preventing attribution |
| *"How can I improve my referral program?"* | Returns a prioritized list of recommendations across activation, sharing, and conversion |
| *"Which recommendations need code changes?"* | Separates the optional enhancements that need dev work from the ones that are only portal configuration |
| *"How do I set up a custom referral launcher?"* | Searches the docs for custom launcher implementation guides |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.