Direct Connect
Direct Mode Examples
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.
Basic subscriptions
Monthly subscription
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
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
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
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
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:
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:
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:
customer: {
id: 'cus_uk',
email: '[email protected]',
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:
customer: {
id: 'cus_enterprise',
email: '[email protected]',
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.