LostChurn Docs

Create, update, activate, and manage dunning campaigns programmatically via the LostChurn REST API.

The Campaigns API lets you manage dunning campaigns programmatically. You can list existing campaigns, create new ones, update configuration, and activate or pause campaigns.

Endpoints

Method	Path	Description
`GET`	`/v1/campaigns`	List campaigns
`GET`	`/v1/campaigns/:id`	Get a campaign
`POST`	`/v1/campaigns`	Create a campaign
`PUT`	`/v1/campaigns/:id`	Update a campaign
`POST`	`/v1/campaigns/:id/activate`	Activate a campaign
`POST`	`/v1/campaigns/:id/pause`	Pause a campaign
`POST`	`/v1/campaigns/:id/archive`	Archive a campaign

List Campaigns

Retrieve all campaigns in your workspace.

GET /v1/campaigns

Query Parameters

Parameter	Type	Default	Description
`status`	`string`	all	Filter: `active`, `paused`, `draft`, `archived`
`trigger`	`string`	--	Filter by trigger type (e.g., `payment_failed`, `card_expired`)
`sort`	`string`	`created_at`	Sort field: `created_at`, `name`, `status`
`order`	`string`	`desc`	Sort order
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`20`	Results per page (max: 100)

Example Request

curl "https://api.lostchurn.com/v1/campaigns?status=active" \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "cmp_abc123",
      "name": "Soft Decline Recovery",
      "status": "active",
      "trigger": "payment_failed",
      "channels": ["email", "sms"],
      "steps_count": 3,
      "enrolled_count": 142,
      "recovered_count": 89,
      "recovery_rate": 0.63,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-03-01T12:00:00Z"
    },
    {
      "id": "cmp_def456",
      "name": "Expired Card Outreach",
      "status": "active",
      "trigger": "card_expired",
      "channels": ["email"],
      "steps_count": 4,
      "enrolled_count": 56,
      "recovered_count": 23,
      "recovery_rate": 0.41,
      "created_at": "2025-02-05T14:00:00Z",
      "updated_at": "2025-03-07T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Get a Campaign

Retrieve full details for a campaign, including all steps and stop conditions.

GET /v1/campaigns/:id

Example Request

curl https://api.lostchurn.com/v1/campaigns/cmp_abc123 \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "id": "cmp_abc123",
    "name": "Soft Decline Recovery",
    "description": "Multi-step email and SMS campaign for soft decline failures.",
    "status": "active",
    "trigger": "payment_failed",
    "trigger_conditions": {
      "decline_categories": ["soft_retry"],
      "min_amount": null,
      "max_amount": null
    },
    "steps": [
      {
        "index": 0,
        "channel": "email",
        "template_id": "tpl_email_001",
        "subject": "Action needed: update your payment method",
        "delay_hours": 0,
        "delay_from": "enrollment"
      },
      {
        "index": 1,
        "channel": "email",
        "template_id": "tpl_email_002",
        "subject": "Your subscription is at risk",
        "delay_hours": 72,
        "delay_from": "previous_step"
      },
      {
        "index": 2,
        "channel": "sms",
        "template_id": "tpl_sms_001",
        "delay_hours": 48,
        "delay_from": "previous_step"
      }
    ],
    "stop_conditions": {
      "max_attempts": 3,
      "stop_on_recovery": true,
      "stop_on_terminal": true,
      "stop_on_card_update": true
    },
    "quiet_hours": {
      "enabled": true,
      "start_hour": 21,
      "end_hour": 8,
      "timezone": "America/New_York"
    },
    "stats": {
      "enrolled_count": 142,
      "recovered_count": 89,
      "terminal_count": 12,
      "active_count": 41,
      "recovery_rate": 0.63,
      "total_recovered_amount": 704242,
      "currency": "usd"
    },
    "created_at": "2025-01-10T09:00:00Z",
    "activated_at": "2025-01-10T09:30:00Z",
    "updated_at": "2025-03-01T12:00:00Z"
  }
}

Create a Campaign

Create a new campaign in draft status. You must activate it separately.

POST /v1/campaigns

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Campaign display name
`description`	`string`	No	Internal description
`trigger`	`string`	Yes	Trigger type (see table below)
`trigger_conditions`	`object`	No	Additional conditions for enrollment
`steps`	`array`	Yes	Ordered list of campaign steps
`stop_conditions`	`object`	No	When to end the campaign for a customer
`quiet_hours`	`object`	No	Time window to suppress messages

Trigger Types

