Required for Pause Offer to work.
To implement the Pause action, you need to implement an endpoint and define features
Prerequisites
SDK
If you are using the SDK, you can implement the Pause action 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 { Subscriptions } from '../controllers/Subscriptions'
export const Pause = Integrator.Pause.config({
Subscriptions: Subscriptions,
features: {
// define which start dates are supported, at least one is required
startDates: {
[Integrator.Pause.StartDate.Immediate]: true,
[Integrator.Pause.StartDate.EndOfPeriod]: true
},
// define which durations are supported, at least one is required
durations: {
[Integrator.Pause.Duration.Period]: true,
[Integrator.Pause.Duration.Date]: true
},
allowAnnual: true
},
async handle(ctx, options) {
const subscription = await this.subscriptions.retrieve({
customerId: options.customerId,
id: options.subscriptionId
})
if (!options.allowAnnual) {
if (subscription.duration.unit === 'year') {
throw new Integrator.Error(400, 'Annual subscriptions are not allowed to be paused')
}
}
switch (options.startAt) {
case Integrator.Pause.StartDate.Immediate:
await ctx.db.pauseSubscription(subscription, {
duration: options.duration
})
break
case Integrator.Pause.StartDate.EndOfPeriod:
await ctx.db.pauseSubscriptionAtThePeriodEnd(subscription, {
duration: options.duration
})
break
}
}
})
Endpoints
Handle Required
POST /churnkey/actions/subscription/pause
This endpoints handles the single subscription pause. You should find the subscription by customerId and subscriptionId and pause it.
Options for pause, provided in the request body.
Unique identifier of the customer.
Unique identifier of the subscription.
Duration of the pause
'immediate' 'end-of-period'
Defines when the pause should start, duration should be relative to this date.
Indicates if the pause can be applied to annual subscriptions. Comes from your Churnkey Dashboard settings.
Must return empty response.
See Error Responses.
app.post('/churnkey/actions/subscription/pause', async (req, res) => {
const subscription = await db.findSubscription(req.body.customerId, req.body.subscriptionId)
if (!req.body.allowAnnual) {
if (subscription.duration.unit === 'year') {
return res.status(400).send({
code: 400,
message: 'Annual subscriptions are not allowed to be paused'
})
}
}
switch (req.body.startAt) {
case 'immediate':
await db.pauseSubscription(subscription, {
duration: req.body.duration
})
break
case 'end_of_period':
await db.pauseSubscriptionAtThePeriodEnd(subscription, {
duration: req.body.duration
})
break
}
res.send()
})
Handle All optional
POST /churnkey/actions/customer/pause
This endpoint handles pause of all customer's subscriptions. You should find all subscriptions by customerId and pause them.
This endpoint is optional. By default, when we need to pause all subscriptions, we will call the Handle endpoint for each subscription. You can implement this endpoint to reduce the number of API calls and improve performance/end-user UX.
Options for pause, provided in the request body.
Unique identifier of the customer.
Duration of the pause
'immediate' 'end-of-period'
Defines when the pause should start, duration should be relative to this date.
Indicates if the pause can be applied to annual subscriptions. Comes from your Churnkey Dashboard settings.
Must return empty response.
See Error Responses.
app.post('/churnkey/actions/customer/cancel', async (req, res) => {
const subscriptions = await db.findSubscriptionsByCustomerId(req.body.customerId)
if (!req.body.allowAnnual) {
if (subscriptions.some(sub => sub.duration.unit === 'year')) {
return res.status(400).send({
code: 400,
message: 'Annual subscriptions are not allowed to be paused'
})
}
}
switch (req.body.startAt) {
case 'immediate':
await db.pauseSubscriptions(subscriptions, {
duration: req.body.duration
})
break
case 'end_of_period':
await db.pauseSubscriptionsAtThePeriodEnd(subscriptions, {
duration: req.body.duration
})
break
}
res.send()
})
Features required
Features define which behavior is supported for the Pause action. Depending on the features you enabled, requests body will have different options.
For example, if you enable only end-of-period start date, the request.body.startAt will be always end-of-period. If you enable both start dates, request.body.startAt can be either immediate or end-of-period.
If true, the action is enabled and can be used by Churnkey, otherwise it is disabled.
Defines supported duration types for pause. At least one duration type should be enabled.
Defines supported start date types for pause. At least one start date type should be enabled.
If your system supports pausing annual subscriptions, set this to true
export interface Features {
enabled: boolean
startDates: {
immediate: boolean
end_of_period: boolean
},
durations: {
period: boolean
date: boolean
},
allowAnnual: boolean
}
export const features: Features = {
enabled: true,
startDates: {
immediate: true,
end_of_period: false // this start date will be disabled
},
durations: {
period: true,
date: false // this duration type will be disabled
},
allowAnnual: true
}