{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-coupon-create-schema.json",
  "title": "CouponCreate",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/recurly-coupon-api-openapi.yml#/components/schemas/CouponCreate",
  "allOf": [
    {
      "$ref": "#/$defs/CouponUpdate"
    },
    {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "title": "Coupon code",
          "description": "The code the customer enters to redeem the coupon."
        },
        "discount_type": {
          "title": "Discount type",
          "description": "The type of discount provided by the coupon (how the amount discounted is calculated)",
          "$ref": "#/$defs/DiscountTypeEnum"
        },
        "discount_percent": {
          "type": "integer",
          "title": "Discount percent",
          "description": "The percent of the price discounted by the coupon.  Required if `discount_type` is `percent`."
        },
        "free_trial_unit": {
          "title": "Free trial unit",
          "description": "Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for. Required if `discount_type` is `free_trial`. Use `billing_period` to grant a free trial for a number of billing cycles.",
          "$ref": "#/$defs/FreeTrialUnitEnum"
        },
        "free_trial_amount": {
          "type": "integer",
          "title": "Free trial amount",
          "description": "Sets the duration of time the `free_trial_unit` is for. Required if `discount_type` is `free_trial`.",
          "minimum": 1,
          "maximum": 9999
        },
        "currencies": {
          "title": "Currencies",
          "description": "Fixed discount currencies by currency. Required if the coupon type is `fixed`. This parameter should contain the coupon discount values",
          "type": "array",
          "items": {
            "$ref": "#/$defs/CouponPricing"
          }
        },
        "applies_to_non_plan_charges": {
          "type": "boolean",
          "title": "Applied to all non-plan charges?",
          "description": "The coupon is valid for one-time, non-plan charges if true.",
          "default": false
        },
        "applies_to_all_plans": {
          "type": "boolean",
          "title": "Applies to all plans?",
          "description": "The coupon is valid for all plans if true. If false then `plans` will list the applicable plans.",
          "default": true
        },
        "applies_to_all_items": {
          "type": "boolean",
          "title": "Applies to all items?",
          "description": "To apply coupon to Items in your Catalog, include a list\nof `item_codes` in the request that the coupon will apply to. Or set value\nto true to apply to all Items in your Catalog. The following values\nare not permitted when `applies_to_all_items` is included: `free_trial_amount`\nand `free_trial_unit`.\n",
          "default": false
        },
        "plan_codes": {
          "type": "array",
          "title": "Plan codes",
          "description": "List of plan codes to which this coupon applies. Required\nif `applies_to_all_plans` is false. Overrides `applies_to_all_plans`\nwhen `applies_to_all_plans` is true.\n",
          "items": {
            "type": "string"
          }
        },
        "item_codes": {
          "type": "array",
          "title": "Item codes",
          "description": "List of item codes to which this coupon applies. Sending\n`item_codes` is only permitted when `applies_to_all_items` is set to false.\nThe following values are not permitted when `item_codes` is included:\n`free_trial_amount` and `free_trial_unit`.\n",
          "items": {
            "type": "string"
          }
        },
        "duration": {
          "title": "Duration",
          "description": "This field does not apply when the discount_type is `free_trial`.\n- \"single_use\" coupons applies to the first invoice only.\n- \"temporal\" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.\n- \"forever\" coupons will apply to invoices forever.\n",
          "default": "forever",
          "$ref": "#/$defs/CouponDurationEnum"
        },
        "temporal_amount": {
          "type": "integer",
          "title": "Temporal amount",
          "description": "If `duration` is \"temporal\" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. When `temporal_unit` is \"billing_period\", this is the number of complete billing cycles."
        },
        "temporal_unit": {
          "title": "Temporal unit",
          "description": "If `duration` is \"temporal\" than `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for. Use \"billing_period\" to apply the coupon for a fixed number of billing cycles. Requires `redemption_resource=subscription`. Not compatible with `discount_type=free_trial`; use `free_trial_unit=billing_period` and `free_trial_amount` instead.",
          "$ref": "#/$defs/TemporalUnitEnum"
        },
        "coupon_type": {
          "title": "Coupon type",
          "description": "Whether the coupon is \"single_code\" or \"bulk\". Bulk coupons will require a `unique_code_template` and will generate unique codes through the `/generate` endpoint.",
          "$ref": "#/$defs/CouponTypeEnum"
        },
        "unique_code_template": {
          "type": "string",
          "title": "Unique code template",
          "description": "On a bulk coupon, the template from which unique coupon codes are generated.\n- You must start the template with your coupon_code wrapped in single quotes.\n- Outside of single quotes, use a 9 for a character that you want to be a random number.\n- Outside of single quotes, use an \"x\" for a character that you want to be a random letter.\n- Outside of single quotes, use an * for a character that you want to be a random number or letter.\n- Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.\nFor example: \"'abc-'****'-def'\"\n"
        },
        "redemption_resource": {
          "title": "Redemption resource",
          "description": "Whether the discount is for all eligible charges on the account, or only a specific subscription.",
          "default": "account",
          "$ref": "#/$defs/RedemptionResourceEnum"
        }
      },
      "required": [
        "code",
        "discount_type",
        "name"
      ]
    }
  ],
  "$defs": {
    "CouponDurationEnum": {
      "type": "string",
      "enum": [
        "forever",
        "single_use",
        "temporal",
        "billing_periods"
      ]
    },
    "CouponPricing": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "description": "3-letter ISO 4217 currency code."
        },
        "discount": {
          "type": "number",
          "format": "float",
          "description": "The fixed discount (in dollars) for the corresponding currency."
        }
      }
    },
    "CouponRedeemByIntervalUnitEnum": {
      "type": "string",
      "title": "Redeem by interval unit",
      "description": "Unit of the relative redemption window. Bulk coupons only.",
      "enum": [
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "CouponTypeEnum": {
      "type": "string",
      "enum": [
        "bulk",
        "single_code"
      ]
    },
    "CouponUpdate": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "The internal name for the coupon."
        },
        "max_redemptions": {
          "type": "integer",
          "title": "Max redemptions",
          "description": "A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions."
        },
        "max_redemptions_per_account": {
          "type": "integer",
          "title": "Max redemptions per account",
          "description": "Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign."
        },
        "hosted_description": {
          "type": "string",
          "title": "Hosted Payment Pages description",
          "description": "This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page."
        },
        "invoice_description": {
          "type": "string",
          "title": "Invoice description",
          "description": "Description of the coupon on the invoice.",
          "maxLength": 255
        },
        "redeem_by_date": {
          "type": "string",
          "title": "Redeem by",
          "description": "The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. Mutually exclusive with redeem_by_interval_unit/redeem_by_interval_amount."
        },
        "redeem_by_interval_unit": {
          "title": "Redeem by interval unit",
          "description": "Unit of the relative redemption window. Must be paired with redeem_by_interval_amount. Mutually exclusive with redeem_by_date. Bulk coupons only.",
          "$ref": "#/$defs/CouponRedeemByIntervalUnitEnum"
        },
        "redeem_by_interval_amount": {
          "type": "integer",
          "title": "Redeem by interval amount",
          "description": "Quantity of redeem_by_interval_unit. Must be paired with redeem_by_interval_unit.",
          "minimum": 1
        }
      }
    },
    "DiscountTypeEnum": {
      "type": "string",
      "enum": [
        "fixed",
        "free_trial",
        "percent"
      ]
    },
    "FreeTrialUnitEnum": {
      "type": "string",
      "enum": [
        "day",
        "month",
        "week",
        "billing_period"
      ]
    },
    "RedemptionResourceEnum": {
      "type": "string",
      "enum": [
        "account",
        "subscription"
      ]
    },
    "TemporalUnitEnum": {
      "type": "string",
      "description": "The temporal unit for the coupon's duration. Used with temporal_amount to define how long the coupon applies. When temporal_unit is billing_period, the coupon applies for temporal_amount complete billing cycles rather than a fixed calendar duration. billing_period requires redemption_resource=subscription.",
      "enum": [
        "day",
        "month",
        "week",
        "year",
        "billing_period"
      ]
    }
  }
}