Trigger	Description
`payment_failed`	Any failed payment
`card_expiring`	Card expiration approaching
`card_expired`	Card already expired
`soft_decline`	Soft decline after retries exhausted
`repeated_failure`	Multiple consecutive failures
`high_value_churn`	Failed payment above threshold
`pre_dunning`	Preventive outreach
`manual`	Manual enrollment only
`any_decline`	Any decline type

Example Request

curl -X POST https://api.lostchurn.com/v1/campaigns \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Expired Card Recovery",
    "trigger": "card_expired",
    "steps": [
      {
        "channel": "email",
        "template_id": "tpl_email_expired_01",
        "subject": "Your card on file has expired",
        "delay_hours": 0
      },
      {
        "channel": "email",
        "template_id": "tpl_email_expired_02",
        "subject": "Reminder: please update your payment method",
        "delay_hours": 72
      }
    ],
    "stop_conditions": {
      "max_attempts": 2,
      "stop_on_recovery": true,
      "stop_on_card_update": true
    }
  }'

Example Response

{
  "data": {
    "id": "cmp_new789",
    "name": "Expired Card Recovery",
    "status": "draft",
    "trigger": "card_expired",
    "steps_count": 2,
    "created_at": "2025-03-08T15:00:00Z"
  }
}

Update a campaign's configuration. Campaigns in active status can be updated, but changes only apply to newly enrolled customers. Customers already in the campaign continue with the original configuration.

PUT /v1/campaigns/:id

The request body accepts the same fields as campaign creation. Only include fields you want to change.

Example Request

curl -X PUT https://api.lostchurn.com/v1/campaigns/cmp_new789 \
  -H "Authorization: Bearer lc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Expired Card Recovery v2",
    "quiet_hours": {
      "enabled": true,
      "start_hour": 22,
      "end_hour": 7,
      "timezone": "America/Los_Angeles"
    }
  }'

Example Response

{
  "data": {
    "id": "cmp_new789",
    "name": "Expired Card Recovery v2",
    "status": "draft",
    "updated_at": "2025-03-08T15:30:00Z"
  }
}

Activate a Campaign

Move a campaign from draft or paused to active. Active campaigns begin enrolling customers that match the trigger conditions.

POST /v1/campaigns/:id/activate

Example Request

curl -X POST https://api.lostchurn.com/v1/campaigns/cmp_new789/activate \
  -H "Authorization: Bearer lc_live_your_api_key"

Example Response

{
  "data": {
    "id": "cmp_new789",
    "status": "active",
    "activated_at": "2025-03-08T16:00:00Z"
  }
}

Creating and activating campaigns counts toward your plan's campaign limit. Check Usage Limits for your current plan's allowance.

Pause a Campaign

Pause an active campaign. No new customers are enrolled and pending messages for currently enrolled customers are held until the campaign is reactivated.

POST /v1/campaigns/:id/pause

Archive a Campaign

Archive a campaign. Archived campaigns cannot be reactivated. All currently enrolled customers are removed from the campaign. Historical performance data is retained.

POST /v1/campaigns/:id/archive

Campaign Object

Field	Type	Description
`id`	`string`	Campaign ID
`name`	`string`	Display name
`description`	`string`	Internal description
`status`	`string`	`draft`, `active`, `paused`, `archived`
`trigger`	`string`	Trigger type
`trigger_conditions`	`object`	Additional enrollment conditions
`steps`	`array`	Campaign steps (on detail endpoint)
`stop_conditions`	`object`	Campaign stop rules
`quiet_hours`	`object`	Quiet hours configuration
`steps_count`	`integer`	Number of steps
`enrolled_count`	`integer`	Total customers enrolled
`recovered_count`	`integer`	Customers recovered
`recovery_rate`	`float`	Recovery rate (0.0 to 1.0)
`stats`	`object`	Detailed stats (on detail endpoint)
`created_at`	`string`	Creation timestamp
`activated_at`	`string \| null`	When the campaign was last activated
`updated_at`	`string`	Last update timestamp

Next Steps

Campaigns Overview -- campaign concepts and configuration in the dashboard
Payments API -- query and retry payments
Analytics API -- campaign performance metrics

Campaigns API

Endpoints

List Campaigns

Query Parameters

Example Request

Example Response

Get a Campaign

Example Request

Example Response

Create a Campaign

Request Body

Trigger Types

Example Request

Example Response

Update a Campaign

Example Request

Example Response

Activate a Campaign

Example Request

Example Response

Pause a Campaign

Archive a Campaign

Campaign Object

Next Steps

On this page