View Source Stripe.SubscriptionSchedule (stripity_stripe v3.2.0)

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.

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

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

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

Retrieves the list of your subscription schedules.

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

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.

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

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.

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

Updates an existing subscription schedule.

Types

add_invoice_items()

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

automatic_tax()

@type automatic_tax() :: %{optional(:enabled) => boolean()}

Automatic tax settings for this phase.

billing_thresholds()

@type billing_thresholds() :: %{
  optional(:amount_gte) => integer(),
  optional(:reset_billing_cycle_anchor) => boolean()
}

canceled_at()

@type canceled_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

completed_at()

@type completed_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

created()

@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

default_settings()

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

invoice_settings()

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

All invoices will be billed using the specified settings.

items()

@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()
}

phases()

@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()
}

price_data()

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

recurring()

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

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

released_at()

@type released_at() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

t()

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

transfer_data()

@type transfer_data() :: %{
  optional(:amount_percent) => number(),
  optional(:destination) => binary()
}

Functions

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

@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()}

Details

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

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

@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

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

@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

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

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

Details

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

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

@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}

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

@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}