View Source Stripe.SubscriptionSchedule (stripity_stripe v3.1.1)

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.

Related guide: Subscription schedules

Link to this section Summary

Types

Automatic tax settings for this phase.

Object representing the subscription schedule's default settings.

All invoices will be billed using the specified settings.

Data used to generate a new Price object inline.

The recurring components of a price such as interval and interval_count.

t()

The subscription_schedule type.

Functions

Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

Retrieves the list of your subscription schedules.

Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription’s ID to the released_subscription property.

Retrieves the details of an existing subscription schedule. You only need to supply the unique subscription schedule identifier that was returned upon subscription schedule creation.

Updates an existing subscription schedule.

Link to this section Types

@type add_invoice_items() :: %{
  optional(:price) => binary(),
  optional(:price_data) => price_data(),
  optional(:quantity) => integer(),
  optional(:tax_rates) => [binary()] | binary()
}
@type automatic_tax() :: %{optional(:enabled) => boolean()}

Automatic tax settings for this phase.

@type billing_thresholds() :: %{
  optional(:amount_gte) => integer(),
  optional(:reset_billing_cycle_anchor) => boolean()
}
@type canceled_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type completed_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type default_settings() :: %{
  optional(:application_fee_percent) => number(),
  optional(:automatic_tax) => automatic_tax(),
  optional(:billing_cycle_anchor) => :automatic | :phase_start,
  optional(:billing_thresholds) => billing_thresholds() | binary(),
  optional(:collection_method) => :charge_automatically | :send_invoice,
  optional(:default_payment_method) => binary(),
  optional(:description) => binary() | binary(),
  optional(:invoice_settings) => invoice_settings(),
  optional(:on_behalf_of) => binary() | binary(),
  optional(:transfer_data) => transfer_data() | binary()
}

Object representing the subscription schedule's default settings.

@type invoice_settings() :: %{optional(:days_until_due) => integer()}

All invoices will be billed using the specified settings.

@type items() :: %{
  optional(:billing_thresholds) => billing_thresholds() | binary(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:plan) => binary(),
  optional(:price) => binary(),
  optional(:price_data) => price_data(),
  optional(:quantity) => integer(),
  optional(:tax_rates) => [binary()] | binary()
}
@type phases() :: %{
  optional(:add_invoice_items) => [add_invoice_items()],
  optional(:application_fee_percent) => number(),
  optional(:automatic_tax) => automatic_tax(),
  optional(:billing_cycle_anchor) => :automatic | :phase_start,
  optional(:billing_thresholds) => billing_thresholds() | binary(),
  optional(:collection_method) => :charge_automatically | :send_invoice,
  optional(:coupon) => binary(),
  optional(:currency) => binary(),
  optional(:default_payment_method) => binary(),
  optional(:default_tax_rates) => [binary()] | binary(),
  optional(:description) => binary() | binary(),
  optional(:end_date) => integer(),
  optional(:invoice_settings) => invoice_settings(),
  optional(:items) => [items()],
  optional(:iterations) => integer(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:on_behalf_of) => binary(),
  optional(:proration_behavior) => :always_invoice | :create_prorations | :none,
  optional(:transfer_data) => transfer_data(),
  optional(:trial) => boolean(),
  optional(:trial_end) => integer()
}
@type price_data() :: %{
  optional(:currency) => binary(),
  optional(:product) => binary(),
  optional(:recurring) => recurring(),
  optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
  optional(:unit_amount) => integer(),
  optional(:unit_amount_decimal) => binary()
}

Data used to generate a new Price object inline.

@type recurring() :: %{
  optional(:interval) => :day | :month | :week | :year,
  optional(:interval_count) => integer()
}

The recurring components of a price such as interval and interval_count.

@type released_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type t() :: %Stripe.SubscriptionSchedule{
  application: (binary() | term() | term()) | nil,
  canceled_at: integer() | nil,
  completed_at: integer() | nil,
  created: integer(),
  current_phase: term() | nil,
  customer: binary() | Stripe.Customer.t() | Stripe.DeletedCustomer.t(),
  default_settings: term(),
  end_behavior: binary(),
  id: binary(),
  livemode: boolean(),
  metadata: term() | nil,
  object: binary(),
  phases: term(),
  released_at: integer() | nil,
  released_subscription: binary() | nil,
  status: binary(),
  subscription: (binary() | Stripe.Subscription.t()) | nil,
  test_clock: (binary() | Stripe.TestHelpers.TestClock.t()) | nil
}

