Coupon

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/checkoutpage-com/json-schema/checkoutpage-com-coupon-schema.json",
  "title": "Coupon",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/checkoutpage-com-coupons-api-openapi.yml#/components/schemas/Coupon",
  "properties": {
    "amountOff": {
      "description": "Flat discount amount in the specified `currency`. Only set if `percentOff` is not used.",
      "type": [
        "number",
        "null"
      ]
    },
    "appliesToSetupFee": {
      "description": "When enabled, applies this coupon discount to the setup fee.",
      "type": "boolean"
    },
    "appliesToTicketFees": {
      "description": "When enabled, applies this coupon discount to ticket-level fees on event pages as well as the ticket prices.",
      "type": "boolean"
    },
    "code": {
      "description": "The coupon code a customer enters.",
      "type": "string"
    },
    "createdAt": {
      "format": "date-time",
      "type": "string"
    },
    "currency": {
      "description": "Three-letter ISO code for the `currency` (required when `amountOff` is set). Examples: usd, eur, gbp.",
      "type": "string"
    },
    "deleted": {
      "description": "If true, this coupon will be soft deleted. It is no longer usable but data is retained.",
      "type": "boolean"
    },
    "duration": {
      "description": "How long the discount applies: once (single payment), repeating (specified months), or forever (all future payments).",
      "enum": [
        "once",
        "repeating",
        "forever"
      ],
      "type": "string"
    },
    "durationInMonths": {
      "description": "If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is forever or once.",
      "type": "number"
    },
    "id": {
      "description": "Unique identifier for the object.",
      "type": "string"
    },
    "label": {
      "description": "Internal name for the coupon.",
      "type": "string"
    },
    "maxRedemptions": {
      "description": "Maximum number of times this coupon can be redeemed globally. A single customer may redeem it multiple times.",
      "type": "number"
    },
    "pageIds": {
      "deprecated": true,
      "description": "Deprecated: use `rules`. The checkout pages and events this coupon can be used on, each discounting the whole order. Accepted only without `rules`. In responses, the pages named by `rules`.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "percentOff": {
      "description": "Percentage discount (0-100) applied to payments using this coupon. Example: 50 applies 50% off ($100 payment becomes $50). Only set if `amountOff` is not used.",
      "type": [
        "number",
        "null"
      ]
    },
    "redeemBy": {
      "description": "The ISO datetime that this coupon must be used before.",
      "format": "date-time",
      "type": "string"
    },
    "rules": {
      "description": "Where the coupon works and what it discounts, one rule per page. A coupon works on a page when any of its rules names that page, and on each page the rules are combined with OR (an event cannot mix `tickets` and `ticketsAndAddOns` rules). Omit `rules` (and `pageIds`), or send an empty list, for a coupon that discounts the whole order on every checkout page and event.",
      "items": {
        "properties": {
          "appliesTo": {
            "description": "What the coupon discounts on the page. Checkout pages: `wholeOrder` (the main product at any price and every order bump), `prices` (applies when the customer buys one of `priceIds`, discounting that price only), `pricesAndBumps` (applies only when the customer buys one of `priceIds` and one of `bumpProductIds`, discounting both). Events: `wholeOrder` (every ticket and add-on), `tickets` (applies when the customer buys one of `ticketTypeIds`, discounting those tickets only), `ticketsAndAddOns` (applies only when the customer buys one of `ticketTypeIds` and one of `bumpProductIds`, discounting both). Setup fees and ticket fees follow `appliesToSetupFee` and `appliesToTicketFees`.",
            "enum": [
              "wholeOrder",
              "prices",
              "pricesAndBumps",
              "tickets",
              "ticketsAndAddOns"
            ],
            "type": "string"
          },
          "bumpProductIds": {
            "description": "Products of order bumps (checkout pages) or add-ons (events) on the page, only for `pricesAndBumps` and `ticketsAndAddOns`. An empty list or no list means every bump or add-on on the page, including ones added later; the coupon still needs one of them bought.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "pageId": {
            "description": "The checkout page or event this rule applies to.",
            "type": "string"
          },
          "priceIds": {
            "description": "Prices of the page's main product, only for `prices` and `pricesAndBumps`. An empty list or no list means every price of the main product, including prices added later. These are the `id`s of a product's `prices`, not Stripe price ids.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "ticketTypeIds": {
            "description": "Ticket types of the event, only for `tickets` and `ticketsAndAddOns`. An empty list or no list means every ticket type of the event, including ticket types added later.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "pageId",
          "appliesTo",
          "priceIds",
          "ticketTypeIds",
          "bumpProductIds"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "sellerId": {
      "type": "string"
    },
    "stripeCouponId": {
      "description": "The unique identifier of the stripe coupon that was created with this coupon.",
      "type": "string"
    },
    "ticketTypeIds": {
      "deprecated": true,
      "description": "Deprecated: use `rules`. Ticket types of events in `pageIds`: on such an event the coupon discounts only those tickets. Accepted only without `rules`. In responses, every ticket type named by `rules`.",
      "items": {
        "allOf": [
          {
            "$ref": "#/$defs/UniqueIdentifier"
          },
          {
            "description": "Unique identifier. Must be in BSON ObjectId format."
          }
        ]
      },
      "type": "array"
    },
    "timesRedeemed": {
      "description": "The number of times this coupon has been redeemed.",
      "type": "number"
    },
    "updatedAt": {
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "id",
    "label",
    "code",
    "duration",
    "timesRedeemed",
    "deleted",
    "sellerId",
    "rules",
    "createdAt",
    "updatedAt"
  ],
  "type": "object",
  "$defs": {
    "UniqueIdentifier": {
      "description": "Unique identifier for the ticket.",
      "pattern": "^[0-9a-fA-F]{24}$",
      "type": "string"
    }
  }
}