Class: Stripe::Coupon

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

Overview

A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions, invoices, checkout sessions, quotes, and more. Coupons do not work with conventional one-off charges or payment intents.

Defined Under Namespace

Classes: AppliesTo, CurrencyOptions, Script, ServicePeriod

Constant Summary collapse

OBJECT_NAME = 
"coupon"

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?, field_encodings, #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

#amount_off ⇒ Object (readonly)

Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.



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

def amount_off
  @amount_off
end

#applies_to ⇒ Object (readonly)

Attribute for field applies_to



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

def applies_to
  @applies_to
end

#created ⇒ Object (readonly)

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



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

def created
  @created
end

#currency ⇒ Object (readonly)

If amount_off has been set, the three-letter ISO code for the currency of the amount to take off.



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

def currency
  @currency
end

#currency_options ⇒ Object (readonly)

Coupons defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.



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

def currency_options
  @currency_options
end

#deleted ⇒ Object (readonly)

Always true for a deleted object



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

def deleted
  @deleted
end

#duration ⇒ Object (readonly)

One of forever, once, or repeating. Describes how long a customer who applies this coupon will get the discount.



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

def duration
  @duration
end

#duration_in_months ⇒ Object (readonly)

If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once.



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

def duration_in_months
  @duration_in_months
end

#id ⇒ Object (readonly)

Unique identifier for the object.



109
110
111
 
# File 'lib/stripe/resources/coupon.rb', line 109

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



111
112
113
 
# File 'lib/stripe/resources/coupon.rb', line 111

def livemode
  @livemode
end

#max_redemptions ⇒ Object (readonly)

Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.



113
114
115
 
# File 'lib/stripe/resources/coupon.rb', line 113

def max_redemptions
  @max_redemptions
end

#metadata ⇒ Object (readonly)

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.



115
116
117
 
# File 'lib/stripe/resources/coupon.rb', line 115

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Name of the coupon displayed to customers on for instance invoices or receipts.



117
118
119
 
# File 'lib/stripe/resources/coupon.rb', line 117

def name
  @name
end

#object ⇒ Object (readonly)

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



119
120
121
 
# File 'lib/stripe/resources/coupon.rb', line 119

def object
  @object
end

#percent_off ⇒ Object (readonly)

Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.



121
122
123
 
# File 'lib/stripe/resources/coupon.rb', line 121

def percent_off
  @percent_off
end

#redeem_by ⇒ Object (readonly)

Date after which the coupon can no longer be redeemed.



123
124
125
 
# File 'lib/stripe/resources/coupon.rb', line 123

def redeem_by
  @redeem_by
end

#script ⇒ Object (readonly)

Configuration of the script used to calculate the discount.



125
126
127
 
# File 'lib/stripe/resources/coupon.rb', line 125

def script
  @script
end

#service_period ⇒ Object (readonly)

Attribute for field service_period



127
128
129
 
# File 'lib/stripe/resources/coupon.rb', line 127

def service_period
  @service_period
end

#times_redeemed ⇒ Object (readonly)

Number of times this coupon has been applied to a customer.



129
130
131
 
# File 'lib/stripe/resources/coupon.rb', line 129

def times_redeemed
  @times_redeemed
end

#type ⇒ Object (readonly)

The type of coupon logic used to calculate the discount.



131
132
133
 
# File 'lib/stripe/resources/coupon.rb', line 131

def type
  @type
end

#valid ⇒ Object (readonly)

Taking account of the above properties, whether this coupon can still be applied to a customer.



133
134
135
 
# File 'lib/stripe/resources/coupon.rb', line 133

def valid
  @valid
end

Class Method Details

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

You can create coupons easily via the coupon management page of the Stripe dashboard. Coupon creation is also accessible via the API if you need to create coupons on the fly.

A coupon has either a percent_off or an amount_off and currency. If you set an amount_off, that amount will be subtracted from any invoice's subtotal. For example, an invoice with a subtotal of 100 will have a final total of 0 if a coupon with an amount_off of 200 is applied to it and an invoice with a subtotal of 300 will have a final total of 100 if a coupon with an amount_off of 200 is applied to it.



138
139
140
 
# File 'lib/stripe/resources/coupon.rb', line 138

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

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

You can delete coupons via the coupon management page of the Stripe dashboard. However, deleting a coupon does not affect any customers who have already applied the coupon; it means that new customers can't redeem the coupon. You can also delete coupons via the API.



143
144
145
146
147
148
149
150
 
# File 'lib/stripe/resources/coupon.rb', line 143

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

.field_remappings ⇒ Object 



186
187
188
 
# File 'lib/stripe/resources/coupon.rb', line 186

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



177
178
179
180
181
182
183
184
 
# File 'lib/stripe/resources/coupon.rb', line 177

def self.inner_class_types
  @inner_class_types = {
    applies_to: AppliesTo,
    currency_options: CurrencyOptions,
    script: Script,
    service_period: ServicePeriod,
  }
end

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

Returns a list of your coupons.



163
164
165
 
# File 'lib/stripe/resources/coupon.rb', line 163

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

.object_name ⇒ Object 



15
16
17
 
# File 'lib/stripe/resources/coupon.rb', line 15

def self.object_name
  "coupon"
end

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

Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.



168
169
170
171
172
173
174
175
 
# File 'lib/stripe/resources/coupon.rb', line 168

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

Instance Method Details

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

You can delete coupons via the coupon management page of the Stripe dashboard. However, deleting a coupon does not affect any customers who have already applied the coupon; it means that new customers can't redeem the coupon. You can also delete coupons via the API.



153
154
155
156
157
158
159
160
 
# File 'lib/stripe/resources/coupon.rb', line 153

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