Retention offer

Long-standing Rotating Residential customers who are about to cancel can accept a one-off retention offer: 20% off the Rotating Residential price on the next renewal. The offer applies to a single renewal and can be accepted once per account.

The subscription object reports whether the offer can be accepted right now in the retention_discount_resi_20_available field. Check that flag before showing the offer; the endpoint below enforces the same rules server-side.

Eligibility

retention_discount_resi_20_available is true only when all of the following hold:

• Auto-renewal is enabled on the subscription.
• The subscription has exactly one active plan, and it is a Rotating Residential plan.
• The offer has never been accepted on this account. It is a once-per-account offer, regardless of whether it was later redeemed or voided.
• The Rotating Residential plan has been renewed at least twice, with no refunds since the plan was created.
• No renewal or payment is currently in progress for the subscription.

How the discount is applied

• The discount is applied automatically to the next renewal after acceptance. No further API call is required.
• It is calculated on the Rotating Residential portion of the renewal price only.
• It stacks on top of any coupon code or account promotion already applied to the renewal. The combined discount never exceeds the renewal price.
• The rate is frozen at acceptance, so later changes to the offer do not affect an outstanding one.
• If the Rotating Residential plan is cancelled before the renewal, the unredeemed offer is voided and cannot be accepted again.
• If the discounted plan is cancelled after the renewal, the refund is calculated from the discounted amount that was actually paid.

Accept the retention offer

Accepts the retention offer for the authenticated account.

Request & Response

POST https://proxy.webshare.io/api/v2/subscription/retention_offer/

import requests
 
response = requests.post(
    "https://proxy.webshare.io/api/v2/subscription/retention_offer/",
    headers={"Authorization": "Token APIKEY"}
)
 
response.json()

The commands above return a subscription object with retention_discount_resi_20_available set to false, since the offer has now been accepted:

{
  "id": 1,
  "plan": 2,
  "payment_method": 1,
  "free_credits": 13.37,
  "term": "monthly",
  "start_date": "2022-06-14T11:19:14.489458-07:00",
  "end_date": "2022-07-14T11:19:14.489461-07:00",
  "renewals_paid": 2,
  "renewals_enabled": true,
  "failed_payment_times": 0,
  "account_discount_percentage": 0,
  "promotion_available_first_time_renewal_25_off": false,
  "customizable": true,
  "paused": false,
  "reactivation_date": null,
  "reactivation_period_left": null,
  "promo_type": null,
  "promo_value": null,
  "retention_discount_resi_20_available": false,
  "throttled": false,
  "created_at": "2022-06-14T11:58:10.246406-07:00",
  "updated_at": "2022-06-14T11:58:10.246406-07:00"
}

Error responses

When the offer cannot be accepted, the endpoint returns a validation error of the form [{"message": "<message>", "code": "<error code>"}].