Skip to main content
GET
/
v1
/
subscription_protocol
Retrieve
curl --request GET \
  --url https://{defaultHost}/v1/subscription_protocol \
  --header 'Authorization: Bearer <token>'
{
  "id": "70c48b6d-5f11-4837-b79e-6dd49ad01d51",
  "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": "pending",
  "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": "20efd9ec-f9e1-4522-afc4-ff238932d13f",
  "created_at": 1771429911,
  "updated_at": 1771429911
}

Authorizations

​
Authorization
string
header
required

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

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.

​
reschedule_existing_reminders
boolean | null
default:false

Whether or not existing subscription reminders should be recalculated. Only applicable when remind_at_period_percent_remaining or remind_after_days are changed.

​
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.