> ## 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 + Claude integration

> How to add user referrals to your app using Cello with Claude

Claude can implement Cello user referrals end-to-end if you give it the **right guide** and force it to create a plan before coding. Use **Claude Code** (the CLI coding agent) to build the integration, and connect the Cello MCP so Claude can look up docs and verify your setup as it goes.

<Note>
  This page covers using **Claude Code** to build your referral integration. To connect the **Claude desktop or web app** so you can chat about your program, see the [Claude](/mcp/connect#claude) section of the MCP connect guide.
</Note>

<img className="w-full rounded-xl" src="https://mintcdn.com/cello/4C7XEZmkMsMYyA_d/coding-apps/claude_cello.png?fit=max&auto=format&n=4C7XEZmkMsMYyA_d&q=85&s=a86705dbc261d8a68f049fe13715253c" alt="Cello + Claude integration" width="1957" height="1104" data-path="coding-apps/claude_cello.png" />

## 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.

<Note>
  Make sure to use Cello **Sandbox environment** when developing and testing
</Note>

## Optional: Connect the Cello MCP

The [Cello MCP server](/mcp/introduction) gives Claude direct access to Cello's documentation, integration health checks, and best-practice recommendations. Connecting it before you start means Claude 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.

This step is optional but recommended. The integration steps below work either way. See [Connect your client → Claude Code](/mcp/connect#claude-code) for the setup steps.

## Cello user referrals integration

<Note>
  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.
</Note>

<Steps>
  <Step title="Prep your project">
    * Signup and authentication flow is functional
    * Stripe subscription flow is functional
    * Cello API keys are handy
  </Step>

  <Step title="Add Cello Webhook Endpoint to Stripe">
    * Get your webhook URL from [Cello Portal](https://portal.cello.so/integrations/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.
  </Step>

  <Step title="Prompt Claude Code to add User Referrals to your app">
    Ask Claude Code to create a plan first - it stays in **plan mode** until you approve. Paste this prompt:

    <Tabs>
      <Tab title="With Cello MCP connected">
        ```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.
        ```

        Claude will pull the relevant guides, check what's already set up, and tailor the plan to your project.
      </Tab>

      <Tab title="Without MCP">
        ```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
        ```
      </Tab>
    </Tabs>

    Claude asks you guiding questions and creates an implementation plan based on your answers.
  </Step>

  <Step title="Confirm executing the plan">
    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 Claude to proceed and start implementing it.
  </Step>

  <Step title="Run & Test">
    Run your app and test the end-to-end flow. If everything was implemented correctly, you should see events coming in to [Cello Dashboard](https://portal.cello.so/dashboard/referrer).

    <Tip>
      If you have the Cello MCP connected, ask Claude to run a health check after deploying:

      *"Use Cello to check my integration status and confirm all four components are connected."*
    </Tip>
  </Step>
</Steps>

## 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 |
| *"How do I set up a custom referral launcher?"*  | Searches the docs for custom launcher implementation guides                              |