Holiday Management

Overview

The holiday management system in TanStack Ship provides a comprehensive solution for defining, organizing, and leveraging holidays and special dates throughout your marketing and pricing infrastructure. From major international observances like Christmas and Lunar New Year to region-specific cultural celebrations and custom business dates, the system enables automated promotional scheduling and seasonal pricing adjustments.

As part of the platform, the holiday module integrates with the campaign and offer system for automated promotions, the pricing engine for holiday-specific rates, and the content scheduling system for timed marketing assets. Each holiday stores localized names and descriptions in all supported languages, enabling culturally relevant user experiences across English, Chinese, and German audiences.

Design Flow

The holiday management lifecycle orchestrates automated seasonal promotions from holiday definition through campaign activation and pricing adjustment:

Core Capabilities

Holiday Creation and Management

Holidays can be created and managed through the admin dashboard:

• Multi-Language Naming — Each holiday stores names in all supported locales (EN, ZH, DE), enabling localized display and region-specific campaign targeting
• Flexible Date Ranges — Support for single-day holidays, multi-day events, and recurring annual observances
• Rich Metadata — Optional descriptions in multiple languages, active status toggles, and country/region association
• Lifecycle Management — Full CRUD operations for creating, editing, enabling/disabling, and deleting holidays

Holiday Generator

The built-in holiday generator automates the population of common holidays:

• International Holidays — Christmas, New Year, Valentine's Day, Halloween, and other globally recognized dates
• Regional Observances — Chinese New Year, Mid-Autumn Festival (China); Thanksgiving, Independence Day (US); German Unity Day, Oktoberfest (Germany)
• Cultural Celebrations — Mother's Day, Father's Day, Easter, and other culturally significant dates
• Custom Business Dates — Company anniversaries, product launch dates, and internal marketing milestones

The generator can be triggered from the admin interface to populate holidays for all supported regions in a single operation, with deduplication logic to prevent duplicate entries.

Campaign and Pricing Integration

Holidays serve as triggers for automated marketing and pricing actions:

• Automated Campaign Launch — Campaigns can be configured to activate automatically when a holiday date range begins. For example, a "Spring Festival Special" campaign launches automatically on the first day of Chinese New Year
• Holiday-Specific Discounts — The pricing engine evaluates active holidays during price calculation, enabling special holiday rates without manual intervention
• Seasonal Content Scheduling — Blog posts, landing pages, and email campaigns can be timed to publish around key holidays

Example — Holiday impact on checkout pricing:

Client-side holiday display example:

import { useQuery } from '@tanstack/react-query'

export function ActiveHolidayBanner() {
  const { data } = useQuery({
    queryKey: ['active-holidays'],
    queryFn: () =>
      fetch('/api/holidays/active').then((r) => r.json()) as Promise<
        Array<{ name: string; locale: string; discount: number }>
      >,
  })

  if (!data?.length) return null

  return (
    <div className="rounded-lg bg-gradient-to-r from-amber-50 to-orange-50 border border-amber-200 p-4 text-center">
      {data.map((holiday) => (
        <p key={holiday.locale} className="font-medium text-amber-800">
          🎉 {holiday.name} — {holiday.discount}% off sitewide
        </p>
      ))}
    </div>
  )
}

Design Philosophy

Data-Driven Scheduling

Holidays serve as the central scheduling primitives for the entire marketing automation stack. Rather than hard-coding seasonal promotions into business logic, the system treats holidays as declarative data — administrators define a holiday once with its date range and locale, and every downstream system (campaign engine, pricing calculator, content scheduler) reacts accordingly. This data-driven approach eliminates duplication, ensures consistency across modules, and makes seasonal strategy auditable at a glance. Unlike manually managing holiday promotions through spreadsheets or calendar tools — where dates drift, campaigns miss their window, and localization is an afterthought — declarative holiday data guarantees that every promotional system activates on the correct date with the correct locale, every time.

Localization-First Design

Every holiday stores its name and description in all supported languages (EN, ZH, DE) with graceful English fallback. The system's holiday-service.ts resolves the appropriate localized value based on the current user locale at query time. This ensures that a Chinese user sees "春节" while a German user sees "Chinesisches Neujahr" for the same holiday entity — without duplicating the holiday definition or requiring separate scheduling logic per market.

Separation of Concerns

Holiday definitions are cleanly separated from their consumption: the holiday module owns the data (creation, storage, resolution), while the campaign engine, pricing calculator, and content scheduler own the behavior. This separation means adding a new holiday never requires code changes — only a database entry — and each consuming module can independently decide how to interpret holiday data.

Best Practices

Regional Holiday Coverage

For SaaS platforms serving global audiences, maintain a comprehensive holiday catalog covering all target markets. Focus on holidays that directly impact user behavior — e-commerce platforms should prioritize shopping events (Black Friday, Cyber Monday, Singles' Day), while B2B platforms should note business-culture holidays.

Campaign Pre-Scheduling

Configure campaign schedules to activate before holiday dates rather than on the day itself. Launch a Christmas campaign in early December, not December 25th. Date range support enables this by allowing campaigns to reference holiday start dates with configurable lead-time offsets.

Holiday-Triggered Pricing Strategy

Use holiday-driven pricing sparingly and transparently. Apply holiday discounts through visible coupon codes or promotional banners rather than silently adjusting prices.

Multi-Language Consistency

Maintain consistent holiday naming across all locales. Use the primary English name as the slug to ensure cross-locale referential integrity, while storing localized display names separately.

Frequently Asked Questions

How do I create a new holiday? Navigate to the holidays page in the admin dashboard and click "Add Holiday." Fill in the name in all supported locales, set the date range, optionally add descriptions, and save.

Can holidays recur annually? Yes. The system supports annual recurrence through date range configuration. Recurring holidays automatically appear in active queries each year.

How does the holiday generator work? The generator contains predefined lists of international and regional holidays. When triggered from the admin panel, it creates records for all defined holidays in selected regions, checking for existing entries to avoid duplicates.

Are holidays country-specific? Yes. Each holiday can be associated with one or more country codes. When queried with a specific country, only matching holidays or global holidays are returned.

Can I create holidays with names in only some languages? Yes. The name field supports locale keys for the locales relevant to you, with graceful fallback to English if a locale-specific name is not available.

How does the pricing engine use holiday data? The pricing engine checks for active holidays during checkout. If holiday-specific pricing is configured, the adjustment is applied before finalizing the total.

What reporting is available for holiday-driven promotions? The attribution analytics dashboard can filter conversion data by holiday periods, allowing you to measure the impact of holiday-specific campaigns on revenue and user acquisition.

Configuration

Holidays are managed through the admin interface. No additional environment variables are required for basic functionality.

For custom holiday definitions, extend the predefined holiday lists as needed. The holiday resolution works with caching to minimize database load.

Integration Points

The holiday management system integrates with these platform modules:

• Campaigns & Offers — Holidays trigger automated campaign launches and offer activations
• Pricing Engine — Holiday-specific discount rates are evaluated during checkout
• Content Scheduling — Blog posts, landing pages, and email content are timed around key holidays
• Localization — Holiday names and descriptions are stored in all supported locales
• Attribution Analytics — Conversion data can be segmented by holiday periods