Coupon Management

Source: internal/api/v1/store/Controllers/coupon.js

Overview

The Coupon controller manages connected account coupon operations including creation, listing, retrieval, updates, and soft deletion. Coupons provide discounts for products and must validate against DashClicks application fee requirements when applied to platform products.

Key Capabilities

• Create coupons with fixed or percentage discounts
• Apply to specific products or all products
• Set expiration dates and redemption limits
• Validate discount amounts against application fees
• Soft delete coupons (mark as deleted instead of permanent removal)

---

MongoDB Collections

Collection	Operations	Purpose
_store.coupons	CRUD	Coupon storage and tracking
_store.products	Read	Product validation, application fee calculation
_store.prices	Read	Price reference lookup for fee calculation

---

Service Methods

newCoupon

Creates a new coupon in Stripe and MongoDB with product application and fee validation.

Authorization: Requires payments_enabled = true

Request Body:

{
  name: string,
  code: string,
  active: boolean,
  expiration: date,                    // Date string
  discount: {
    type: 'fixed' | 'percentage',
    amount: number                      // Cents for fixed, percentage for percent
  },
  duration: {
    type: 'once' | 'repeating' | 'forever',
    length: number                      // Months (if type = 'repeating')
  },
  max_redemptions: number,              // Optional: global limit
  max_redemptions_per_customer: number, // Optional: per-customer limit
  products: [ObjectId]                  // Optional: product IDs to apply to
}

Response: Created coupon object

Business Logic:

1. Validate payments enabled
2. Verify product IDs (if provided) belong to connected account
3. Calculate discount amounts for DashClicks products
4. Validate discounts don't exceed application fee thresholds
5. Create coupon in Stripe
6. Save to MongoDB

---

getCoupons

Lists all coupons for the connected account with pagination.

Authorization: Requires payments_enabled = true

Query Parameters:

{
  page: number,
  limit: number
}

Response: Paginated coupon list with populated products and account business info

---

getCoupon

Retrieves a single coupon by MongoDB _id.

Authorization: Requires payments_enabled = true

Response: Single coupon with populated products and account

---

updateCoupon

Updates a coupon's name, active status, or per-customer redemption limit.

Authorization: Requires payments_enabled = true

Request Body:

{
  name: string,              // Optional
  active: boolean,           // Optional
  max_redemptions_per_customer: number  // Optional
}

Response: Updated coupon object

Limitations: Cannot update discount amount, duration, or applied products after creation

---

deleteCoupon

Soft deletes a coupon (marks as deleted, doesn't actually remove from Stripe/MongoDB).

Authorization: Requires payments_enabled = true

Response:

{
  success: true,
  message: "SUCCESS",
  data: {
    id: "coupon_id",
    deleted: true
  }
}

---

Discount Validation Logic

Application Fee Calculation

For DashClicks products (platform_type = 'default'), coupons must not reduce price below application fee:

// For each price in each product
const discountAmount =
  req.body.discount.type === 'fixed'
    ? req.body.discount.amount
    : price.unit_amount * (req.body.discount.amount / 100);

const platformsPortion = price.reference_price.unit_amount;
const feePercentage =
  price.reference_price.type === 'one-time'
    ? process.env.ADDITIONAL_APP_FEE_PERCENTAGE
    : process.env.ADDITIONAL_APP_FEE_SUBSCRIPTION_PERCENTAGE;

const totalPlatformFee =
  platformsPortion +
  Math.floor(platformsPortion * feePercentage) +
  parseInt(process.env.ADDITIONAL_APP_FEE_CENTS);

if (price.unit_amount - discountAmount < totalPlatformFee) {
  throw new Error('INVALID_DISCOUNT_AMOUNT');
}

Validation ensures: price - discount >= reference_price + (reference_price * fee%) + fee_cents

---

Edge Cases

• Products must belong to authenticated account's connected account
• DashClicks products validated against application fee minimums
• Coupons soft deleted (deleted flag set to true)
• Metadata stores code and active status
• All monetary amounts in cents

---

Related Documentation

• Promo Codes - Platform-wide promotion codes
• Product Management - Product catalog
• Subscriptions - Coupon application