Skip to main content
PATCH
/
v1
/
subscription_protocol
Update
curl --request PATCH \
  --url https://{defaultHost}/v1/subscription_protocol \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscription_protocol": {
    "downgrade_behavior": "immediate"
  }
}
'
{
  "id": "f8b654db-435b-4f6d-9ca3-68b13941ebde",
  "object": "subscription_protocol",
  "bypass_duplicate_trials": false,
  "cancel_behavior": "pending",
  "cancel_window_enabled": false,
  "cancel_window_days": 14,
  "default_payment_method_detach_enabled": false,
  "default_payment_method_fallback_enabled": true,
  "downgrade_behavior": "immediate",
  "payment_retry_window_weeks": 1,
  "preservation_enabled": false,
  "preservation_locales": {
    "reasons_title": "We're sad to see you go",
    "reasons_description": "Before you cancel, please let us know the reason you're leaving.",
    "skip_link": "Never mind, I don't want to cancel.",
    "preserve_title": "Take {{ amount }} off your next payment?",
    "preserve_description": "We'd be happy to offer you  {{ amount }} off your next payment if you'd stay with us.",
    "preserve_button": "Yes, I'll take it.",
    "cancel_link": "No thanks, I'd still like to cancel."
  },
  "remind_at_period_percent_remaining": 10,
  "remind_after_days": null,
  "require_upfront_payment_method": true,
  "revoke_purchases_on_past_due": false,
  "upgrade_behavior": "immediate",
  "preservation_coupon": "f5248aca-971f-42fe-91cd-da0a026e85e8",
  "created_at": 1767909775,
  "updated_at": 1767909775
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
subscription_protocol
object

Response

200 - application/json

Success

​
id
string | null

The UUID of the specific object.

​
object
string

A string describing the object type returned.

​
bypass_duplicate_trials
boolean

Whether or not to skip the trial period for a product if the customer has already been in a trial.

​
cancel_behavior
string

Controls how subscription cancellations should be handled – one of immediate or pending.

​
cancel_window_enabled
boolean

Whether or not the subscription cancel window is enabled.

​
cancel_window_days
integer

The number of days prior to a subscription renewing that the cancel option will be visible to customers.

​
default_payment_method_detach_enabled
boolean

Whether or not default payment methods can be removed.

​
default_payment_method_fallback_enabled
boolean

Whether or not the customer's default payment method should be used as a fallback when a subscription does not have a payment method.

​
downgrade_behavior
string

Controls how subscription changes should be handled when downgrading – one of immediate or pending.

​
payment_retry_window_weeks
integer

The number of weeks to retry failed subscription payments before canceling the subscription.

​
preservation_enabled
boolean

Whether or not subscription preservation is enabled.

​
preservation_locales
object

A collection of locale strings that will be used when displaying the subscription preservation flow to customers. These strings have access to the following liquid variables: amount and name.

​
remind_at_period_percent_remaining
number

Specifies the percentage of time remaining in the subscription period at which a reminder should be sent. For example, if set to 25%, the reminder will be triggered when there is 25% of the subscription period remaining.

​
remind_after_days
integer | null

Specifies the minimum number of days that must pass since the last reminder (or subscription creation if no reminder has been sent) before a new reminder can be sent. For example, if set to 180, a reminder will only be sent if at least 180 days have passed since the last reminder. This prevents reminders from being sent too frequently across multiple subscription periods.

​
require_upfront_payment_method
boolean

Whether or not a payment method should be required for subscriptions that have an initial period amount of $0 (free trial or coupon).

​
revoke_purchases_on_past_due
boolean

Whether or not a purchase should be revoked when a subscription becomes past_due. If the subscription transitions to the active or trialing state the associated purchase will be automatically invoked again.

​
upgrade_behavior
string

Controls how subscription changes should be handled when upgrading – one of immediate or pending.

​
preservation_coupon

The coupon that is applied to subscriptions when a cancellation reason with coupon_enabled=true is selected and the susbcription is preserved.

Expandable – The associated preservation coupon ID.

​
created_at
integer | null

Time at which the object was created. Measured in seconds since the Unix epoch.

​
updated_at
integer | null

Time at which the object was last updated. Measured in seconds since the Unix epoch.