The subscription_schedule type.

  • application ID of the Connect Application that created the schedule.
  • canceled_at Time at which the subscription schedule was canceled. Measured in seconds since the Unix epoch.
  • completed_at Time at which the subscription schedule was completed. Measured in seconds since the Unix epoch.
  • created Time at which the object was created. Measured in seconds since the Unix epoch.
  • current_phase Object representing the start and end dates for the current phase of the subscription schedule, if it is active.
  • customer ID of the customer who owns the subscription schedule.
  • default_settings
  • end_behavior Behavior of the subscription schedule and underlying subscription when it ends. Possible values are release or cancel with the default being release. release will end the subscription schedule and keep the underlying subscription running.cancel will end the subscription schedule and cancel the underlying subscription.
  • id Unique identifier for the object.
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  • object String representing the object's type. Objects of the same type share the same value.
  • phases Configuration for the subscription schedule's phases.
  • released_at Time at which the subscription schedule was released. Measured in seconds since the Unix epoch.
  • released_subscription ID of the subscription once managed by the subscription schedule (if it is released).
  • status The present status of the subscription schedule. Possible values are not_started, active, completed, released, and canceled. You can read more about the different states in our behavior guide.
  • subscription ID of the subscription managed by the subscription schedule.
  • test_clock ID of the test clock this subscription schedule belongs to.
@type transfer_data() :: %{
  optional(:amount_percent) => number(),
  optional(:destination) => binary()
}

Link to this section Functions

Link to this function

cancel(schedule, params \\ %{}, opts \\ [])

View Source
@spec cancel(
  schedule :: binary(),
  params :: %{
    optional(:expand) => [binary()],
    optional(:invoice_now) => boolean(),
    optional(:prorate) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Cancels a subscription schedule and its associated subscription immediately (if the subscription schedule has an active subscription). A subscription schedule can only be canceled if its status is not_started or active.

Details

  • Method: post
  • Path: /v1/subscription_schedules/{schedule}/cancel
Link to this function

create(params \\ %{}, opts \\ [])

View Source
@spec create(
  params :: %{
    optional(:customer) => binary(),
    optional(:default_settings) => default_settings(),
    optional(:end_behavior) => :cancel | :none | :release | :renew,
    optional(:expand) => [binary()],
    optional(:from_subscription) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:phases) => [phases()],
    optional(:start_date) => integer() | :now
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates a new subscription schedule object. Each customer can have up to 500 active or scheduled subscriptions.

Details

  • Method: post
  • Path: /v1/subscription_schedules
Link to this function

list(params \\ %{}, opts \\ [])

View Source
@spec list(
  params :: %{
    optional(:canceled_at) => canceled_at() | integer(),
    optional(:completed_at) => completed_at() | integer(),
    optional(:created) => created() | integer(),
    optional(:customer) => binary(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:released_at) => released_at() | integer(),
    optional(:scheduled) => boolean(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the list of your subscription schedules.

Details

  • Method: get
  • Path: /v1/subscription_schedules
Link to this function

release(schedule, params \\ %{}, opts \\ [])

View Source
@spec release(
  schedule :: binary(),
  params :: %{
    optional(:expand) => [binary()],
    optional(:preserve_cancel_date) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Releases the subscription schedule immediately, which will stop scheduling of its phases, but leave any existing subscription in place. A schedule can only be released if its status is not_started or active. If the subscription schedule is currently associated with a subscription, releasing it will remove its subscription property and set the subscription’s ID to the released_subscription property.

Details

  • Method: post
  • Path: /v1/subscription_schedules/{schedule}/release
Link to this function

retrieve(schedule, params \\ %{}, opts \\ [])

View Source
@spec retrieve(
  schedule :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the details of an existing subscription schedule. You only need to supply the unique subscription schedule identifier that was returned upon subscription schedule creation.

Details

  • Method: get
  • Path: /v1/subscription_schedules/{schedule}
Link to this function

update(schedule, params \\ %{}, opts \\ [])

View Source
@spec update(
  schedule :: binary(),
  params :: %{
    optional(:default_settings) => default_settings(),
    optional(:end_behavior) => :cancel | :none | :release | :renew,
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:phases) => [phases()],
    optional(:proration_behavior) =>
      :always_invoice | :create_prorations | :none
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates an existing subscription schedule.

Details

  • Method: post
  • Path: /v1/subscription_schedules/{schedule}