Skip to main content

ChurnKey

ChurnKey is a subscription-retention platform that helps SaaS businesses reduce churn through customizable cancel flows, failed-payment recovery, and predictive customer-health models. This connector uses the ChurnKey Data API and Event Tracking API to read cancel session records and aggregated churn metrics into Nexla, and to push behavioral events, customer attribute updates, and billing-contact configurations back to ChurnKey.

ChurnKey icon

Power end-to-end data operations for your ChurnKey API with Nexla. Our bi-directional ChurnKey connector is purpose-built for ChurnKey, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to ChurnKey or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your ChurnKey workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

To connect Nexla to ChurnKey, you will need an active ChurnKey account along with a Data API key and your App ID. ChurnKey authenticates all Data API and Event Tracking API requests using two values passed as request headers: the API key in the x-ck-api-key header and the App ID in the x-ck-app header.

Locate Your App ID​

Your App ID is a unique identifier for your ChurnKey application and is required on every API request.

  1. Sign in to the ChurnKey dashboard at app.churnkey.co.

  2. Navigate to Settings > Account.

  3. Locate your App ID in the account details. This value is sent in the x-ck-app header on every request.

Generate a Data API Key​

ChurnKey uses a dedicated Data API key for server-to-server integrations. This key is distinct from the Cancel Flow (client-side) API key — using the Cancel Flow key for Data API requests will result in 401 or 403 authorization errors.

  1. In the ChurnKey dashboard, navigate to Settings > Account.

  2. Locate the Data API section, and copy or generate your Data API key. Data API keys are typically prefixed with data_.

  3. Store this key securely. It grants programmatic access to your cancel session data, customer events, and GDPR (Data Subject Request) operations.

    Keep your Data API key secure

    The Data API key provides full access to read session data and to create, update, and delete customer records and events. Treat it like a password, and never expose it in client-side code or public repositories.

For complete details about the ChurnKey Data API and authentication, refer to the ChurnKey Data API documentation.

Authenticate​

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Enter your ChurnKey Data API key in the API Key field. Nexla sends this value in the x-ck-api-key request header to authenticate each API call. This field is required and is stored securely.

  4. Enter your ChurnKey App ID in the App ID field. Nexla sends this value in the x-ck-app request header on every request. This field is required and identifies your ChurnKey application. Your App ID is found under Settings > Account in the ChurnKey dashboard.

    Nexla validates the credential by issuing a test request to the ChurnKey sessions endpoint. If validation fails, confirm that the API key is a Data API key (not a Cancel Flow key) and that the App ID matches the one shown in your ChurnKey account.

  5. Click the Save button at the bottom of the overlay to save the configured credential. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the ChurnKey connector tile, then select the credential that will be used to connect to the ChurnKey instance, and click Next; or, create a new ChurnKey credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common ChurnKey endpoints. Each template is designed specifically for the corresponding ChurnKey endpoint, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Sessions

This endpoint returns a list of all cancel-flow sessions recorded in your ChurnKey account. Use it to ingest session-level retention data — such as save attempts, accepted offers, and cancellation outcomes — for analysis, reporting, or warehousing.

  • This endpoint retrieves session records from https://api.churnkey.co/v1/data/sessions using a GET request. No additional configuration is required beyond selecting this endpoint template.
  • Each element in the returned array is treated as an individual record, so the data is automatically organized into one record per session.

The ChurnKey sessions endpoint returns up to 10,000 sessions per request. For accounts with high session volumes, consider scheduling regular ingestion runs to capture new sessions incrementally.

Get Session Aggregation

This endpoint returns aggregated session data and summary statistics for your ChurnKey account. Use it when you need rolled-up churn metrics rather than individual session records — for example, to populate executive dashboards or track retention trends over time.

  • This endpoint retrieves aggregated statistics from https://api.churnkey.co/v1/data/session-aggregation using a GET request. No additional configuration is required beyond selecting this endpoint template.
  • The endpoint returns a single aggregated object, so this source produces a single record representing the current account-level summary.

Because this endpoint returns a point-in-time snapshot of aggregated metrics, schedule recurring ingestion runs if you want to track how these statistics change over time.

Get DSR Data Access

This endpoint fulfills a GDPR Data Subject Request (DSR) by returning all stored ChurnKey data for a single customer, identified by email address. The response includes the customer's events, sessions, campaigns, invoices, failed payments, subscriptions, charges, and emails. Use this endpoint to satisfy data subject access requests or to export a complete profile for a specific customer.

  • This endpoint issues a POST request to https://api.churnkey.co/v1/data/dsr/access. To configure it, provide the following parameter:

    • Customer Email — Enter the email address of the customer whose data subject access request data should be returned. This value is required and is sent in the request body to identify the customer.
  • The endpoint returns a single consolidated object containing all stored records for the specified customer.

This endpoint is intended for fulfilling individual data subject access requests under GDPR. For additional details on ChurnKey's data subject request handling, refer to the ChurnKey Data API documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

ChurnKey data sources can also be manually configured to ingest data from any valid ChurnKey API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers. ChurnKey Data API endpoints are based at https://api.churnkey.co/v1/data/.

You do not need to include the ChurnKey x-ck-api-key and x-ck-app authentication headers in Request Headers — Nexla adds them automatically based on your credential configuration. For endpoints like the sessions endpoint that return a top-level array, set Path to Data in Response to $[*] so that each array element becomes a record.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new ChurnKey data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the ChurnKey destination, and select the Send to Destination option from the menu. Select the ChurnKey connector from the list of available destination connectors, then select the credential that will be used to connect to the ChurnKey account, and click Next; or, create a new ChurnKey credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common ChurnKey endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Create Event

This endpoint tracks a single customer behavioral event, feeding ChurnKey's predictive customer-health models. Use it to stream product-usage signals — such as logins or feature usage — that help ChurnKey forecast churn risk.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/api/events/new. Each Nexset record is sent as the JSON request body.

  • Map your Nexset so each record matches the expected event shape. The body supports the following fields:

    • event — The name of the behavioral event being tracked (for example, a login or a feature use).
    • customerId — The customer's identifier from your billing provider (for example, the Stripe customer ID).
    • uid — An optional alternative customer identifier.
    • eventDate — An optional timestamp for when the event occurred.
    • eventData, user, and customerData — Optional objects carrying additional event, user, and customer attributes.

To pre-train ChurnKey's health models, ChurnKey recommends submitting three to six months of historical event data. For details on supported event fields, refer to the ChurnKey Event Tracking documentation.

Bulk Create Events

This endpoint tracks up to 100 customer events in a single request. Use it to backfill historical behavioral data efficiently when pre-training ChurnKey's customer-health models.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/api/events/bulk. The request body is an array of event objects.
  • Use Record Batching to group multiple Nexset records into a single array per request. Set the batch size to no more than 100, since the endpoint accepts a maximum of 100 events per call.

Unlike the single Create Event endpoint, the bulk endpoint does not accept customerData updates. To update customer attributes, use the Update Customer endpoint instead.

Update Customer

This endpoint updates the customer attributes that ChurnKey stores — such as plan tier or seat count — so that health-model features stay current with your CRM or billing system. Use it to keep ChurnKey's view of each customer in sync with your source of truth.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/api/events/customer-update. Each Nexset record is sent as the JSON request body.

  • Map your Nexset so each record includes at least one customer identifier. The body supports the following fields:

    • customerId or uid — At least one of these is required to identify the customer to update.
    • customerData — An optional object carrying updated customer attributes, such as the number of seats or plan name.
    • user — An optional object carrying user-level attributes, useful for B2B products that track individual users.

Keeping customer attributes current improves the accuracy of ChurnKey's churn predictions. For the full customer model, refer to the ChurnKey customer model documentation.

Set Billing Contacts

This endpoint configures the billing contacts for a single customer so they receive Failed Payment Recovery communications. Use it to control which users are opted into recovery emails for a given customer.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/api/events/customer-update/set-users. Each Nexset record is sent as the JSON request body.
  • Set billingAdmin to true for any user who should be opted into Failed Payment Recovery emails for the customer.

For complete details on configuring billing contacts, refer to the ChurnKey Billing Contact API documentation.

Bulk Set Billing Contacts

This endpoint updates billing contacts across many customers in a single request. Use it to apply Failed Payment Recovery contact settings in bulk rather than one customer at a time.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/api/events/customer-update/set-users/bulk. The request body is an array of objects, each containing a customerId and a users array.
  • Use Record Batching to group multiple Nexset records into a single array per request, with each element specifying the customer and its billing-contact users.

This endpoint is best suited for syncing billing-contact settings for large customer bases. For details on the request shape, refer to the ChurnKey Billing Contact API documentation.

Delete DSR Data

This endpoint fulfills a GDPR data deletion request by erasing all stored ChurnKey data for a customer identified by email address. Use it to satisfy data subject deletion requests.

  • This endpoint sends a POST request to https://api.churnkey.co/v1/data/dsr/delete. Each Nexset record is sent as the JSON request body and must include the customer's email.
  • The endpoint responds for each request indicating whether the deletion succeeded.

Use this endpoint with care, as deletions are permanent. A deletion can be rejected (returning deleted: false with a reason) if the profile exceeds the API deletion limit. For details, refer to the ChurnKey Data API documentation.

Manual configuration​

ChurnKey destinations can also be manually configured to send data to any valid ChurnKey API endpoint, and can automatically send the response received from the ChurnKey API after each call to a new Nexla webhook data source. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks. ChurnKey write endpoints use the POST method with JSON-formatted request bodies. ChurnKey Event Tracking endpoints are based at https://api.churnkey.co/v1/api/, and the GDPR deletion endpoint is https://api.churnkey.co/v1/data/dsr/delete.

You do not need to include the ChurnKey x-ck-api-key and x-ck-app authentication headers in Request Headers — Nexla adds them automatically based on your credential configuration. When batching records for the Bulk Create Events endpoint, set the batch size to no more than 100, since the endpoint accepts a maximum of 100 events per call.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to ChurnKey, open the destination resource menu, and select Activate.

The Nexset data will not be sent to ChurnKey until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.