# coupon

From **Stripe API**.

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 [invoices](https://stripe.com/docs/api#invoices) or
[orders](https://stripe.com/docs/api#create_order_legacy-coupon). Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge).

- Type: `object`

## Properties

### `amount_off`

- Required: false
- Type: `integer`
- Nullable: true

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

### `applies_to`

- Required: false
- Type: `object`

### `created`

- Required: true
- Type: `integer`
- Format: `unix-time`

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

### `currency`

- Required: false
- Type: `string`
- Nullable: true

If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.

### `duration`

- Required: true
- Type: `string`
- Allowed values: `"forever"`, `"once"`, `"repeating"`

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

### `duration_in_months`

- Required: false
- Type: `integer`
- Nullable: true

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

### `id`

- Required: true
- Type: `string`
- maxLength: `5000`

Unique identifier for the object.

### `livemode`

- Required: true
- Type: `boolean`

Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.

### `max_redemptions`

- Required: false
- Type: `integer`
- Nullable: true

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

### `metadata`

- Required: false
- Type: `object`
- Nullable: true

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

### `name`

- Required: false
- Type: `string`
- Nullable: true
- maxLength: `5000`

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

### `object`

- Required: true
- Type: `string`
- Allowed values: `"coupon"`

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

### `percent_off`

- Required: false
- Type: `number`
- Nullable: true

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 %s100 invoice %s50 instead.

### `redeem_by`

- Required: false
- Type: `integer`
- Format: `unix-time`
- Nullable: true

Date after which the coupon can no longer be redeemed.

### `times_redeemed`

- Required: true
- Type: `integer`

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

### `valid`

- Required: true
- Type: `boolean`

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

## JSON Schema

```json
{"description":"A coupon contains information about a percent-off or amount-off discount you\nmight want to apply to a customer. Coupons may be applied to [invoices](https://stripe.com/docs/api#invoices) or\n[orders](https://stripe.com/docs/api#create_order_legacy-coupon). Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge).","properties":{"amount_off":{"description":"Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.","nullable":true,"type":"integer"},"applies_to":{"$ref":"#/components/schemas/coupon_applies_to"},"created":{"description":"Time at which the object was created. Measured in seconds since the Unix epoch.","format":"unix-time","type":"integer"},"currency":{"description":"If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.","nullable":true,"type":"string"},"duration":{"description":"One of `forever`, `once`, and `repeating`. Describes how long a customer who applies this coupon will get the discount.","enum":["forever","once","repeating"],"type":"string"},"duration_in_months":{"description":"If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.","nullable":true,"type":"integer"},"id":{"description":"Unique identifier for the object.","maxLength":5000,"type":"string"},"livemode":{"description":"Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.","type":"boolean"},"max_redemptions":{"description":"Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.","nullable":true,"type":"integer"},"metadata":{"additionalProperties":{"maxLength":500,"type":"string"},"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.","nullable":true,"type":"object"},"name":{"description":"Name of the coupon displayed to customers on for instance invoices or receipts.","maxLength":5000,"nullable":true,"type":"string"},"object":{"description":"String representing the object's type. Objects of the same type share the same value.","enum":["coupon"],"type":"string"},"percent_off":{"description":"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 %s100 invoice %s50 instead.","nullable":true,"type":"number"},"redeem_by":{"description":"Date after which the coupon can no longer be redeemed.","format":"unix-time","nullable":true,"type":"integer"},"times_redeemed":{"description":"Number of times this coupon has been applied to a customer.","type":"integer"},"valid":{"description":"Taking account of the above properties, whether this coupon can still be applied to a customer.","type":"boolean"}},"required":["created","duration","id","livemode","object","times_redeemed","valid"],"title":"Coupon","type":"object","x-expandableFields":["applies_to"],"x-resourceId":"coupon"}
```