Help › For developers
For developers
Everything the dashboard does is also available via the API. The snippet uses the same endpoints. Base: https://churnreturn.com/api/v1, all responses are JSON.
Snippet interface in the browser
The script provides a global object:
| Call | Effect |
|---|---|
ChurnReturn.consent(true) | report consent; switches to the “after consent” mode |
ChurnReturn.trigger('name') | fire a custom trigger, for example from the cart event; the name must be set up in the configuration as a trigger of type custom |
ChurnReturn.dismiss() | close the overlay |
ChurnReturn.config() | read the loaded configuration |
ChurnReturn.pageview() | report a page change (single-page application without History API); the script detects changes via pushState, replaceState or the back button by itself |
With data-debug="1" on the script tag, the script writes what it does to the browser console. With ?cr_trigger=<type> in the page address, only that trigger is armed (for testing, see Triggers and rules).
Events
The script reports what it does as a CustomEvent on document; the data is in event.detail. This lets you include the overlay in your own analytics, for example in Tag Manager:
| Event | detail |
|---|---|
churnreturn:ready | triggers (armed triggers on this page), only (value of cr_trigger), mobile |
churnreturn:trigger | trigger: a trigger fired, recommendations are being loaded |
churnreturn:blocked | trigger, reason: already_shown, not_servable, dwell_rule or frequency |
churnreturn:impression | trigger, products: overlay shown |
churnreturn:empty | trigger: no recommendations for this page |
churnreturn:dismiss | trigger: overlay closed |
churnreturn:pageview | path: page change without reload detected, triggers restart |
document.addEventListener('churnreturn:impression', function (e) { dataLayer.push({ event: 'cr_overlay', trigger: e.detail.trigger }); });Public endpoints (no key, website recognized by origin)
| Endpoint | Purpose |
|---|---|
GET /config | Website configuration: status, triggers, rules, texts, CSS, JS |
POST /recommendations with {"url": "...", "text": "..."} | Recommendations for the page; the response contains products, rendered HTML and request_id |
POST /events with {"request_id", "type": "impression|click|dismiss", "product_id"} | Report an event |
GET /resolve?url=... | Check which product is recognized for an address (with secret key) |
Management API with secret key
Admins create a secret key per advertiser. It acts as owner of the advertiser and belongs only on your server, never in the browser. Header: Authorization: Bearer cr_sk_…
curl -H "Authorization: Bearer cr_sk_…" https://churnreturn.com/api/v1/advertisers/12/feeds
curl -X POST -H "Authorization: Bearer cr_sk_…" -H "Content-Type: application/json" \
-d '{"embed": true}' https://churnreturn.com/api/v1/feeds/23/import
| Area | Endpoints |
|---|---|
| Advertisers | GET /advertisers, GET|PUT /advertisers/{id}, GET|PUT|DELETE /advertisers/{id}/members |
| Websites | GET|POST /advertisers/{id}/sites, GET|PUT|DELETE /sites/{id}, PUT /sites/{id}/status|template|css|js, GET /sites/{id}/history, POST /sites/{id}/preview |
| Feeds | GET|POST /advertisers/{id}/feeds, GET|PUT|DELETE /feeds/{id}, POST /feeds/{id}/import, POST /feeds/{id}/embed, GET /feeds/{id}/products|runs|fields|sample|preview |
| Keys | GET|POST /advertisers/{id}/keys, DELETE /keys/{id} |
Errors are returned as {"error": {"code": "...", "message": "..."}} with the appropriate HTTP status. The site configuration is validated on save, and every change creates a version.
Custom triggers
Set up a trigger of type custom with a name in the configuration, and ChurnReturn.trigger('name') will fire the overlay, for example when “Continue shopping” is clicked or a cart item is removed. Enter the names in the dashboard under Triggers & rules, in “Custom triggers”.