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

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.



45
46
47
 
# File 'lib/stripe/resources/coupon.rb', line 45

def amount_off
  @amount_off
end

#applies_to ⇒ Object (readonly)

Attribute for field applies_to



47
48
49
 
# File 'lib/stripe/resources/coupon.rb', line 47

def applies_to
  @applies_to
end

#created ⇒ Object (readonly)

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



49
50
51
 
# File 'lib/stripe/resources/coupon.rb', line 49

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.



51
52
53
 
# File 'lib/stripe/resources/coupon.rb', line 51

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.



53
54
55
 
# File 'lib/stripe/resources/coupon.rb', line 53

def currency_options
  @currency_options
end

#deleted ⇒ Object (readonly)

Always true for a deleted object



55
56
57
 
# File 'lib/stripe/resources/coupon.rb', line 55

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.



57
58
59
 
# File 'lib/stripe/resources/coupon.rb', line 57

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.



59
60
61
 
# File 'lib/stripe/resources/coupon.rb', line 59

def duration_in_months
  @duration_in_months
end

#id ⇒ Object (readonly)

Unique identifier for the object.



61
62
63
 
# File 'lib/stripe/resources/coupon.rb', line 61

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.



63
64
65
 
# File 'lib/stripe/resources/coupon.rb', line 63

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.



65
66
67
 
# File 'lib/stripe/resources/coupon.rb', line 65

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.



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

def metadata
  @metadata
end

#name ⇒ Object (readonly)

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



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

def name
  @name
end

#object ⇒ Object (readonly)

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



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

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.



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

def percent_off
  @percent_off
end

#redeem_by ⇒ Object (readonly)

Date after which the coupon can no longer be redeemed.



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

def redeem_by
  @redeem_by
end

#times_redeemed ⇒ Object (readonly)

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



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

def times_redeemed
  @times_redeemed
end

#valid ⇒ Object (readonly)

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



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

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.



84
85
86
 
# File 'lib/stripe/resources/coupon.rb', line 84

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.



89
90
91
92
93
94
95
96
 
# File 'lib/stripe/resources/coupon.rb', line 89

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 



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

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



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

def self.inner_class_types
  @inner_class_types = { applies_to: AppliesTo, currency_options: CurrencyOptions }
end

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

Returns a list of your coupons.



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

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.



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

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.



99
100
101
102
103
104
105
106
 
# File 'lib/stripe/resources/coupon.rb', line 99

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