Bling.Subscriptions (bling v0.4.0)

Module to interact with Bling subscriptions. Most functions expect the ecto subscription struct as the first argument, and will return the updated subscription with subscription items preloaded.

Link to this section Summary

Functions

Returns whether the provided subscription is active, which is if it has not ended, and it has a valid status.

Adds prices to an existing subscription. Returns the subscription with the items loaded.

Fetches the stripe subscription object from a database subscription.

Cancels the subscription in stripe and updates the model. Cancellation is scheduled for the end of the period.

Cancels a subscription at a specific time.

Cancels and ends the subscription immediately.

Cancels, ends, and invoices for the subscription immediately. Forwards any stripe options to Bling.Subscriptions.cancel_now/2.

Returns whether the provided subscription has been cancelled.

Changes the subscription to new prices.

Decrements the quantity of a subscription item. Defaults to decrementing the first item. Defaults to decrementing by one. Raises if trying to go below 0.

Deletes the subscription from the database as well as cancels it in stripe.

Returns whether the provided subscription has been cancelled and is no longer within its grace period.

Returns whether the provided subcription has been cancelled but has time before it ends.

Returns whether the provided subscription has multiple subscription items (prices).

Returns whether the provided subscription has only a single subscription item (price).

Increments the quantity of a subscription item. Defaults to incrementing the first item. Defaults to incrementing by one.

Returns whether the provided subscription is recurring, which is the case if it has no end date and is not on a trial.

Removes prices from a subscription. Returns the subscription with the items loaded.

Resumes a cancelled subscription. The grace period must not have ended in order for this to succeed.

Sets the quantity of a subscription item. Defaults to setting the first item. Defaults to setting to one.

Turns an array of stripe subscription items into database subscription structs. Meant for internal use.

Returns all of the database subscription items for a subscription.

Turns a stripe subscription object into a database subscription without committing it. Meant for internal use.

Returns whether the provided subscription is on a trial that hasn't expired.

Returns whether the provided subscription is valid, which is the case if any of the following checks are true

Link to this section Functions

Link to this function

active?(subscription)

Returns whether the provided subscription is active, which is if it has not ended, and it has a valid status.

Link to this function

add_prices(subscription, opts)

Adds prices to an existing subscription. Returns the subscription with the items loaded.

examples

Examples

add_prices(subscription, prices: [{price_id, quantity}])
Link to this function

as_stripe_subscription(subscription)

Fetches the stripe subscription object from a database subscription.

Link to this function

cancel(subscription, opts \\ [])

Cancels the subscription in stripe and updates the model. Cancellation is scheduled for the end of the period.

If the user is on a trial, they will have until the end of their trial.

examples

Examples

subscription = cancel(subscription)

# can pass any valid Stripe.Subscription.update/2 params
subscription = cancel(subscription, stripe: %{ prorate: false })
Link to this function

cancel_at(subscription, datetime, opts \\ [])

Cancels a subscription at a specific time.

examples

Examples

subscription = cancel_at(subscription, DateTime.utc_now() |> DateTime.add(30, :day))

# can pass any valid Stripe.Subscription.update/2 params
subscription = cancel_at(subscription, DateTime.utc_now() |> DateTime.add(30, :day), stripe: %{ prorate: false })
Link to this function

cancel_now(subscription, opts \\ [])

Cancels and ends the subscription immediately.

examples

Examples

subscription = cancel_now(subscription)

# can pass any valid Stripe.Subscription.delete/2 params
subscription = cancel_now(subscription, stripe: %{ invoice_now: true })
Link to this function

cancel_now_and_invoice(subscription, opts \\ [])

Cancels, ends, and invoices for the subscription immediately. Forwards any stripe options to Bling.Subscriptions.cancel_now/2.

Link to this function

canceled?(subscription)

Returns whether the provided subscription has been cancelled.

Link to this function

change_prices(subscription, opts \\ [])

Changes the subscription to new prices.

examples

Examples

change_prices(sub, prices: [{price_id, quantity}])
Link to this function

decrement(subscription, opts \\ [])

