Integration status

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. For what each component’s statuses mean and how to fix them, see the 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:

​

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

​

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

​

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.

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

​

Signup tracking

Tracks signup events from your configured source. The expected event type depends on the source: Whatever the state, troubleshoot the source that is already configured rather than switching sources or setting up a webhook for a different one.

​

Purchase tracking

Tracks purchase events from your configured source: 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.

​

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
• 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 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.
• Reward model. Recurring vs one-time rewards, free-to-paid conversion, renewals, and refunds.
• Motion. Self-serve vs sales-led, for example Salesforce.
• Auto Attribution. Can be primary or fallback, and is enabled by Cello only.

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 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 instead. The usual sequence is to run the health check first, then drill into events for whichever component came back with warnings.

​

Troubleshooting

​

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