> ## 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.
# Integration status
> How the cello_get_integration_status tool checks your integration, what the health report contains, what each status and warning means, and how to set your signup and purchase sources
`cello_get_integration_status` checks whether all four required parts of a Cello referral program integration are working for your product, and returns a plain-language Integration Health Report. It is the fastest way to answer "is my integration working?" without leaving your editor.
You don't call it directly. Ask your coding tool in natural language and it picks the tool for you:
> *"Is my Cello integration working?"*
> *"I just finished the Cello integration. Verify that everything is set up correctly."*
> *"Why aren't my Cello referral rewards being triggered?"*
## What it checks
A complete Cello integration has four components. The tool reports on all four, every time.
| Component | What it does |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Referral component (widget)** | The in-app UI widget existing users interact with to share their referral link and track their rewards. See [Referral Component](/referral-component/introduction). |
| **Attribution library (`cello-attribution.js`)** | Captures the referral code (`ucc`) from incoming referred visitors on your signup and landing pages, and persists it across the signup flow. See [Web attribution setup](/attribution/for-web). |
| **Signup tracking** | When a referred user completes signup, your product reports that signup to Cello, through a Stripe or Chargebee webhook or a direct API call, so Cello can attribute it to the referrer. See [Track signups](/attribution/tracking-signups). |
| **Purchase tracking** | When a referred user makes a purchase, your product reports it to Cello so Cello can trigger reward payouts to the referrer. See [Track purchases](/attribution/tracking-purchase). |
For what each component's statuses mean and how to fix them, see the [Component reference](#component-reference) below.
## When to call it
* **While you're integrating**, to confirm the step you just finished actually worked before you move on to the next one.
* **After the integration is complete**, to verify all four components are set up and communicating correctly.
* **When rewards aren't triggering**, to find out which component is at fault.
* **As your coding tool's own check**, once it has finished writing the integration code.
## What the report contains
The tool returns one section per component. Each section includes these fields:
| Field | What it tells you |
| ----------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Conclusion** | A plain-language verdict, combining the alert with last-event timing where that matters. |
| **Status** | `Connected`, `Connected with warnings`, or `Not connected`. |
| **Configured source** | The signup or purchase source, on the components where a source applies. |
| **Auto-attribution for signup detection** | Read-only configuration context on Signup tracking, shown when it is present. |
| **Recent errors** | Widget errors with their type, path and timing, when there are any. |
| **Action** | The fix steps, with portal paths or docs links, when a fix is needed. |
## Status definitions
Every component reports one of three statuses, calculated against a **health window** of **1 hour** in production and **24 hours** in sandbox. If no successful events arrive within that window, the component is flagged as needing attention.
| Status | Meaning |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connected** | At least one successful event received within the health window. Even if some events had errors, a single success is enough to count as Connected. |
| **Connected with warnings** | The component **is** receiving events, but something needs attention. Either events arrived recently (within the last 30 days) but **none in the current health window**, or events arrived in the window but couldn't be attributed (no referral code) or failed validation. |
| **Not connected** | The component is **not** receiving events. This covers three distinct situations: (1) **no source is configured**, (2) a source is selected but its **credentials are missing** (Cello API key or webhook signing secret), or (3) the source and credentials are set up correctly but **no events have been received yet**. |
Statuses can move in any direction. A component can go from Connected to warnings if recent events have errors, or to Not connected if you change the source.
**Connected with warnings is not the same as Not connected.** Connected with warnings means events are arriving and the integration is fundamentally wired up. The fix is usually about the referral code (`ucc`) or field validation, **not** about setting up or changing a source. Always match troubleshooting to the source that is **already configured**.
## How to read the report
The tool instructs your assistant to follow four rules. Knowing them helps you sanity-check the answer you get back.
**All four components are always reported.** Every component keeps its own Conclusion and Status, and the last-event timing on a connected component is part of the verdict rather than noise. If your assistant summarises only the broken ones, ask it for the full report.
**Only the fixes on the Action line apply.** Each component's Action line is the remediation for that component. Fixes invented outside it, or borrowed from another component, tend to make things worse.
**Auto-attribution is context, not a lever.** The `Auto-attribution for signup detection` field is read-only configuration detail on Signup tracking. It is a separate mechanism from the Attribution library (`cello-attribution.js`), and toggling it never fixes an attribution problem or a webhook problem. See [Auto Attribution](/guides/attribution/auto-attribution) for what it actually does.
**Recency warnings can be normal.** If the report flags recency warnings only, or describes a quiet period, that is expected for a small or new program. It isn't evidence of a broken install or webhook unless you were expecting recent activity, or another component's Action line says otherwise.
## Component reference
What each component tracks, what its statuses mean, and what to do about them.
### Referral component
Tracks `booted` events from `cello.js`, the script that renders the referral component in your app.
| Status | What it means | What to check |
| ---------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Connected | The referral component booted successfully within the health window. | Nothing - everything is working as expected. |
| Connected with warnings | No successful boots in the health window, but no errors either. | Confirm the referral component is still being loaded for users. Check whether traffic to pages embedding it has dropped. |
| Connected with warnings (errors present) | Recent boots produced errors. The report lists them under **Recent errors**. | See [Widget errors](#widget-errors) below to interpret the message. |
| Not connected | No boots in 30 days. | Verify `cello.js` is loaded and `cello("boot", ...)` is called. See [Embed the Referral Component](/referral-component/introduction). |
#### Widget errors
Widget error messages are written to be human-readable, and they're worded differently from what you'll see in the browser **Console** or the **Network** tab. Use this table to map between them.
| Error type | Console (browser) | API (network tab) | Health report |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| **JWT token issue** | `401 (Unauthorized) [Cello]: User is not authorized to load the widget` | `Error 1100: Invalid JWT token` | **JWT token is missing, malformed, or expired** (code: `Invalid token payload`) |
| **Internal error** | `Internal server error` | `Internal server error` | **An internal error occurred - contact support** |
##### Token issue (`InvalidJwt`)
Several underlying token failures collapse into the single message **"JWT token is missing, malformed, or expired"**. The actual cause is one of:
* `token verification failed` - `decodeWidgetToken` could not verify the signature.
* `token schema not validated` - the token payload is invalid (e.g. wrong shape).
* `token missing iat field` - the token has no `iat` claim and `allowMissingTokenIat = false`.
* `token creation time in future` - the `iat` is in the future.
* `No referrer found for productUserId` - the token references a `productUserId` that doesn't exist.
* `No auth token found` - no token was sent with the boot request.
When you see this error, regenerate the widget token on your backend and confirm it's signed with the right secret, contains a valid `productUserId`, and has a current `iat` timestamp. See [User Authentication](/sdk/client-side/user-authentication) for details.
### Attribution library
Tracks referral link visits picked up by `cello-attribution.js`, the script you embed on your landing pages to capture referral codes.
| Status | What it means | What to check |
| ---------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connected | A referral link was visited within the health window. | Nothing - attribution is being captured. |
| Connected with warnings | No referral link visits in the last few hours. | Likely just low traffic. Check recent sharing activity. |
| Not connected (no signup URL) | No signup URL is set in your Cello configuration. | Set the signup URL in **User Experience → Settings**. |
| Not connected (URL set, no events) | The signup URL is configured but no visits have been recorded. | Confirm `cello-attribution.js` is embedded on the landing pages reachable from your referral links. See [Web attribution setup](/attribution/for-web). |
### Signup tracking
Tracks signup events from your configured source. The expected event type depends on the source:
| Source | Events tracked |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Cello API | `new-signup` |
| Stripe | `customer.created`, `customer.updated` |
| Chargebee | `Customer Created`, `Customer Changed` |
| Auto Attribution | Signup detected by [Auto Attribution](/guides/attribution/auto-attribution), used only if no other source is set |
Whatever the state, **troubleshoot the source that is already configured** rather than switching sources or setting up a webhook for a different one.
| Scenario | Status | What to do |
| ---------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No source configured | Not connected | Set your signup source. See [Changing the configured source](#changing-the-configured-source). |
| Source set, credentials missing | Not connected | Cello API: generate an API key under **Developers → Access keys**. Stripe or Chargebee: install the webhook and add its signing secret. |
| Source set, no signups received yet | Not connected | Confirm the configured source is actually sending. Cello API: your backend calls `POST /events` with `trigger: "new-signup"`, see [Track signups](/attribution/tracking-signups). Stripe: the [Stripe webhook](/integrations/webhooks/stripe-webhook) is installed and forwarding `customer.created` and `customer.updated`. Chargebee: the [Chargebee webhook](/integrations/webhooks/chargebee-webhook) is forwarding `Customer Created` and `Customer Changed`. Auto Attribution: it is enabled and a referred signup has actually happened. |
| Events arriving, none attributed | Connected with warnings | Events lack a referral code (`ucc`), so they can't be attributed. Open **Developers → Events** to see which `ucc` is missing or malformed. Applies to event-sending sources, not Auto Attribution. |
| Attributed events arriving, all fail validation | Connected with warnings | Open **Developers → Events** to see which required fields are failing for your source. |
| Auto Attribution: signups seen before, none in the health window | Connected with warnings | Usually low recent activity rather than a break. Confirm referred signups are still occurring. This recency warning applies to Auto Attribution only. |
| Everything healthy | Connected | Nothing - signups are being attributed. |
### Purchase tracking
Tracks purchase events from your configured source:
| Source | Events tracked |
| --------- | ------------------------------------------------------------------ |
| Cello API | `invoice-paid` |
| Stripe | Purchase events, for example `invoice.paid` and `charge.succeeded` |
| Chargebee | Purchase events |
Purchases have no Auto Attribution path and no recency warning. A configured purchase source that has never received events shows **Not connected** until the first event arrives.
| Scenario | Status | What to do |
| ----------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No source configured | Not connected | Set your purchase source. See [Changing the configured source](#changing-the-configured-source). |
| Source set, credentials missing | Not connected | Cello API: generate an API key under **Developers → Access keys**. Stripe or Chargebee: install the webhook and add its signing secret. |
| Source set, no purchases received yet | Not connected | Confirm the configured source is actually sending. Cello API: your backend sends `invoice-paid` via `POST /events`, see [Track purchases](/attribution/tracking-purchase). Stripe: the [Stripe webhook](/integrations/webhooks/stripe-webhook) is forwarding purchase events. Chargebee: the [Chargebee webhook](/integrations/webhooks/chargebee-webhook) is forwarding purchase events. |
| Events arriving, none attributed | Connected with warnings | Events lack a referral code (`ucc`). Open **Developers → Events** to see which `ucc` is missing or malformed. |
| Attributed events arriving, all fail validation | Connected with warnings | Open **Developers → Events** to see which required fields are failing for your source. |
| Everything healthy | Connected | Nothing - purchases are being attributed. |
## Changing the configured source
Your **signup source** and **purchase source** tell Cello where to expect your events. Cello can't recognise events until both are set.
You can set them yourself, and change them while you're still testing. The options are:
* **Signup source** - Cello API, Stripe, Chargebee, or [Auto Attribution](/guides/attribution/auto-attribution)
* **Purchase source** - Cello API, Stripe, or Chargebee
The key Stripe/Chargebee vs Cello API rule: Stripe or Chargebee can only be your signup source if your payment-provider customer is created **at signup**. If the customer is created **at first purchase**, use the Cello API to send `new-signup` at the real signup moment instead, or backfill with the [purchase-first, signup-later](/guides/support/faqs) pattern.
The right choice also depends on:
* **Payment provider.** Stripe and Chargebee can use webhooks. Other providers such as Paddle, Recurly and RevenueCat use the [Cello API](/api-reference/introduction).
* **Reward model.** Recurring vs one-time rewards, free-to-paid conversion, renewals, and refunds.
* **Motion.** Self-serve vs sales-led, for example [Salesforce](/integrations/salesforce-apex-triggers).
* **Auto Attribution.** Can be primary or fallback, and is enabled by Cello only.
A wrong source silently breaks attribution rather than failing loudly. If you're unsure which one fits your setup, confirm it with Cello before you build against it.
When you change a source, that component reverts to **Not connected** until events from the new source start arriving, usually within \~10 minutes.
### Auto Attribution
[Auto Attribution](/guides/attribution/auto-attribution) can only be enabled by Cello. Once it is enabled for your tenant, it becomes selectable as a signup source.
If Auto Attribution is on but a CRM source (Cello API, Stripe, or Chargebee) is your primary signup source, Auto Attribution runs in the background to catch any signups the primary source missed.
## When to use cello\_get\_events instead
`cello_get_integration_status` answers "is everything working?" at the component level. It does not validate individual webhook payloads.
When you need to know why one specific event failed, or which field in it was missing or malformed, use [`cello_get_events`](/mcp/tools#cello-get-events) instead. The usual sequence is to run the health check first, then drill into events for whichever component came back with warnings.
Per-event, per-field validation. Answers "why did this specific event fail?"
The manual, front-end checks no automated tool can see for you
## Troubleshooting
| Problem | Cause | Solution |
| -------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| A component shows Not connected even though events are flowing | Statuses can take up to 10 minutes to update | Re-run the health check in a few minutes. |
| A component shows Connected with warnings but you can't see why | The report doesn't include payload-level detail | Use [`cello_get_events`](/mcp/tools#cello-get-events), or open **Developers → Events**, to inspect the latest events for that source. |
| Signup or purchase tracking shows "source not set" | No source has been configured yet | Set it. See [Changing the configured source](#changing-the-configured-source). |
| A status flipped to Not connected after you updated your integration | The source changed and no new events have arrived yet | Trigger a test event from the new source. The status updates within \~10 minutes. |
| Auto Attribution isn't available as a signup source | It has not been enabled for your tenant | Contact Cello Support to enable it. |
## Programmatic use
Alongside the formatted report, the response includes `structuredContent` with the raw per-component status objects: `connectionStatus` (`connected`, `connectedWithWarnings`, or `notConnected`), an optional `warningType`, and a `lastEventReceived` timestamp, plus the configured signup and purchase sources and any widget errors. Use it when you want to gate a deployment or build your own check rather than read prose.
## Related
Every tool the Cello MCP server exposes
Example prompts for building and debugging your integration