type: object
description: |
    A coupon — a short-circuit around the payment system. Redeeming a coupon
    produces an `Entitlement` for either an entire entitlement class or a
    specific `bigMediaId`. Mirrors `Schemas.Coupon` (api/src/Schemas.ts).

    Coupons are not credits — they don't carry monetary value, just the right to
    skip checkout for a particular product.
required: [id, code, entitlementClass]
properties:
    id: { type: string }
    createdAt: { type: string, format: date-time }
    code:
        type: string
        description: Public code customers type in to redeem. Unique. Auto-generated when not supplied.
    entitlementClass:
        type: string
        description: General entitlement class the coupon redeems for (`TWO_DAY_RENTAL`, `OWNERSHIP`, etc.).
    bigMediaId:
        type: [string, "null"]
        description: |
            If set, restricts the coupon to a single media product. Overrides the
            broader `entitlementClass`-based eligibility.
    activationTimestamp:
        type: [string, "null"]
        format: date-time
        description: When the coupon was redeemed. Null while unused.
    expirationTimestamp:
        type: [string, "null"]
        format: date-time
        description: After this date the coupon can no longer be redeemed.
    entitlementId:
        type: [string, "null"]
        description: The `Entitlement` that was created on redemption. Null while unused.
example:
    id: "cpn_01HZC12345ABC678DEF90GHJKM"
    createdAt: "2026-04-22T10:14:00.000Z"
    code: "BIGSCREEN-PROMO-2026"
    entitlementClass: "TWO_DAY_RENTAL"
    bigMediaId: null
    activationTimestamp: null
    expirationTimestamp: "2026-12-31T23:59:59.000Z"
    entitlementId: null
