Skip to main content

Coupon Object

Overview​

The coupon object represents a single discount code or promotional offer applied to an order or product. It captures the discount value, tax implications, and coupon classification for promotion tracking and marketing analytics.

Coupons can be applied at two levels:

  • Order-level — in the top-level coupons array, applied to the entire order
  • Product-level — inside a product's coupons array, applied to a specific product

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_percent number recommended

info

Tax percentage for the coupon

tax_percent: 21

id string

info

Coupon internal identifier.

id: "COUPON_INTERNAL_ID"

type string

info

Coupon type. Free-form string, use consistent naming (e.g. "LOYALTY", "SEASONAL", "FIRST_ORDER", "SHIPPING").

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

Examples​

{
  "name": "SUMMER10",
  "value": 29.99,
  "tax_included": true,
  "tax_percent": 19,
  "id": "SUMMER10_2024",
  "type": "SEASONAL",
  "currency": "EUR",
  "exchange_rate": 1
}

Order-Level vs Product-Level​

Order-Level Coupons​

Applied to the entire order in the top-level coupons array:

{
  "event": { "name": "checkout_completed", "id": "ORD_123" },
  "coupons": [
    {
      "name": "ORDER_WIDE_15OFF",
      "value": 45.00,
      "tax_included": true,
      "tax_percent": 19,
      "type": "PROMOTIONAL"
    }
  ]
}

Product-Level Coupons​

Applied to a specific product inside the product's coupons array:

{
  "products": [
    {
      "id": "LAPTOP_001",
      "name": "Gaming Laptop",
      "price": 999.99,
      "coupons": [
        {
          "name": "LAPTOP_DEAL",
          "value": 100.00,
          "tax_included": true,
          "tax_percent": 19,
          "type": "PRODUCT_SPECIFIC"
        }
      ]
    }
  ]
}

Best Practices​

  • Accurate values — ensure coupon values reflect the actual discount amount applied, not the coupon's potential value
  • Consistent naming — use standardized coupon code naming conventions
  • Tax information — include accurate tax calculations; if tax_percent is not provided, the default from your account configuration is used
  • Currency — only specify currency and exchange_rate when the coupon's currency differs from the event currency
  • Type classification — use consistent type values for campaign analytics (e.g. "SEASONAL", "LOYALTY", "FIRST_ORDER", "SHIPPING", "PROMOTIONAL")