Publish your Integration

Before following this guide, make sure that you have implemented all the required controllers and actions.

Get Integration Token

To obtain your Integration Token, go to the Churnkey dashboard -> Settings -> Billing Providers:

Choose Custom Provider and copy the Integration Token:

Never store your Integration Token in your codebase. Use environment variables or a secure vault to store it.

Make integration publicly available

import { Integrator } from '@churnkey/sdk'
import { Context } from './Context'
import { Customers } from './controllers/Customers'
import { Prices } from './controllers/Prices'
import { Subscriptions } from './controllers/Subscriptions'
import { Coupons } from './controllers/Coupons' // optional
import { Cancel } from './actions/Cancel' // optional
import { ApplyCoupon } from './actions/ApplyCoupon' // optional
import { ExtendTrial } from './actions/ExtendTrial' // optional
import { ChangePrice } from './actions/ChangePrice' // optional
import { Pause } from './actions/Pause' // optional

export const Integration = new Integrator.Integration({
    ctx: Context,
    name: 'YourCompanyName',
    modules: {
        controllers: {
            Customers,
            Prices,
            Subscriptions,
            Coupons // optional
        },
        actions: {
            Cancel, // optional
            ApplyCoupon, // optional
            ExtendTrial, // optional
            ChangePrice, // optional
            Pause // optional
        }
    }
})

import express from 'express'
import { Integration } from './churnkey/Integration'
import { Context } from './churnkey/Context'

const app = express()
Integration.expose({
    app: app, // express app instance
    token: process.env.CK_INTEGRATION_TOKEN, // your integration token
    ctx(req, req) {
        return new Context(
            // initialize your context here
            // parameters can vary depending on your implementation
        )
    } 
})

Verify your Integration

Go to the Churnkey dashboard -> Settings -> Billing Providers. You should see that your Custom Provider is pending verification:

Add your API URL to the Custom Provider. This is your API root URL, we will append the endpoint with /churnkey prefix to it automatically:

Click on the Verify button to verify your integration:

You should see results and list of supported features soon:

Troubleshooting

If you see any errors during the verification process, the most common issues are:

• Incorrect Integration Token
• Incorrect data format (e.g. wrong Model implementation)
• Incorrect endpoint implementation (e.g. wrong url or wrong response)
• Features endpoint is not implemented

Generally, you should be able to fix most of the issues by following the error message you see. If you are still stuck, feel free to reach out to our support team, we are happy to help you.

Keep in mind that we're following modular architecture, so if one of the optional modules doesn't work, other modules should work fine.

Updating integration

Over time you may want to add new features or fix bugs in your integration.

We cache the Feature Manifest, so if your update includes changes to the Feature Manifest, you should re-verify your integration. If you only update the implementation, you don't need to re-verify it.

Manual verification

You can go to the Churnkey dashboard -> Settings -> Billing Providers and click on the Verify button to re-verify your integration.

Automatic verification

You can call the verify endpoint programmatically from your CI/CD or during the server start. This way, you can ensure that your integration is always up-to-date and verified.