Skip to main content

Coupon Object

Overview​

The coupon object contains detailed information about coupons, discount codes, and promotional offers used in e-commerce events, enabling comprehensive promotion tracking, marketing analytics, and discount performance optimization. This object is used within e-commerce events to track coupon usage, discount amounts, promotional effectiveness, and customer savings across the shopping journey.

Each coupon object represents a single discount code or promotional offer with its associated discount value, tax implications, coupon type, and custom properties that enable precise promotion tracking and marketing analytics.

Core Structure​

The coupon object consists of several logical groups of properties:

  • Core Properties - Essential coupon identification and discount value
  • Tax Information - Tax calculations and tax-inclusive discount pricing
  • Coupon Classification - Coupon types and promotional categories
  • Currency Support - Multi-currency discount values and exchange rates

Complete Reference​

coupons[0] object

name string required

info

Coupon name or code.

name: "FREE SHIPPING"

value number recommended

info

Coupon discount value.

value: 123.99

tax_included boolean recommended

info

Whether coupon value includes taxes

tax_included: true

tax_precent string recommended

info

Tax percentage for the coupon

tax_precent: 21

id string

info

Coupon internal identifier.

id: "COUPON_INTERNAL_ID"

type string

info

Coupon type (e.g., "LOYALTY", "SEASONAL", "FIRST_ORDER")

type: "SHIPPING"

currency string required-if-applicable

info

Currency code. Specifies the currency code when it differs from event.currency.

currency: "USD"

exchange_rate number

info

Custom exchange rate for multi-currency. Default has value 1. Specifies when it differs from event.exchange_rate.

exchange_rate: 1

Implementation Examples​

{
  // 10% off discount coupon
  name: "SUMMER10",
  value: 29.99,           // Actual discount amount applied
  tax_included: true,
  tax_percent: 8.25,
  id: "SUMMER10_2024",
  type: "SEASONAL",
  currency: "USD",
  exchange_rate: 1
}

Coupon Types​

The type field categorizes coupons for analytics and campaign management:

Marketing and promotional discount types:

{
  type: "SEASONAL",          // Seasonal promotions (summer, holiday)
  type: "FIRST_ORDER",       // New customer welcome discount
  type: "WELCOME",           // Account registration bonus
  type: "FLASH_SALE",        // Limited-time flash sales
  type: "CLEARANCE"          // Inventory clearance discounts
}

Coupon Usage Examples​

Single Coupon Application​

{
  name: "BLACKFRIDAY2024",
  value: 149.99,
  tax_included: true,
  tax_percent: 8.25,
  id: "BF2024_001",
  type: "SEASONAL"
}

Multiple Coupon Combinations​

[
  {
    name: "NEWCUSTOMER20",
    value: 60.00,
    tax_included: true,
    tax_percent: 8.25,
    id: "NEW20_001",
    type: "FIRST_ORDER"
  },
  {
    name: "FREESHIP50",
    value: 12.99,
    tax_included: true,
    tax_percent: 0,
    id: "FREESHIP_001",
    type: "SHIPPING"
  }
]

Product-Level vs Order-Level Coupons​

// Applied to specific products within product object
products: [
  {
    id: "LAPTOP_001",
    name: "Gaming Laptop",
    price: 999.99,
    coupons: [
      {
        name: "LAPTOP_UPGRADE_100",
        value: 100.00,
        tax_included: true,
        tax_percent: 8.25,
        type: "PRODUCT_SPECIFIC"
      }
    ]
  }
]

Tax Configuration​

Coupon objects support comprehensive tax calculation for accurate discounting:

Tax-Inclusive Discounts​

{
  name: "DISCOUNT_WITH_TAX",
  value: 23.99,           // Total discount including tax
  tax_included: true,     // Tax is included in discount value
  tax_percent: 8.25,      // Tax rate for calculation
  currency: "USD"
}

Tax-Exclusive Discounts​

{
  name: "PRETAX_DISCOUNT",
  value: 20.00,           // Discount before tax calculation
  tax_included: false,    // Tax not included in discount
  tax_percent: 19,        // Tax to be calculated separately
  currency: "EUR"
}

Tax-Free Promotions​

