---
title: Direct Mode Examples
description: Real-world examples for common subscription scenarios
---

Practical examples showing how to structure customer and subscription data for different billing scenarios. All examples show the `subscriptions` array, which should be combined with `customer` and `handleCancel` from the [Churnkey Direct guide](/billing-providers/direct-connect/direct).

## Basic subscriptions

### Monthly subscription

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_monthly',
    status: {
      name: 'active',
      currentPeriod: {
        start: new Date('2025-01-01'),
        end: new Date('2025-02-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_pro_monthly',
          name: 'Pro Plan',
          interval: 'month',
          intervalCount: 1,
          amount: { value: 2999, currency: 'usd' }, // $29.99
        },
      },
    ],
  },
];
```

### Annual subscription

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_annual',
    status: {
      name: 'active',
      currentPeriod: {
        start: new Date('2025-06-01'),
        end: new Date('2026-06-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_pro_annual',
          name: 'Pro Plan - Annual',
          interval: 'year',
          intervalCount: 1,
          amount: { value: 29900 }, // $299/year
        },
      },
    ],
  },
];
```

### Quarterly subscription

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_quarterly',
    status: {
      name: 'active',
      currentPeriod: {
        start: new Date('2025-09-01'),
        end: new Date('2025-12-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_quarterly',
          name: 'Quarterly Plan',
          interval: 'month',
          intervalCount: 3,
          amount: { value: 7999 }, // $79.99 every 3 months
        },
      },
    ],
  },
];
```

## Subscription statuses

### Trial subscription

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_trial',
    status: {
      name: 'trial',
      trial: {
        start: new Date('2026-01-01'),
        end: new Date('2026-01-14'),
      },
      // currentPeriod optional - defaults to trial period
    },
    items: [
      {
        price: {
          id: 'price_pro',
          name: 'Pro Plan',
          amount: { value: 2999 },
        },
      },
    ],
  },
];
```

### Paused subscription

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_paused',
    status: {
      name: 'paused',
      pause: {
        start: new Date('2026-01-15'),
        end: new Date('2026-02-15'), // Omit for indefinite pause
      },
      currentPeriod: {
        start: new Date('2026-01-01'),
        end: new Date('2026-02-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_pro',
          name: 'Pro Plan',
          amount: { value: 2999 },
        },
      },
    ],
  },
];
```

## Advanced pricing

### Per-seat pricing

Subscription with quantity-based pricing:

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_team',
    status: {
      name: 'active',
      currentPeriod: {
        start: new Date('2025-11-01'),
        end: new Date('2025-12-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_per_seat',
          name: 'Team Plan',
          interval: 'month',
          intervalCount: 1,
          amount: { value: 1500 }, // $15 per seat
        },
        quantity: 10, // 10 seats = $150/month total
      },
    ],
  },
];
```

### Multi-item subscription

Customer with base plan plus add-ons:

```javascript
subscriptions: [
  {
    start: new Date('2025-06-01'),
    id: 'sub_bundle',
    status: {
      name: 'active',
      currentPeriod: {
        start: new Date('2025-10-01'),
        end: new Date('2025-11-01'),
      },
    },
    items: [
      {
        price: {
          id: 'price_base',
          name: 'Base Plan',
          amount: { value: 2999 },
        },
      },
      {
        price: {
          id: 'price_analytics_addon',
          name: 'Analytics Add-on',
          amount: { value: 500 },
        },
        quantity: 2, // 2 analytics add-ons
      },
    ],
  },
];
```

### Non-USD currency

Customer in different currency:

```javascript
customer: {
  id: 'cus_uk',
  email: 'user@example.co.uk',
  currency: 'gbp',
},

subscriptions: [{
  id: 'sub_uk',
  start: new Date('2025-06-01'),
  status: {
    name: 'active',
    currentPeriod: {
      start: new Date('2025-01-01'),
      end: new Date('2025-02-01'),
    },
  },
  items: [{
    price: {
      id: 'price_pro_gbp',
      name: 'Pro Plan',
      amount: { value: 2499, currency: 'gbp' }, // £24.99
    },
  }],
}]
```

## Custom metadata

Pass custom attributes for segmentation and analytics:

```javascript
customer: {
  id: 'cus_enterprise',
  email: 'admin@bigcorp.com',
  name: 'Enterprise Admin',
  metadata: {
    account_type: 'enterprise',
    team_size: 35,
    industry: 'saas',
  },
},

subscriptions: [{
  id: 'sub_enterprise',
  start: new Date('2025-01-01'),
  status: {
    name: 'active',
    currentPeriod: {
      start: new Date('2025-01-01'),
      end: new Date('2026-01-01'),
    },
  },
  items: [{
    price: {
      id: 'price_enterprise',
      name: 'Enterprise Plan',
      interval: 'year',
      intervalCount: 1,
      amount: { value: 120000 }, // $1,200/year
    },
  }],
  metadata: {
    contract_id: 'contract_2025_001',
    renewal_date: '2026-01-01',
  },
}]
```

Use these attributes to create targeted flows in the Flow Builder's **Audience Targeting** section.