Connect attribution
This guide walks you through the steps required to attribute referrals and includes:
If your payment gateway is Stripe or Chargebee, use the following guides with Webhook integration
1. Track conversions on your landing page
Add Attribution library to your Home page by including the following script in the <head> tag to track attributions and show New user banner.
<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>2. Track signups
When a signup finally happens, you need to make sure that a ucc code, identifying the referrer, is saved to the new user record and passed to Stripe upon customer creation.
Access Ucc code during signup
Ucc is present in the URL of your Home page when a new user is redirected to it from the invite link and in the cookies, added by the Attribution library.
To access the ucc during signup, you can use the Attribution library JS method getUcc().
Here is how to do it:
- Add the following javascript code before any of the calls to the library to avoid race conditions.
window.CelloAttribution=window.CelloAttribution||async function(t,o){if("getReferral"===t)throw new Error("getReferral is not supported in this context. Use getUcc instead.");let e,n;const i=new Promise((t,o)=>(e=t,n=o));return(window.CelloAttributionCmd=window.CelloAttributionCmd||[]).push({command:t,args:o,resolve:e,reject:n}),i};// if in async functionconst ucc = await window.CelloAttribution('getUcc');// otherwisewindow.CelloAttribution('getUcc').then((result) => { const ucc = result;})Next save the ucc to your user record. You will need it in next step when you send Cello referral update events.
To make sure your referrers get rewarded when a new user signs up in the mobile app, follow this guide on Mobile attribution to track mobile app signups.
3. Connect Cello API
You can interact with the Cello API through HTTP requests from any language. Cello API provides 3 endpoints: Events to report and push (generic) events directly to Cello, Referral Codes to validate referral code (UCC) and Active link to retrieve an active referral code (UCC) and invite link for your user.
Domain base URL's
Use the Domain base URL that corresponds with the environment.
| Endpoint URL | Environment |
|---|---|
https://api.sandbox.cello.so/ | Sandbox |
https://api.cello.so/ | Prod |
💡 Switch environments in the Portal using a switch to get the credentials
Authentication
To use the Cello API, you need to authenticate the request using an accessToken which is passed in the Authorization request header.
To obtain them you will need accessKeyId & secretAccessKey which you can get from your product dashboard on Access Keys page.
The value of expiresIn specifies after how many seconds the token expires.
Obtain accessToken & refreshToken
curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "accessKeyId": "<accessKeyId>", "secretAccessKey": "<secretAccessKey>" }'{ "accessToken": "<accessToken>", "expiresIn": 18000, // specifies after how many seconds the token expires "refreshToken": "<refreshToken>"}Status Code 201Refresh accessToken
curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "<refreshToken>" }'{ "accessToken": "<accessToken>", "expiresIn": 18000 // specifies after how many seconds the token expires}Status Code 201Make sure that all requests contain Authorization: Bearer <accessToken> header and Content-Type: application/json
4. Send referral update events
This Cello API provides a way to report and push (generic) events directly to Cello. Currently Cello supports manual reporting via exports and direct integration to Stripe via a an webhook endpoint. For all other use cases you can use our Events endpoint.
Use cases:
- New user signs up for your product based on a referral link.
- New user schedules a demo call based on a referral link.
- New user buys a subscription directly after the signup or after he or she tested the product.
- New user cancels his or her subscription.
- New user adds new seats to his or her active plan.
Example Requests and Flows
Based on your business model and signup flow, you need to provide Cello with certain events. You will find a couple of common use cases in the tab menu underneath. If they don't fit your needs, feel free to reach out to our support and discuss a custom flow.
If the buying persona is the organization and you want to attribute purchases on the organization level always provide the ID of the organization in the parameter payload.newUserId.