Class: Stripe::Plan

Inherits:
APIResource show all
Extended by:
APIOperations::Create, APIOperations::List
Includes:
APIOperations::Delete, APIOperations::Save
Defined in:
lib/stripe/resources/plan.rb

Overview

You can now model subscriptions more flexibly using the [Prices API](api.stripe.com#prices). It replaces the Plans API and is backwards compatible to simplify your migration.

Plans define the base price, currency, and billing cycle for recurring purchases of products. [Products](api.stripe.com#products) help you track inventory or provisioning, and plans help you track pricing. Different physical goods or levels of service should be represented by products, and pricing options should be represented by plans. This approach lets you change prices without having to change your provisioning scheme.

For example, you might have a single “gold” product that has plans for $10/month, $100/year, €9/month, and €90/year.

Related guides: [Set up a subscription](docs.stripe.com/billing/subscriptions/set-up-subscription) and more about [products and prices](docs.stripe.com/products-prices/overview).

Defined Under Namespace

Classes: Tier, TransformUsage

Constant Summary collapse

OBJECT_NAME = 
"plan"

Constants inherited from StripeObject

StripeObject::RESERVED_FIELD_NAMES

Instance Attribute Summary collapse

Attributes inherited from APIResource

#save_with_parent

Attributes inherited from StripeObject

#last_response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIOperations::Create

create

Methods included from APIOperations::List

list

Methods included from APIOperations::Save

included, #save

Methods included from APIOperations::Delete

included

Methods inherited from APIResource

class_name, custom_method, #refresh, #request_stripe_object, resource_url, #resource_url, retrieve, save_nested_resource

Methods included from APIOperations::Request

included

Methods inherited from StripeObject

#==, #[], #[]=, #_get_inner_class_type, additive_object_param, additive_object_param?, #as_json, construct_from, #deleted?, #dirty!, #each, #eql?, #hash, #initialize, #inspect, #keys, #marshal_dump, #marshal_load, protected_fields, #serialize_params, #to_hash, #to_json, #to_s, #update_attributes, #values

Constructor Details

This class inherits a constructor from Stripe::StripeObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Stripe::StripeObject

Instance Attribute Details

#active ⇒ Object (readonly)

Whether the plan can be used for new purchases.



67
68
69
 
# File 'lib/stripe/resources/plan.rb', line 67

def active
  @active
end

#amount ⇒ Object (readonly)

The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if ‘billing_scheme=per_unit`.



69
70
71
 
# File 'lib/stripe/resources/plan.rb', line 69

def amount
  @amount
end

#amount_decimal ⇒ Object (readonly)

The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if ‘billing_scheme=per_unit`.



71
72
73
 
# File 'lib/stripe/resources/plan.rb', line 71

def amount_decimal
  @amount_decimal
end

#billing_scheme ⇒ Object (readonly)

Describes how to compute the price per period. Either ‘per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `amount`) will be charged per unit in `quantity` (for plans with `usage_type=licensed`), or per unit of total usage (for plans with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes.



73
74
75
 
# File 'lib/stripe/resources/plan.rb', line 73

def billing_scheme
  @billing_scheme
end

#created ⇒ Object (readonly)

Time at which the object was created. Measured in seconds since the Unix epoch.



75
76
77
 
# File 'lib/stripe/resources/plan.rb', line 75

def created
  @created
end

#currency ⇒ Object (readonly)

Three-letter [ISO currency code](www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](stripe.com/docs/currencies).



77
78
79
 
# File 'lib/stripe/resources/plan.rb', line 77

def currency
  @currency
end

#deleted ⇒ Object (readonly)

Always true for a deleted object



79
80
81
 
# File 'lib/stripe/resources/plan.rb', line 79

def deleted
  @deleted
end

#id ⇒ Object (readonly)

Unique identifier for the object.



81
82
83
 
# File 'lib/stripe/resources/plan.rb', line 81

def id
  @id
end

#interval ⇒ Object (readonly)

The frequency at which a subscription is billed. One of ‘day`, `week`, `month` or `year`.



83
84
85
 
# File 'lib/stripe/resources/plan.rb', line 83

def interval
  @interval
end

#interval_count ⇒ Object (readonly)

The number of intervals (specified in the ‘interval` attribute) between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months.



85
86
87
 
# File 'lib/stripe/resources/plan.rb', line 85

def interval_count
  @interval_count
end

#livemode ⇒ Object (readonly)

If the object exists in live mode, the value is ‘true`. If the object exists in test mode, the value is `false`.



87
88
89
 
# File 'lib/stripe/resources/plan.rb', line 87

def livemode
  @livemode
end

#metadata ⇒ Object (readonly)

Set of [key-value pairs](docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.



89
90
91
 
# File 'lib/stripe/resources/plan.rb', line 89

def metadata
  @metadata
end

#meter ⇒ Object (readonly)

The meter tracking the usage of a metered price



91
92
93
 
# File 'lib/stripe/resources/plan.rb', line 91

def meter
  @meter
end

#nickname ⇒ Object (readonly)

A brief description of the plan, hidden from customers.



93
94
95
 
# File 'lib/stripe/resources/plan.rb', line 93

def nickname
  @nickname
end

#object ⇒ Object (readonly)

String representing the object’s type. Objects of the same type share the same value.



95
96
97
 
# File 'lib/stripe/resources/plan.rb', line 95

def object
  @object
end

#product ⇒ Object (readonly)

The product whose pricing this plan determines.



97
98
99
 
# File 'lib/stripe/resources/plan.rb', line 97

def product
  @product
end

#tiers ⇒ Object (readonly)

Each element represents a pricing tier. This parameter requires ‘billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`.



99
100
101
 
# File 'lib/stripe/resources/plan.rb', line 99

def tiers
  @tiers
end

#tiers_mode ⇒ Object (readonly)

Defines if the tiering price should be ‘graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows.



101
102
103
 
# File 'lib/stripe/resources/plan.rb', line 101

def tiers_mode
  @tiers_mode
end

#transform_usage ⇒ Object (readonly)

Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with ‘tiers`.



103
104
105
 
# File 'lib/stripe/resources/plan.rb', line 103

def transform_usage
  @transform_usage
end

#trial_period_days ⇒ Object (readonly)

Default number of trial days when subscribing a customer to this plan using [‘trial_from_plan=true`](docs.stripe.com/api#create_subscription-trial_from_plan).



105
106
107
 
# File 'lib/stripe/resources/plan.rb', line 105

def trial_period_days
  @trial_period_days
end

#usage_type ⇒ Object (readonly)

Configures how the quantity per period should be determined. Can be either ‘metered` or `licensed`. `licensed` automatically bills the `quantity` set when adding it to a subscription. `metered` aggregates the total usage based on usage records. Defaults to `licensed`.



107
108
109
 
# File 'lib/stripe/resources/plan.rb', line 107

def usage_type
  @usage_type
end

Class Method Details

.create(params = {}, opts = {}) ⇒ Object

You can now model subscriptions more flexibly using the [Prices API](docs.stripe.com/api#prices). It replaces the Plans API and is backwards compatible to simplify your migration.



110
111
112
 
# File 'lib/stripe/resources/plan.rb', line 110

def self.create(params = {}, opts = {})
  request_stripe_object(method: :post, path: "/v1/plans", params: params, opts: opts)
end

.delete(plan, params = {}, opts = {}) ⇒ Object

Deleting plans means new subscribers can’t be added. Existing subscribers aren’t affected.



115
116
117
118
119
120
121
122
 
# File 'lib/stripe/resources/plan.rb', line 115

def self.delete(plan, params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/plans/%<plan>s", { plan: CGI.escape(plan) }),
    params: params,
    opts: opts
  )
end

.field_encodings ⇒ Object 



157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/stripe/resources/plan.rb', line 157

def self.field_encodings
  @field_encodings = {
    amount_decimal: :decimal_string,
    tiers: {
      kind: :array,
      element: {
        kind: :object,
        fields: { flat_amount_decimal: :decimal_string, unit_amount_decimal: :decimal_string },
      },
    },
  }
end

.field_remappings ⇒ Object 



153
154
155
 
# File 'lib/stripe/resources/plan.rb', line 153

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



149
150
151
 
# File 'lib/stripe/resources/plan.rb', line 149

def self.inner_class_types
  @inner_class_types = { tiers: Tier, transform_usage: TransformUsage }
end

.list(params = {}, opts = {}) ⇒ Object

Returns a list of your plans.



135
136
137
 
# File 'lib/stripe/resources/plan.rb', line 135

def self.list(params = {}, opts = {})
  request_stripe_object(method: :get, path: "/v1/plans", params: params, opts: opts)
end

.object_name ⇒ Object 



20
21
22
 
# File 'lib/stripe/resources/plan.rb', line 20

def self.object_name
  "plan"
end

.update(plan, params = {}, opts = {}) ⇒ Object

Updates the specified plan by setting the values of the parameters passed. Any parameters not provided are left unchanged. By design, you cannot change a plan’s ID, amount, currency, or billing cycle.



140
141
142
143
144
145
146
147
 
# File 'lib/stripe/resources/plan.rb', line 140

def self.update(plan, params = {}, opts = {})
  request_stripe_object(
    method: :post,
    path: format("/v1/plans/%<plan>s", { plan: CGI.escape(plan) }),
    params: params,
    opts: opts
  )
end

Instance Method Details

#delete(params = {}, opts = {}) ⇒ Object

Deleting plans means new subscribers can’t be added. Existing subscribers aren’t affected.



125
126
127
128
129
130
131
132
 
# File 'lib/stripe/resources/plan.rb', line 125

def delete(params = {}, opts = {})
  request_stripe_object(
    method: :delete,
    path: format("/v1/plans/%<plan>s", { plan: CGI.escape(self["id"]) }),
    params: params,
    opts: opts
  )
end