---
title: Custom Provider Integration
description: Build a custom integration to connect your billing system with Churnkey's retention tools.
---

## Overview

Churnkey helps reduce churn by offering targeted retention experiences when customers try to cancel. This guide walks you through building a custom integration that connects your billing system to Churnkey, enabling features like pause offers, targeted discounts, and plan changes during cancellation flows.

## Core Models

Models map your billing system's data to Churnkey's format. Each model represents a key billing concept that Churnkey needs to understand your customers and their subscriptions.

::grid{cols="4"}
  ::card-baseline{title="Customer" to="/integrations/models/customer"}
    A user who owns subscriptions.
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Price" to="/integrations/models/price"}
    Billing cycle and price of a subscription (a.k.a. Plan)
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Subscription" to="/integrations/models/subscription"}
    Subscription to a product or service.
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Coupon" to="/integrations/models/coupon"}
    A discount code for a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Coupon Offer"}
    ::
  ::
  ::card-baseline{title="Product" to="/integrations/models/product"}
    A product or service.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Better UX"}
    ::
  ::
  ::card-baseline{title="Family" to="/integrations/models/family"}
    A group of products or services.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Better UX"}
    ::
  ::
  ::card-baseline{title="Invoice"}
    An invoice for a subscription.
    ::flex{class="mt-4"}
      :badge{label="Coming soon"}
    ::
  ::
::

## Data Access Controllers

Controllers provide secure, standardized access to your billing data. Each controller exposes two essential methods:

- `retrieve()`: Fetch a single record by ID
- `list()`: Fetch multiple records with pagination support

::grid{cols="4"}
  ::card-baseline{title="Customers" to="/integrations/controllers/customers"}
    List, retrieve and find `Customer` models.
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Prices" to="/integrations/controllers/prices"}
    List and retrieve `Price` models.
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Subscriptions" to="/integrations/controllers/subscriptions"}
    List and retrieve `Subscription` models.
    ::flex{class="mt-4"}
      :badge{label="Required" color="green"}
    ::
  ::
  ::card-baseline{title="Coupons" to="/integrations/controllers/coupons"}
    List and retrieve `Coupon` models.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Coupon Offer"}
    ::
  ::
  ::card-baseline{title="Products" to="/integrations/controllers/products"}
    List and retrieve `Product` models.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Better UX"}
    ::
  ::
  ::card-baseline{title="Families" to="/integrations/controllers/families"}
    List and retrieve `Family` models.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Better UX"}
    ::
  ::
  ::card-baseline{title="Invoices"}
    List and retrieve `Invoice` models for advanced analytics.
    ::flex{class="mt-4"}
      :badge{label="Coming soon"}
    ::
  ::
::

## Subscription Actions

Actions enable Churnkey to modify subscriptions based on customer choices during the cancellation flow. Each action handles a specific type of subscription change, like applying a discount or pausing service.

::grid{cols="4"}
  ::card-baseline{title="Cancel" to="/integrations/actions/cancel"}
    Cancels a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Cancel Flow - Required" color="green"}
    ::
  ::
  ::card-baseline{title="Pause" to="/integrations/actions/pause"}
    Pauses a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Pause Offer"}  
    ::
  ::
  ::card-baseline{title="Extend Trial" to="/integrations/actions/extend-trial"}
    Extends a trial period for a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Trial Offer"}
    ::
  ::
  ::card-baseline{title="Apply Coupon" to="/integrations/actions/apply-coupon"}
    Applies a coupon to a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Discount Offer"}
    ::
  ::
  ::card-baseline{title="Change Price" to="/integrations/actions/change-price"}
    Changes the price and/or product of a subscription.
    ::flex{class="mt-4"}
      :badge{label="Optional"}
      :badge{label="Price Offer"}
    ::
  ::
::

## Deploy Your Integration

Finally, you need to make sure that all your `Controllers` and `Actions` are accessible from an Internet, have proper authentication and provide `Features` manifest.

Follow the [publishing guide](/integrations/publish) for detailed deployment instructions and troubleshooting tips.