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

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.



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

def amount_off
  @amount_off
end

#applies_to ⇒ Object (readonly)

Attribute for field applies_to



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

def applies_to
  @applies_to
end

#created ⇒ Object (readonly)

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



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

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.



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

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.



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

def currency_options
  @currency_options
end

#deleted ⇒ Object (readonly)

Always true for a deleted object



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

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.



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

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.



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

def duration_in_months
  @duration_in_months
end

#id ⇒ Object (readonly)

Unique identifier for the object.



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

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.



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

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.



82
83
84
 
# File 'lib/stripe/resources/coupon.rb', line 82

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.



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

def metadata
  @metadata
end

#name ⇒ Object (readonly)

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



86
87
88
 
# File 'lib/stripe/resources/coupon.rb', line 86

def name
  @name
end

#object ⇒ Object (readonly)

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



88
89
90
 
# File 'lib/stripe/resources/coupon.rb', line 88

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.



90
91
92
 
# File 'lib/stripe/resources/coupon.rb', line 90

def percent_off
  @percent_off
end

#redeem_by ⇒ Object (readonly)

Date after which the coupon can no longer be redeemed.



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

def redeem_by
  @redeem_by
end

#script ⇒ Object (readonly)

Configuration of the script used to calculate the discount.



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

def script
  @script
end

#times_redeemed ⇒ Object (readonly)

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



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

def times_redeemed
  @times_redeemed
end

#type ⇒ Object (readonly)

One of amount_off, percent_off, or script. Describes the type of coupon logic used to calculate the discount.



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

def type
  @type
end

#valid ⇒ Object (readonly)

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



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

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.



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

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.



110
111
112
113
114
115
116
117
 
# File 'lib/stripe/resources/coupon.rb', line 110

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 



152
153
154
 
# File 'lib/stripe/resources/coupon.rb', line 152

def self.field_remappings
  @field_remappings = {}
end

.inner_class_types ⇒ Object 



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

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

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

Returns a list of your coupons.



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

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.



135
136
137
138
139
140
141
142
 
# File 'lib/stripe/resources/coupon.rb', line 135

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.



120
121
122
123
124
125
126
127
 
# File 'lib/stripe/resources/coupon.rb', line 120

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