# Promotion Code (/en/api-reference/objects/promotion-code)

A Promotion Code is a customer-facing alphanumeric code (for example `SUMMER25`) that maps to a single Coupon. One Coupon can have many Promotion Codes, letting you run different campaigns (email vs. social, customer-specific codes, regional codes, …) against the same underlying discount. Customers enter the code at checkout to redeem the Coupon's discount. Promotion Codes can carry their own restrictions on top of the Coupon — a per-code redemption cap, an expiry date, or a binding to a specific Customer. You receive `promotion_code.created` and `promotion_code.updated` webhook events whenever a code is created or modified.

## Fields

- `id` (string, required) — Unique identifier for this Promotion Code. Always prefixed with `promo_`.
- `object` (string, required) — String identifying the object type. Always `promotion_code` for this resource.
- `createdAt` (string, required) — Created timestamp (ISO 8601)
- `code` (string, required) — The customer-facing code merchants share and customers enter at checkout.
- `active` (boolean, required) — Whether the code can currently be redeemed. Set to `false` to disable a code without deleting it.
- `coupon` ([Coupon](/en/api-reference/objects/coupon), required) — The Coupon this code redeems. Multiple Promotion Codes can map to the same Coupon.
- `customerId` (string) — ID of the specific Customer this code is bound to. When set, only that Customer can redeem the code.
- `maxRedemptions` (number) — Maximum number of times this specific code can be redeemed across all customers. Independent from the parent Coupon's `maxRedemptions`.
- `timesRedeemed` (number, required) — Number of times this code has already been redeemed.
- `expiresAt` (string) — When this code stops being redeemable (ISO 8601). Independent from the parent Coupon's `redeemBy`.
- `restrictions` (object) — Per-code restrictions (e.g. minimum order amount, first-time customers only).
- `metadata` (object) — Custom key/value metadata you attached to the code.
- `merchantId` (string, required) — Merchant ID this Promotion Code belongs to.
- `livemode` (boolean, required) — Whether the Promotion Code exists in live mode (vs. test mode).