# Coupon

object type

A Coupon — the CODE-GATED entry to the discount engines: a normalized code (trim+UPPERCASE, stored normalized-only, IMMUTABLE at birth — re-code = a new coupon) that either UNLOCKS a couponGated Promotion (trigger flavor — the reduction is source=promo at position 3) or CARRIES its own simple effect (discount flavor — source=coupon at position 2, BEFORE promotions). Attach to an OPEN order via applyOrderCoupon (HARD 1 coupon/order — the strict default); redemption counts per ORDER in the place transaction — a capped-out coupon refuses CONFLICT/COUPON_EXHAUSTED. NAMED deferrals: CouponBatch (unique single-use child codes) · per-customer caps.

## Fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (CP-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `Coupon` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: active \| inactive \| doomed. |
| `parentId` | [ID](/types/#scalars) `ID!` | The parent org group; for a Coupon parentId === rootId. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/RefCaption/) `[RefCaption!]!` | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
| `flavor` | [CouponFlavor](/types/CouponFlavor/) `CouponFlavor!` | The canned flavor (SPEC_REGISTRY row 106) — IMMUTABLE at birth. |
| `code` | [String](/types/#scalars) `String!` | No further notes. |
| `promotionId` | [ID](/types/#scalars) | trigger flavor ONLY: the unlocked couponGated Promotion (same-tenant + ACTIVE at create) — IMMUTABLE (re-point = a new coupon). |
| `effect` | [CouponEffect](/types/CouponEffect/) | discount flavor ONLY: the carried effect — wholesale-replace on edit (refused on trigger, the cross-flavor gate). |
| `startAt` | [String](/types/#scalars) `String!` | The half-open window start (kit-stamped NOW when omitted at create). |
| `endAt` | [String](/types/#scalars) | The half-open window end — ABSENT = evergreen; out-of-window redemption refuses CONFLICT/COUPON_EXPIRED. |
| `totalUsesCap` | [Int](/types/#scalars) | Total-use cap. |

## Used by

- [coupon](/reference/coupon/coupon/)
- [coupons](/reference/coupon/coupons/)
- [createCoupon](/reference/coupon/createCoupon/)
- [deactivateCoupon](/reference/coupon/deactivateCoupon/)
- [doomCoupon](/reference/coupon/doomCoupon/)
- [reactivateCoupon](/reference/coupon/reactivateCoupon/)
- [updateCoupon](/reference/coupon/updateCoupon/)