Core Resources

Retention strategiesNew

A Retention strategy is a cancellation reason a customer can choose when cancelling, together with the message and optional incentive (a discount, skipping a charge, delaying the subscription or swapping the product) offered to keep them subscribed.

This resource is new in the V2 reference. It also works when you send X-Recharge-Version: 2021-11.

Endpoints

GET/retention_strategies
GET/retention_strategies/{id}
POST/retention_strategies
PUT/retention_strategies/{id}
DELETE/retention_strategies/{id}

#The retention strategy object

Attributes

idinteger
Unique numeric identifier for the Retention strategy.
cancellation_flow_typestring
The kind of cancellation the Retention strategy is offered for.
Possible values
subscriptionmembership
reasonstring
The cancellation reason shown to the customer.
prevention_textstring · nullable
The message shown to the customer after selecting the cancellation reason, to encourage them not to cancel.
incentive_typestring · nullable
The incentive offered to the customer to prevent the cancellation. null when no incentive is offered.
Possible values
discountskip_chargedelay_subscriptionswap_product
discount_codestring · nullable
The code of the Discount offered to the customer. Only set when incentive_type is discount.
originstring · nullable
Set to active_churn_flow when the Retention strategy belongs to a cancellation flow; otherwise null.
Possible values
active_churn_flow
created_atdatetime
The date and time when the Retention strategy was created.
updated_atdatetime
The date and time when the Retention strategy was last updated.
includeobject
Related objects requested with the include query parameter.
Only returned when the include query parameter is passed.
Show child attributesHide child attributes1
- discountobject
  The Discount matching discount_code.
  Only returned when include contains discount and a matching Discount exists.
  Show child attributesHide child attributes6
  - idinteger
    Unique numeric identifier for the Discount.
  - codestring · nullable
    The code used to apply the Discount.
  - valuefloat
    The discounted value to be applied.
  - value_typestring
    The type of the discount value.
    Possible values
    fixed_amountpercentageshipping
  - titlestring · nullable
    The title of the Discount.
  - application_methodstring · nullable
    How the Discount is applied.
    Possible values
    codeautomatic

The retention strategy object

{
  "retention_strategy": {
    "id": 9042,
    "cancellation_flow_type": "subscription",
    "created_at": "2026-08-03T18:22:10+00:00",
    "discount_code": "STAY10",
    "incentive_type": "discount",
    "origin": null,
    "prevention_text": "Stay with us and save 10% on your next order.",
    "reason": "This is too expensive",
    "updated_at": "2026-08-03T18:22:10+00:00"
  }
}

#List retention strategies

GET/retention_strategies

Returns a list of the store's Retention strategies. By default only strategies without an origin are returned.

Scoperead_subscriptions

Query parameters

cancellation_flow_typestring
Return the retention strategies offered for the given kind of cancellation.
Possible values
subscriptionmembership
originstring
Pass active_churn_flow to also return the retention strategies that belong to a cancellation flow.
Possible values
active_churn_flow
includestring
Pass discount to return the Discount matching discount_code under include. Also requires the read_discounts scope.
Possible values
discount
sort_bystring
Sort the results by the given field and direction. Default is id-desc.
Possible values
id-ascid-desc
limitinteger
The amount of results. Default is 50 while the maximum is 250.
pageinteger
The page of results to show. Default is 1. Use cursor instead where possible.
cursorstring
The next_cursor or previous_cursor value returned by a previous list request. When a cursor is passed, only limit can be passed with it.

GET/retention_strategies

