Promotion Code — XPay docs

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.

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.

id*string

Unique identifier for this Promotion Code. Always prefixed with promo_.

object*string

String identifying the object type. Always promotion_code for this resource.

createdAt*string

Created timestamp (ISO 8601)

code*string

The customer-facing code merchants share and customers enter at checkout.

active*boolean

Whether the code can currently be redeemed. Set to false to disable a code without deleting it.

coupon*

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

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?

Per-code restrictions (e.g. minimum order amount, first-time customers only).

metadata?

Custom key/value metadata you attached to the code.

merchantId*string

Merchant ID this Promotion Code belongs to.

livemode*boolean

Whether the Promotion Code exists in live mode (vs. test mode).

{
  "id": "promo_abc123",
  "object": "promotion_code",
  "createdAt": "string",
  "code": "SUMMER25",
  "active": true,
  "coupon": {
    "id": "string",
    "object": "coupon",
    "createdAt": "string",
    "discountType": "percentage",
    "percentOff": 0,
    "amountOff": 0,
    "currency": "EGP",
    "duration": "once",
    "durationInMonths": 0,
    "name": "string",
    "maxDiscountAmount": 0,
    "minValue": 0,
    "maxRedemptions": 0,
    "customerMaxRedemptions": 0,
    "timesRedeemed": 0,
    "redeemBy": "string",
    "valid": true,
    "active": true,
    "appliesToProductIds": [
      "string"
    ],
    "metadata": {},
    "merchantId": "string",
    "livemode": true
  },
  "customerId": "cus_abc123",
  "maxRedemptions": 100,
  "timesRedeemed": 0,
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "restrictions": {},
  "metadata": {},
  "merchantId": "string",
  "livemode": true
}