Coupon

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stripe/main/json-schema/stripe-coupon-schema.json",
  "title": "Coupon",
  "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 [subscriptions](https://stripe.com/docs/api#subscriptions), [invoices](https://stripe.com/docs/api#invoices),\n[checkout sessions](https://stripe.com/docs/api/checkout/sessions), [quotes](https://stripe.com/docs/api#quotes), and more. Coupons do not work with conventional one-off [charges](https://stripe.com/docs/api#create_charge) or [payment intents](https://stripe.com/docs/api/payment_intents).",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stripe-coupons-api-openapi.yml#/components/schemas/coupon",
  "properties": {
    "amount_off": {
      "description": "Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.",
      "type": [
        "integer",
        "null"
      ]
    },
    "applies_to": {
      "$ref": "#/$defs/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.",
      "type": [
        "string",
        "null"
      ]
    },
    "currency_options": {
      "additionalProperties": {
        "$ref": "#/$defs/coupon_currency_option"
      },
      "description": "Coupons defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).",
      "type": "object"
    },
    "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",
      "x-stripeBypassValidation": true
    },
    "duration_in_months": {
      "description": "If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.",
      "type": [
        "integer",
        "null"
      ]
    },
    "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.",
      "type": [
        "integer",
        "null"
      ]
    },
    "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.",
      "type": [
        "object",
        "null"
      ]
    },
    "name": {
      "description": "Name of the coupon displayed to customers on for instance invoices or receipts.",
      "maxLength": 5000,
      "type": [
        "string",
        "null"
      ]
    },
    "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 $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.",
      "type": [
        "number",
        "null"
      ]
    },
    "redeem_by": {
      "description": "Date after which the coupon can no longer be redeemed.",
      "format": "unix-time",
      "type": [
        "integer",
        "null"
      ]
    },
    "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"
  ],
  "type": "object",
  "x-expandableFields": [
    "applies_to",
    "currency_options"
  ],
  "x-resourceId": "coupon"
}