curl 'https://api.rechargeapps.com/retention_strategies' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "retention_strategies": [
    {
      "id": 9042,
      "cancellation_flow_type": "subscription",
      "created_at": "2026-08-03T18:22:10+00:00",
      "discount_code": "STAY10",
      "incentive_type": "discount",
      "origin": null,
      "prevention_text": "Stay with us and save 10% on your next order.",
      "reason": "This is too expensive",
      "updated_at": "2026-08-03T18:22:10+00:00"
    },
    {
      "id": 9041,
      "cancellation_flow_type": "subscription",
      "created_at": "2026-08-03T18:20:47+00:00",
      "discount_code": null,
      "incentive_type": "skip_charge",
      "origin": null,
      "prevention_text": "Need a break? Skip your next order instead.",
      "reason": "I have too much product",
      "updated_at": "2026-08-03T18:20:47+00:00"
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}

#Retrieve a retention strategy

GET/retention_strategies/{id}

Returns a single Retention strategy by its id.

Scoperead_subscriptions

Query parameters

includestring
Pass discount to return the Discount matching discount_code under include. Also requires the read_discounts scope.
Possible values
discount

GET/retention_strategies/{id}

curl 'https://api.rechargeapps.com/retention_strategies/129593' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "retention_strategy": {
    "id": 9042,
    "cancellation_flow_type": "subscription",
    "created_at": "2026-08-03T18:22:10+00:00",
    "discount_code": "STAY10",
    "incentive_type": "discount",
    "origin": null,
    "prevention_text": "Stay with us and save 10% on your next order.",
    "reason": "This is too expensive",
    "updated_at": "2026-08-03T18:22:10+00:00"
  }
}

#Create a retention strategy

POST/retention_strategies

Creates a Retention strategy: a cancellation reason with the message, and optionally the incentive, shown to a customer who selects it.

Scopewrite_retention_strategies

Body parameters

reasonstringRequired
The cancellation reason shown to the customer. Maximum 255 characters.
prevention_textstringRequired
The message shown to the customer after selecting the cancellation reason. Maximum 255 characters.
incentive_typestring
The incentive offered to the customer to prevent the cancellation. Strategies with a cancellation_flow_type of membership only support discount, swap_product or no incentive.
Possible values
discountskip_chargedelay_subscriptionswap_product
discount_codestring
The code of an existing, enabled Discount to offer. Required when incentive_type is discount, and ignored for any other incentive_type.
cancellation_flow_typestring
The kind of cancellation the Retention strategy is offered for. Defaults to subscription.
Possible values
subscriptionmembership
originstring
Pass active_churn_flow to attach the Retention strategy to a cancellation flow.
Possible values
active_churn_flow

POST/retention_strategies

curl -X POST 'https://api.rechargeapps.com/retention_strategies' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "retention_strategy": {
    "id": 9042,
    "cancellation_flow_type": "subscription",
    "created_at": "2026-08-03T18:22:10+00:00",
    "discount_code": "STAY10",
    "incentive_type": "discount",
    "origin": null,
    "prevention_text": "Stay with us and save 10% on your next order.",
    "reason": "This is too expensive",
    "updated_at": "2026-08-03T18:22:10+00:00"
  }
}

#Update a retention strategy

PUT/retention_strategies/{id}

Updates a Retention strategy. Only the attributes passed in the request are changed; at least one attribute is required.

Scopewrite_retention_strategies

Body parameters

reasonstring
The cancellation reason shown to the customer. Maximum 255 characters.
prevention_textstring
The message shown to the customer after selecting the cancellation reason. Maximum 255 characters.
incentive_typestring
The incentive offered to the customer to prevent the cancellation. Strategies with a cancellation_flow_type of membership only support discount, swap_product or no incentive.
Possible values
discountskip_chargedelay_subscriptionswap_product
discount_codestring
The code of an existing, enabled Discount to offer. Required when incentive_type is discount, and ignored for any other incentive_type.
cancellation_flow_typestring
The kind of cancellation the Retention strategy is offered for. Defaults to subscription.
Possible values
subscriptionmembership
originstring
Pass active_churn_flow to attach the Retention strategy to a cancellation flow.
Possible values
active_churn_flow

PUT/retention_strategies/{id}

curl -X PUT 'https://api.rechargeapps.com/retention_strategies/129593' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

{
  "retention_strategy": {
    "id": 9042,
    "cancellation_flow_type": "subscription",
    "created_at": "2026-08-03T18:22:10+00:00",
    "discount_code": "STAY10",
    "incentive_type": "discount",
    "origin": null,
    "prevention_text": "Stay with us and save 10% on your next order.",
    "reason": "This is too expensive",
    "updated_at": "2026-08-03T18:22:10+00:00"
  }
}

#Delete a retention strategy

DELETE/retention_strategies/{id}

Permanently deletes a Retention strategy.

Scopewrite_retention_strategies

DELETE/retention_strategies/{id}

curl -X DELETE 'https://api.rechargeapps.com/retention_strategies/129593' \
  -H 'X-Recharge-Version: v2' \
  -H 'X-Recharge-Access-Token: your_api_token'

Response

No content is returned for this response.