Add New Credit Card to CouponCycle

This skill guides you through adding a new credit card to the application's predefined card catalog.

When to Use

• User asks to add a new credit card to the system
• User wants to create a card template with benefits
• User needs to download a card image
• Adding support for a new card type

Workflow

Step 1: Gather Card Information

Before adding a card, collect this information:

1. Card Name (exact official name)
2. Issuer (American Express, Chase, Citi, Capital One, etc.)
3. Annual Fee
4. Cyclical Benefits (monthly/quarterly/yearly credits)

Tip: Research benefits at US Credit Card Guide

Step 2: Download Card Image

Run the image download script:

bash
1# Search Google Images for the card
2node scripts/download-card-image.js --name "Card Name" --list
3
4# Download from best result
5node scripts/download-card-image.js --name "Card Name"
6
7# Or use UseYourCredits.com as source (if available)
8node scripts/download-card-image.js --name "Card Name" --source useyourcredits
9
10# Or download from a specific URL
11node scripts/download-card-image.js --name "Card Name" --url "https://..."

Image Location: public/images/cards/{slugified-card-name}.png

Step 3: Update Seed File

Edit prisma/seed.ts and add the card to the predefinedCardsData array:

typescript
1{
2  name: 'Card Name',
3  issuer: 'Issuer Name',
4  annualFee: 595,
5  benefits: [
6    // Monthly benefit example
7    {
8      description: '$15 Monthly Credit (Service Name)',
9      category: 'Travel',
10      maxAmount: 15,
11      frequency: BenefitFrequency.MONTHLY,
12      percentage: 0,
13      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
14      occurrencesInCycle: 1,
15    },
16    // Quarterly benefit example
17    {
18      description: '$100 Quarterly Travel Credit',
19      category: 'Travel',
20      maxAmount: 100,
21      frequency: BenefitFrequency.QUARTERLY,
22      percentage: 0,
23      cycleAlignment: BenefitCycleAlignment.CARD_ANNIVERSARY,
24      occurrencesInCycle: 1,
25    },
26    // Semi-annual benefit (Jan-Jun)
27    {
28      description: '$250 Hotel Credit (Jan-Jun)',
29      category: 'Travel',
30      maxAmount: 250,
31      frequency: BenefitFrequency.YEARLY,
32      percentage: 0,
33      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
34      fixedCycleStartMonth: 1,
35      fixedCycleDurationMonths: 6,
36      occurrencesInCycle: 1,
37    },
38    // Semi-annual benefit (Jul-Dec)
39    {
40      description: '$250 Hotel Credit (Jul-Dec)',
41      category: 'Travel',
42      maxAmount: 250,
43      frequency: BenefitFrequency.YEARLY,
44      percentage: 0,
45      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
46      fixedCycleStartMonth: 7,
47      fixedCycleDurationMonths: 6,
48      occurrencesInCycle: 1,
49    },
50    // Yearly benefit
51    {
52      description: '$200 Airline Fee Credit',
53      category: 'Travel',
54      maxAmount: 200,
55      frequency: BenefitFrequency.YEARLY,
56      percentage: 0,
57      cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
58      fixedCycleStartMonth: 1,
59      fixedCycleDurationMonths: 12,
60      occurrencesInCycle: 1,
61    },
62  ],
63}

Step 4: Apply the Seed

bash
1npx prisma db seed

Step 5: Verify

bash
1# List all available cards to verify
2node scripts/list-available-cards.cjs

Benefit Categories

Use these standard categories:

• Travel - Airlines, hotels, TSA PreCheck, Uber, Lyft
• Dining - Restaurants, food delivery
• Entertainment - Streaming, events, concerts
• Electronics - Dell, Apple, Best Buy
• Wellness - Equinox, fitness memberships
• Software - Adobe, subscriptions
• Business Services - Professional services

Benefit Inclusion Criteria

Include:

• Credits that reset on cycles (monthly/quarterly/yearly)
• Free nights, statement credits, points multipliers with caps

Exclude:

• Lounge memberships (Priority Pass, Centurion)
• Insurance benefits
• Earning rate multipliers without caps
• One-time signup bonuses
• Elite status benefits

Common Patterns

Calendar-Fixed Monthly

Credits that reset on the 1st of each month:

typescript
1cycleAlignment: BenefitCycleAlignment.CALENDAR_FIXED,
2frequency: BenefitFrequency.MONTHLY,

Card Anniversary Quarterly

Credits that reset every 3 months from card opening:

typescript
1cycleAlignment: BenefitCycleAlignment.CARD_ANNIVERSARY,
2frequency: BenefitFrequency.QUARTERLY,

Semi-Annual (Split Year)

Two separate benefits, one for each half of the year:

typescript
1// First half: Jan-Jun
2fixedCycleStartMonth: 1,
3fixedCycleDurationMonths: 6,
4
5// Second half: Jul-Dec
6fixedCycleStartMonth: 7,
7fixedCycleDurationMonths: 6,

Image Download Troubleshooting

If the automatic download fails:

1. Try UseYourCredits source: --source useyourcredits
2. Manual URL: Find the image manually and use --url
3. Check slug mapping: Update USEYOURCREDITS_SLUGS in the script