To implement the Customers controller, you need to implement at least 2 API endpoints, we will use these endpoints to fetch customers from your system.
Prerequisites
SDK
If you are using the SDK, you can implement the Customers controller by following the code example below. You don't need to get into the details of the API endpoints, the SDK will take care of that for you.
import { Integrator } from '@churnkey/sdk'
import { Context } from '../Context'
import { Customer } from '../models/Customer'
export const Customers = Integrator.Customers.config({
ctx: Context,
async retrieve(ctx, options) {
const yourCustomer = await ctx.db.findCustomerById(options.id)
return new Customer(yourCustomer)
},
async list(ctx, options) {
const yourCustomers = await ctx.db.findCustomers({
limit: options.limit,
offset: options.cursor // the value you pass as `next` below
})
return {
data: yourCustomers.map(c => new Customer(c)),
// pass the next cursor if there are more items
next: yourCustomers.length === options.limit ? offset + limit : undefined
}
},
async findByEmail(ctx, email) { // optional
const yourCustomer = await ctx.db.findCustomerByEmail(email)
return new Customer(yourCustomer)
},
async findByPhone(ctx, phone) { // optional
const yourCustomer = await ctx.db.findCustomerByPhone(phone)
return new Customer(yourCustomer)
}
})
Endpoints
Retrieve Required
GET /churnkey/customers/:id
This endpoint fetches Customer by its id. Usually, implementation will include finding a customer in your database and mapping it to the Customer model.
Must return Customer model. See Customer model documentation.
See Error Responses.
import { Customer } from '../models/Customer'
app.get('/churnkey/customers/:id', async (req, res) => {
const customer = await db.findCustomerById(req.params.id)
if (!customer) {
return res.status(404).send({ code: 404, message: 'Customer not found' })
}
res.send(new Customer(customer))
})
List Optional
GET /churnkey/customers
This endpoint fetches a list of customers from your database. You should find customers in your database (with pagination), map them to the Customer model and return a paginated list.
Maximum number of items to return
Cursor for pagination. The actual value is whatever you decided to use as next in the response.
Array of items. The type of item is defined in the endpoint documentation, e.g. Customer for /customers endpoint
Either a next id or an offset for the next page. You decide what to use, we will send next value as a cursor query parameter back to you. If next is empty, there are no more pages
import { Customer } from '../models/Customer'
app.get('/churnkey/customers', async (req, res) => {
const limit = Number.parseInt(req.query.limit)
const offset = Number.parseInt(req.query.cursor)
const customers = await db.findCustomers({ limit, offset })
res.send({
data: customers.map(c => new Customer(c)),
next: customers.length === limit ? offset + limit : undefined
})
})
Find by Email Managed Flow
GET /churnkey/customers/email/:email
This endpoint fetches Customer by its email. Usually, implementation will include finding a customer in your database and mapping it to the Customer model.
Make sure that each customer has a unique email address if you are going to implement this endpoint.
Must return Customer model. See Customer model documentation.
See Error Responses.
import { Customer } from '../models/Customer'
app.get('/churnkey/customers/email/:email', async (req, res) => {
const customer = await db.findCustomerByEmail(req.params.email)
if (!customer) {
return res.status(404).send({ code: 404, message: 'Customer not found' })
}
res.send(new Customer(customer))
})
Find by Phone Managed Flow
GET /churnkey/customers/phone/:phone
This endpoint fetches Customer by its phone. Usually, implementation will include finding a customer in your database and mapping it to the Customer model.
Make sure that each customer has a unique phone number if you are going to implement this endpoint.
Must return Customer model. See Customer model documentation.
See Error Responses.
import { Customer } from '../models/Customer'
app.get('/churnkey/customers/email/:email', async (req, res) => {
const customer = await db.findCustomerByEmail(req.params.email)
if (!customer) {
return res.status(404).send({ code: 404, message: 'Customer not found' })
}
res.send(new Customer(customer))
})
Webhooks
Coming soon.