Braintree.Subscription (Braintree v0.13.0)
Manage customer subscriptions to recurring billing plans.
For additional reference see: https://developers.braintreepayments.com/reference/request/subscription/create/ruby
Link to this section Summary
Functions
Cancel an existing subscription by subscription_id
. A cancelled subscription
cannot be reactivated, you would need to create a new one.
Create a subscription, or return an error response with after failed validation.
Find an existing subscription by subscription_id
Convert a map into a Subscription struct. Add_ons and transactions are converted to a list of structs as well.
You can manually retry charging past due subscriptions.
To search for subscriptions, pass a map of search parameters.
To update a subscription, use its ID along with new attributes. The same validations apply as when creating a subscription. Any attribute not passed will remain unchanged.
Link to this section Types
@type t() :: %Braintree.Subscription{ add_ons: [Braintree.AddOn.t()], balance: String.t(), billing_day_of_month: String.t(), billing_period_end_date: String.t(), billing_period_start_date: String.t(), created_at: String.t(), current_billing_cycle: String.t(), days_past_due: String.t(), descriptor: String.t(), discounts: [any()], failure_count: String.t(), first_billing_date: String.t(), id: String.t(), merchant_account_id: String.t(), never_expires: String.t(), next_bill_amount: String.t(), next_billing_date: String.t(), next_billing_period_amount: String.t(), number_of_billing_cycles: String.t(), paid_through_date: String.t(), payment_method_token: String.t(), plan_id: String.t(), price: String.t(), status: String.t(), status_history: [any()], transactions: [Braintree.Transaction.t()], trial_duration: String.t(), trial_duration_unit: String.t(), trial_period: String.t(), updated_at: String.t() }
Link to this section Functions
cancel(subscription_id, opts \\ [])
@spec cancel(String.t(), Keyword.t()) :: {:ok, t()} | {:error, Braintree.ErrorResponse.t()}
Cancel an existing subscription by subscription_id
. A cancelled subscription
cannot be reactivated, you would need to create a new one.
example
Example
{:ok, subscription} = Subscription.cancel("123")
create(params \\ %{}, opts \\ [])
@spec create(map(), Keyword.t()) :: {:ok, t()} | {:error, Braintree.ErrorResponse.t()}
Create a subscription, or return an error response with after failed validation.
example
Example
{:ok, sub} = Braintree.Subscription.create(%{
payment_method_token: card.token,
plan_id: "starter"
})
find(subscription_id, opts \\ [])
@spec find(String.t(), Keyword.t()) :: {:ok, t()} | {:error, Braintree.ErrorResponse.t()}
Find an existing subscription by subscription_id
example
Example
{:ok, subscription} = Subscription.find("123")
new(params)
Convert a map into a Subscription struct. Add_ons and transactions are converted to a list of structs as well.
example
Example
subscripton = Braintree.Subscription.new(%{"plan_id" => "business",
"status" => "Active"})
retry_charge(subscription_id, amount \\ nil, opts \\ [])
@spec retry_charge(String.t(), String.t() | nil, Keyword.t()) :: {:ok, Braintree.Transaction.t()} | {:error, Braintree.ErrorResponse.t()}
You can manually retry charging past due subscriptions.
By default, we will use the subscription balance when retrying the transaction. If you would like to use a different amount you can optionally specify the amount for the transaction.
A successful manual retry of a past due subscription will always reduce the balance of that subscription to $0, regardless of the amount of the retry.
example
Example
{:ok, transaction} = Braintree.Subscription.retry_charge(sub_id)
{:ok, transaction} = Braintree.Subscription.retry_charge(sub_id, "24.00")
search(params, opts \\ [])
@spec search(map(), Keyword.t()) :: {:ok, t()} | {:error, Braintree.ErrorResponse.t()}
To search for subscriptions, pass a map of search parameters.
example
Example:
= Braintree.Subscription.search(%{plan_id: %{is: "starter"}})
update(id, params, opts \\ [])
@spec update(binary(), map(), Keyword.t()) :: {:ok, t()} | {:error, Braintree.ErrorResponse.t()}
To update a subscription, use its ID along with new attributes. The same validations apply as when creating a subscription. Any attribute not passed will remain unchanged.
example
Example
{:ok, subscription} = Braintree.Subscription.update("subscription_id", %{
plan_id: "new_plan_id"
})
subscription.plan_id # "new_plan_id"