Decrements the quantity of a subscription item. Defaults to decrementing the first item. Defaults to decrementing by one. Raises if trying to go below 0.

## Examples

  # this would update the first subscription item's quantity by one
  # useful for single price subscriptions
  subscription = decrement(subscription)

  # you can also specify a price and quantity to decrement by
  subscription = decrement(subscription, price_id: "price_123", quantity: 2)

  # can pass any valid Stripe.SubscriptionItem.update/2 params
  subscription = decrement(subscription, stripe: %{ prorate: false })
Link to this function

delete(subscription, opts \\ [])

Deletes the subscription from the database as well as cancels it in stripe.

examples

Examples

subscription = delete(subscription)

# can pass any valid Stripe.Subscription.delete/2 params
subscription = delete(subscription, stripe: %{ invoice_now: true })
Link to this function

ended?(subscription)

Returns whether the provided subscription has been cancelled and is no longer within its grace period.

Link to this function

grace_period?(subscription)

Returns whether the provided subcription has been cancelled but has time before it ends.

Link to this function

has_multiple_prices?(subscription)

Returns whether the provided subscription has multiple subscription items (prices).

Link to this function

has_single_price?(subscription)

Returns whether the provided subscription has only a single subscription item (price).

Link to this function

increment(subscription, opts \\ [])

Increments the quantity of a subscription item. Defaults to incrementing the first item. Defaults to incrementing by one.

examples

Examples

# this would update the first subscription item's quantity by one
# useful for single price subscriptions
subscription = increment(subscription)

# you can also specify a price and quantity to increment by
subscription = increment(subscription, price_id: "price_123", quantity: 2)

# can pass any valid Stripe.SubscriptionItem.update/2 params
subscription = increment(subscription, stripe: %{ prorate: false })
Link to this function

recurring?(subscription)

Returns whether the provided subscription is recurring, which is the case if it has no end date and is not on a trial.

Link to this function

remove_prices(subscription, opts)

Removes prices from a subscription. Returns the subscription with the items loaded.

Raises if all prices are removed from a subscription.

examples

Examples

remove_prices(subscription, prices: [price_id])
Link to this function

resume(subscription, opts \\ [])

Resumes a cancelled subscription. The grace period must not have ended in order for this to succeed.

examples

Examples

subscription = resume(subscription)

# can pass any valid Stripe.Subscription.update/2 params
subscription = resume(subscription, stripe: %{ prorate: false })
Link to this function

set_quantity(subscription, opts \\ [])

Sets the quantity of a subscription item. Defaults to setting the first item. Defaults to setting to one.

examples

Examples

# this would update the first subscription item's quantity to one
# useful for single price subscriptions
subscription = set_quantity(subscription)

# you can also specify a price and quantity to set to
subscription = set_quantity(subscription, price_id: "price_123", quantity: 2)

# can pass any valid Stripe.SubscriptionItem.update/2 params
subscription = set_quantity(subscription, stripe: %{ prorate: false })
Link to this function

subscription_item_structs_from_stripe_items(items, db_subscription)

Turns an array of stripe subscription items into database subscription structs. Meant for internal use.

examples

Examples

subscription =
  subscription_struct_from_stripe_subscription(MyApp.Subscriptions.Subscription, stripe_subscription)
  |> MyApp.Repo.insert()

subscription_items =
  subscription_item_structs_from_stripe_items(stripe_subscription.items.data, subscription)
  |> Enum.each(&MyApp.Repo.insert/1)
Link to this function

subscription_items(subscription)

Returns all of the database subscription items for a subscription.

Link to this function

subscription_struct_from_stripe_subscription(schema_or_subscription, event)

Turns a stripe subscription object into a database subscription without committing it. Meant for internal use.

examples

Examples

subscription =
  subscription_struct_from_stripe_subscription(MyApp.Subscriptions.Subscription, stripe_subscription)
  |> MyApp.Repo.insert()
Link to this function

trial?(subscription)

Returns whether the provided subscription is on a trial that hasn't expired.

Link to this function

valid?(subscription)

Returns whether the provided subscription is valid, which is the case if any of the following checks are true: