Revenue Recovery

Change the settings

curl -X PUT https://api.subscriby.net/v1/projects/7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13/retention \
  -H "Authorization: Bearer sbt_..." \
  -H "Idempotency-Key: 6b1f0d2e-9c3a-4e8b-b2d1-7a9c5e3f1d04" \
  -H "Content-Type: application/json" \
  -d '{"grace_days": 10, "offer_pause_enabled": true, "offer_return_coupon_id": "3b7c9d1e-5f24-4a86-9c0b-2d4e6f8a1b3c"}'

Every field is optional and the row keeps its stored value for each one left out, so a client can flip the digest without restating the window. A coupon must be one of the project's own; send null to clear an offer. The two nurture windows are whole numbers within their bounds (checkout_stall_hours 1 to 24, trial_notice_days 1 to 14); a checkout already open is judged by the window in force when the hourly sweep runs. The answer is the settings as they now read.

A grace window of 0 pauses access at the first failure. The never-paid trial keeps today's immediate revoke whatever the window says, and a one-time purchase never enters grace.

put/v1/projects/{project}/retention

Request

  • Base URL: https://api.subscriby.net
  • URL: https://api.subscriby.net/v1/projects/{project}/retention
  • Auth: HTTP bearer

Path parameters

projectstring uuid required

The project, resolved by the route binder.

Headers

Idempotency-Keystring uuid required

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Request body

grace_daysinteger

How many days a failed renewal keeps access while the gateway retries, 0 to 30. 0 pauses access at the failure.

digest_enabledboolean

Whether the owner gets one message a day with the failures, reminders, pauses and recoveries, only on a day something happened.

cancel_feedback_enabledboolean

Whether the cancellation screen asks the member why before the offer. Off skips straight to the offer.

offer_pause_enabledboolean

Whether a cancelling member on Stripe or PayPal is offered one billing cycle on hold. Needs the Growth plan or the Revenue Recovery Addon; ignored by the screen without it.

offer_discount_coupon_idstring nullable

One of this project's coupons, applied to the member's renewals where Stripe can carry it, or null for no discount offer. Needs the Growth plan or the Revenue Recovery Addon.

offer_return_coupon_idstring nullable

One of this project's coupons, handed to the member on the way out on every payment method, or null for no return coupon. Needs the Growth plan or the Revenue Recovery Addon.

checkout_stall_hoursinteger

How many hours a checkout may stay open with no settled charge before the hourly sweep counts it as stalled and the stalled-checkout sequences start, 1 to 24; such as 4.

trial_notice_daysinteger

How many days before a trial without a card ends its trial-ending sequences start, 1 to 14; such as 3. A trial shorter than that enrols at its start.

Response

The settings as they now read.

Example response

{
  "data": {
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "grace_days": 7,
    "ladder": "A failed renewal keeps access for 7 days: a notice at the failure, a reminder on day 3, a final warning on the last day, then access pauses until a charge settles.",
    "digest_enabled": true,
    "cancel_feedback_enabled": true,
    "checkout_stall_hours": 1,
    "trial_notice_days": 3,
    "offers_available": true,
    "offer_pause_enabled": true,
    "offer_discount_coupon": {
      "id": "3b7c9d1e-5f24-4a86-9c0b-2d4e6f8a1b3c",
      "code": "STAY20"
    },
    "updated_at": "2026-10-12T09:00:00+00:00"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.