Attributes

• idstring

  Unique identifier for the object.

• amount_offnullable integer

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

• currencynullable enum

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

• durationenum

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

  Possible enum values

  forever Applies to all charges from a subscription with this coupon applied.

  once Applies to the first charge from a subscription with this coupon applied.

  repeating Applies to charges in the first duration_in_months months from a subscription with this coupon applied.

• duration_in_monthsnullable integer

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

• metadatanullable object

  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.

• namenullable string

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

• percent_offnullable float

  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 $100 invoice $50 instead.

More attributes

Expand all

• objectstring

• applies_tonullable objectExpandable

• createdtimestamp

• currency_optionsnullable objectExpandable

• livemodeboolean

• max_redemptionsnullable integer

• redeem_bynullable timestamp

• times_redeemedinteger

• validboolean

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 JPY will have a final total of 0 JPY if a coupon with an amount_off of 200 is applied to it and an invoice with a subtotal of 300 JPY will have a final total of 100 JPY if a coupon with an amount_off of 200 is applied to it.

Parameters

• amount_offinteger

  A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).

• currencyenum

  Three-letter ISO code for the currency of the amount_off parameter (required if amount_off is passed).

• durationenum

  Specifies how long the discount will be in effect if used on a subscription. Defaults to once.

  Possible enum values

  forever Applies to all charges from a subscription with this coupon applied.

  once Applies to the first charge from a subscription with this coupon applied.

  repeating Applies to charges in the first duration_in_months months from a subscription with this coupon applied.

• duration_in_monthsinteger

  Required only if duration is repeating, in which case it must be a positive integer that specifies the number of months the discount will be in effect.

• metadataobject

  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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• namestring

  Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the id is shown if name is not set.

• percent_offfloat

  A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).

More parameters

Expand all

• applies_toobject

• currency_optionsobject

• idstring

• max_redemptionsinteger

• redeem_bytimestamp

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

Parameters

• metadataobject

  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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

• namestring

  Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the id is shown if name is not set.

More parameters

Expand all

• currency_optionsobject

Retrieves the coupon with the given ID.

Parameters

No parameters.

Returns a list of your coupons.

Parameters

No parameters.

More parameters

Expand all

• createdobject

• ending_beforestring

• limitinteger

• starting_afterstring