---
title: Pause - Action
description: Pauses a subscription at specific date for a specific period.
---

Required for :badge{label="Pause Offer"} to work.

To implement the `Pause` action, you need to implement an endpoint and define `features`

## Prerequisites
::grid{cols="2"}
    ::card-baseline{title="Subscriptions - Controller" to="/integrations/controllers/subscriptions"}
      You must implement a `Subscriptions` controller first.
      ::flex{class="mt-4"}
        :badge{label="Required" color="green"}
      ::
    ::
    ::card-baseline{title="Cancel - Action" to="/integrations/actions/cancel"}
      Pause is a part of the Cancel Flow. You must implement the `Cancel` action first.
      ::flex{class="mt-4"}
        :badge{label="Required" color="green"}
      ::
    ::
::

## 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.

::code-group
```typescript [Typescript]
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 :badge{label="Required" color="green"}

`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.

::collapsible{name="request body"}
  :field-schema{schema="/types/actions/pause/request.type.json"}
::

::collapsible{name="response"}
    ::tabs
        ::div{label="200"}
        Must return empty response.
        ::
        ::div{label="Error"}
        See [Error Responses](/integrations/general#error-responses).
        ::
    ::
::

::collapsible{name="code example"}
  ::code-group
  ```typescript [Typescript Express]
    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 :badge{label="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.

::collapsible{name="request body"}
  :field-schema{schema="/types/actions/pause/request-all.type.json"}
::

::collapsible{name="response"}
    ::tabs
        ::div{label="200"}
        Must return empty response.
        ::
        ::div{label="Error"}
        See [Error Responses](/integrations/general#error-responses).
        ::
    ::
::

::collapsible{name="code example"}
  ::code-group
  ```typescript [Typescript Express]
    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 :badge{label="required" color="green"}

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`.

::collapsible{name="schema"}
  :field-schema{schema="/types/actions/pause/features.type.json"}
::
::collapsible{name="code example"}
  ::code-group
  ```typescript [Typescript]
  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
  }
  ```
::