{
  name: "TAX_FREE_PROMO",
  value: 25.00,
  tax_included: true,
  tax_percent: 0,         // No tax on promotional discount
  currency: "USD"
}

Multi-Currency Support​

Coupon discounts support multi-currency transactions with exchange rates:

// USD Base Currency
{
  name: "DISCOUNT_USD",
  value: 25.00,
  currency: "USD",
  exchange_rate: 1
}

// EUR with Exchange Rate
{
  name: "DISCOUNT_EUR",
  value: 22.99,
  currency: "EUR",
  exchange_rate: 1.08      // EUR to USD conversion
}

// Local Currency
{
  name: "DISCOUNT_LOCAL",
  value: 89.99,
  currency: "RON",
  exchange_rate: 0.22      // RON to USD conversion
}

Campaign and Seasonal Examples​

Seasonal Campaigns​

[
  {
    name: "CHRISTMAS_SPECIAL_30",
    value: 89.99,
    tax_included: true,
    tax_percent: 8.25,
    id: "XMAS30_2024",
    type: "SEASONAL"
  },
  {
    name: "HOLIDAY_FREESHIP",
    value: 15.99,
    tax_included: true,
    tax_percent: 0,
    id: "HOLIDAY_SHIP_2024",
    type: "SHIPPING"
  }
]

Customer Lifecycle Campaigns​

[
  {
    name: "WELCOME_FIRST_ORDER_25",
    value: 25.00,
    tax_included: true,
    tax_percent: 8.25,
    id: "WELCOME25_001",
    type: "FIRST_ORDER"
  },
  {
    name: "SIGNUP_BONUS_10",
    value: 10.00,
    tax_included: true,
    tax_percent: 8.25,
    id: "SIGNUP10_001",
    type: "WELCOME"
  }
]

Usage in E-commerce Events​

The coupon object is used in e-commerce events within the coupons array:

Integration Patterns​

Order-Level Coupons​

// Coupons applied to entire order
{
  coupons: [
    {
      name: "TOTAL_ORDER_DISCOUNT",
      value: 50.00,
      tax_included: true,
      tax_percent: 8.25,
      type: "PROMOTIONAL"
    }
  ]
}

Product-Level Coupons​

// Coupons applied to specific products
{
  products: [
    {
      id: "PRODUCT_001",
      coupons: [
        {
          name: "PRODUCT_SPECIAL_20",
          value: 20.00,
          tax_included: true,
          tax_percent: 8.25,
          type: "PRODUCT_SPECIFIC"
        }
      ]
    }
  ]
}

Mixed Coupon Strategy​

// Combination of order and product coupons
{
  // Order-level discount
  coupons: [
    {
      name: "ORDER_WIDE_15OFF",
      value: 45.00,
      type: "PROMOTIONAL"
    }
  ],
  products: [
    {
      id: "SPECIAL_ITEM",
      // Product-specific additional discount
      coupons: [
        {
          name: "ITEM_EXTRA_10",
          value: 10.00,
          type: "PRODUCT_SPECIFIC"
        }
      ]
    }
  ]
}

Best Practices​

Data Quality​

  • Accurate Values - Ensure coupon values reflect actual discount amounts applied
  • Consistent Naming - Use standardized coupon code naming conventions
  • Complete Tax Information - Include accurate tax calculations for discount compliance
  • Currency Consistency - Match coupon currency with order currency when possible

Campaign Management​

  • Clear Type Classification - Use appropriate coupon types for accurate campaign tracking
  • Unique Identifiers - Maintain unique coupon IDs for tracking and analytics
  • Expiration Tracking - Monitor coupon usage and effectiveness over time
  • Segmentation Support - Include relevant data for customer segmentation analysis

Performance Optimization​

  • Essential Data First - Prioritize required fields for fast checkout implementation
  • Campaign Analytics - Track coupon performance and customer response rates
  • Fraud Prevention - Monitor unusual coupon usage patterns
  • ROI Measurement - Calculate promotion effectiveness and customer acquisition costs

Customer Experience​

  • Clear Descriptions - Use descriptive coupon names that explain the benefit
  • Transparent Savings - Display accurate discount amounts including tax implications
  • Stacking Strategy - Define clear rules for multiple coupon combinations
  • Error Handling - Gracefully handle invalid or expired coupon codes