Accept a retention offer

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offerType": "PAUSE",
  "cancellationFeedback": "UNUSED",
  "pauseMonths": 3
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/"

payload = {
    "offerType": "PAUSE",
    "cancellationFeedback": "UNUSED",
    "pauseMonths": 3
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({offerType: 'PAUSE', cancellationFeedback: 'UNUSED', pauseMonths: 3})
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offerType' => 'PAUSE',
    'cancellationFeedback' => 'UNUSED',
    'pauseMonths' => 3
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/"

	payload := strings.NewReader("{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Discount applied successfully",
  "subscriptionId": "78058918-9746-4280-9b9b-1bd5115eec6e",
  "offerType": "DISCOUNT",
  "cancellationFeedback": "TOO_EXPENSIVE",
  "percentageOff": 20,
  "billingCycles": 3,
  "appliesUntil": "2027-01-01T00:00:00Z",
  "originalAmount": "50.00",
  "discountedAmount": "40.00"
}

Subscriptions

Accept a retention offer

Applies the retention offer a customer accepted instead of cancelling.

Pass the cancellation reason the customer picked and the offer it maps to. offerType has to be the offer configured for that reason in the dashboard retention settings; any other pairing is rejected with 400. Eligibility is checked again at this point, so an offer that was eligible when you fetched it can still be refused if, for example, the subscription was paused or scheduled to cancel in between.

What happens depends on the offer:

DISCOUNT creates a single-use coupon for the configured percentage and billing cycles and attaches it to the subscription. The response includes the discounted amount and when the discount ends.
PAUSE pauses the subscription for pauseMonths, which must be one of the durations returned by Get retention offers. Billing and access resume on the returned date, exactly as a merchant-initiated pause would.
SUPPORT records that the customer took the support offer and returns the configured support URL to send them to. Nothing changes on the subscription.

Every acceptance is recorded against the subscription and counted by the organization’s offer repeat policy, so a customer cannot stack discounts or pause indefinitely by reopening the cancellation flow.

POST

subscriptions

{subscriptionId}

retention

Accept a retention offer

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offerType": "PAUSE",
  "cancellationFeedback": "UNUSED",
  "pauseMonths": 3
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/"

payload = {
    "offerType": "PAUSE",
    "cancellationFeedback": "UNUSED",
    "pauseMonths": 3
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({offerType: 'PAUSE', cancellationFeedback: 'UNUSED', pauseMonths: 3})
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'offerType' => 'PAUSE',
    'cancellationFeedback' => 'UNUSED',
    'pauseMonths' => 3
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/"

	payload := strings.NewReader("{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/retention/accept/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"offerType\": \"PAUSE\",\n  \"cancellationFeedback\": \"UNUSED\",\n  \"pauseMonths\": 3\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Discount applied successfully",
  "subscriptionId": "78058918-9746-4280-9b9b-1bd5115eec6e",
  "offerType": "DISCOUNT",
  "cancellationFeedback": "TOO_EXPENSIVE",
  "percentageOff": 20,
  "billingCycles": 3,
  "appliesUntil": "2027-01-01T00:00:00Z",
  "originalAmount": "50.00",
  "discountedAmount": "40.00"
}

Click the base URL in the API playground and select the Sandbox host for test data or the Production host for live data. Use credentials from the same environment.

Authorizations

Authorization

string

header

required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Path Parameters

subscriptionId

string<uuid>

required

The unique identifier of the subscription.

Body

application/json

offerType

enum<string>

required

The offer to apply. Must be the offer configured for cancellationFeedback.

Available options:

DISCOUNT,

PAUSE,

SUPPORT

Example:

"PAUSE"

cancellationFeedback

enum<string>

required

The cancellation reason the customer picked.

Available options:

TOO_EXPENSIVE,

MISSING_FEATURES,

SWITCHED_SERVICE,

UNUSED,

CUSTOMER_SERVICE,

LOW_QUALITY,

TOO_COMPLEX,

OTHER

Example:

"UNUSED"

pauseMonths

integer | null

Required when offerType is PAUSE. Must be one of the durations returned by Get retention offers.

Required range: x >= 1

Example:

3

Response

The offer was applied. The fields after cancellationFeedback depend on offerType.

message

string

Example:

"Subscription paused successfully"

subscriptionId

string<uuid>

offerType

enum<string>

Available options:

DISCOUNT,

PAUSE,

SUPPORT

cancellationFeedback

enum<string>

Available options:

TOO_EXPENSIVE,

MISSING_FEATURES,

SWITCHED_SERVICE,

UNUSED,

CUSTOMER_SERVICE,

LOW_QUALITY,

TOO_COMPLEX,

OTHER

percentageOff

integer

DISCOUNT only.

Example:

20

billingCycles

integer

DISCOUNT only.

Example:

3

appliesUntil

string<date-time> | null

DISCOUNT only. When the discount stops applying, or null when it applies to a single invoice.

originalAmount

string

DISCOUNT only. The amount billed per period before the discount.

Example:

"50.00"

discountedAmount

string

DISCOUNT only. The amount billed per period while the discount lasts.

Example:

"40.00"

pauseMonths

integer

PAUSE only.

Example:

3

resumesAt

string<date-time>

PAUSE only. When billing and access resume.

url

string

SUPPORT only. The support URL to send the customer to.

Example:

"https://cal.com/acme/15min"

Get Started

API Documentation

Accept a retention offer

Authorizations

Path Parameters

Body

Response