Subscriptions & Rebilling

Time: ~10 minutes | Difficulty: Intermediate

What Are Subscriptions in TagadaPay?

TagadaPay manages the entire recurring billing lifecycle — creation, automatic rebills, retries on failure, pause/resume, cancellation, and processor changes. It’s PSP-agnostic: the same subscription can be billed through Stripe today and NMI tomorrow, without touching your code.

┌────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────┐
│  Customer   │────▶│  Subscribe  │────▶│  Auto-rebill │────▶│  Renew   │
│  pays once  │     │  (active)   │     │  every cycle │     │  forever │
└────────────┘     └─────────────┘     └──────────────┘     └──────────┘
                         │                    │
                         │              ┌─────┴──────┐
                         │              │  Declined?  │
                         │              │  → Retry    │
                         │              │  → Past due │
                         │              │  → Cancel   │
                         │              └────────────┘
                         │
                    ┌────┴────┐
                    │  Trial? │
                    │  7 days │
                    │  free   │
                    └─────────┘

Subscriptions are vaulted. The customer’s card is tokenized once. TagadaPay charges it automatically each cycle — through whichever processor your payment flow selects. You never handle raw card data or PSP-specific recurring APIs.

Subscription Lifecycle

Status	Meaning
`trialing`	Free trial period, no charges yet
`active`	Recurring charges are running
`past_due`	Last rebill failed, retrying automatically
`paused`	Billing suspended, can be resumed
`canceled`	Terminated (immediately or at period end)

create → trialing → active ⟲ (rebill each cycle)
                       ↓
                   past_due → retry → active (success)
                       ↓              → canceled (max retries)
                       ↓
                    paused → resume → active
                       ↓
                   canceled

Create a Subscription

import Tagada from '@tagadapay/node-sdk';

const tagada = new Tagada('your-api-key');

const { subscription } = await tagada.subscriptions.create({
  customerId: 'cus_abc123',
  priceId: 'price_monthly_2999',
  storeId: 'store_xxx',
  currency: 'USD',
  quantity: 1,
  defaultPaymentInstrumentId: 'pi_abc123',
});

console.log(subscription.id);             // 'sub_xyz789'
console.log(subscription.status);          // 'active'
console.log(subscription.nextBillingDate); // '2026-04-19T00:00:00Z'

Parameter	Required	Description
`customerId`	Yes	The customer to bill
`priceId`	Yes	A recurring price (from a product variant)
`storeId`	Yes	Your store
`currency`	Yes	ISO currency code
`defaultPaymentInstrumentId`	No	Card to charge (uses customer’s default if omitted)
`quantity`	No	Number of units (default: 1)
`paymentId`	No	Link to the initial payment
`billingCycleAnchor`	No	ISO date — fix the billing day (e.g. always the 1st)
`initiatePayment`	No	Charge immediately on creation

Create with a Free Trial

const { subscription } = await tagada.subscriptions.create({
  customerId: 'cus_abc123',
  priceId: 'price_monthly_2999',
  storeId: 'store_xxx',
  currency: 'USD',
  defaultPaymentInstrumentId: 'pi_abc123',
  trialSettings: {
    trialPeriodDuration: 7,
    trialPeriodDurationType: 'day',
  },
});

console.log(subscription.status); // 'trialing'
console.log(subscription.trial);  // true

The customer isn’t charged until the trial ends. TagadaPay automatically transitions to active and triggers the first rebill.

Trial Duration Type	Examples
`day`	3 days, 7 days, 14 days
`week`	1 week, 2 weeks
`month`	1 month, 3 months

Manual Rebill

Trigger an immediate charge on any active or past_due subscription — useful for dashboards, support tools, or retry scripts.

const result = await tagada.subscriptions.rebill('sub_xyz789');

console.log(result.success); // true
console.log(result.message); // 'Rebill triggered successfully'

What happens under the hood:

TagadaPay loads the subscription’s price, currency, and payment instrument
Routes the charge through your payment flow (cascade, weighted, fallback — all automatic)
On success → updates nextBillingDate, status stays active
On decline → enters retry logic (see below)

When to Use Manual Rebill

Scenario	Example
Customer updated card	They fixed their card details, you want to charge immediately instead of waiting for auto-retry
Support request	”Please charge me now”
Retry script	Batch-retry all `past_due` subscriptions
Testing	Verify billing works end-to-end

Batch Retry All Past-Due Subscriptions

const { data: subscriptions } = await tagada.subscriptions.list({
  per_page: 100,
  filters: {
    'subscriptions.status': ['past_due'],
    storeIds: ['store_xxx'],
  },
});

console.log(`Found ${subscriptions.length} past-due subscriptions`);

for (const sub of subscriptions) {
  try {
    await tagada.subscriptions.rebill(sub.id);
    console.log(`Rebilled ${sub.id}`);
  } catch (err) {
    console.log(`Failed ${sub.id}: ${err.message}`);
  }
}

Automatic Retry on Failure

When a rebill is declined, TagadaPay doesn’t immediately cancel. It retries automatically:

Rebill declined
  → Wait 24h  → Retry #1
  → Wait 48h  → Retry #2
  → Wait 96h  → Retry #3
  → Wait 168h → Retry #4
  → Wait 168h → Retry #5
  → Cancel subscription

Retry	Delay	Total elapsed
1	24 hours	1 day
2	48 hours	3 days
3	96 hours	7 days
4	168 hours	14 days
5	168 hours	21 days

During retries, the subscription status is past_due. After max retries, it’s automatically canceled.

Smart retry is also available — it uses failure codes (e.g. “insufficient funds”), velocity limits, and even payroll-day heuristics to pick the optimal retry time. Contact support to enable it.

Cancel a Subscription

Cancel Immediately

await tagada.subscriptions.cancel({
  subscriptionIds: ['sub_xyz789'],
});
// Status → 'canceled' right now

Cancel at Period End

await tagada.subscriptions.cancel({
  subscriptionIds: ['sub_xyz789'],
  cancelAtPeriodEnd: true,
});
// Stays 'active' until currentPeriodEnd, then auto-cancels

The customer keeps access until their billing period ends. TagadaPay handles the scheduled cancellation automatically.

Bulk Cancel

await tagada.subscriptions.cancel({
  subscriptionIds: ['sub_001', 'sub_002', 'sub_003'],
  cancelAtPeriodEnd: true,
});

Resume a Subscription

Resume a canceled, paused, or past_due subscription:

await tagada.subscriptions.resume({
  subscriptionIds: ['sub_xyz789'],
});
// Status → 'active', billing resumes

If the subscription had cancelAtPeriodEnd: true but hasn’t reached the end yet, resuming clears the cancellation flag.

Pause a Subscription

Pausing stops billing without canceling — the subscription stays on file and can be resumed at any time. Useful for customer-portal self-serve, seasonal accounts, or account-recovery flows where you don’t want to lose the vaulted card.

await tagada.subscriptions.pause({
  subscriptionIds: ['sub_xyz789'],
});
// Status → 'paused', billing suspended until resume

Bulk Pause

await tagada.subscriptions.pause({
  subscriptionIds: ['sub_001', 'sub_002', 'sub_003'],
});

Only subscriptions belonging to the authenticated account are affected — ids you don’t own are silently ignored (no error). Response shape: { success: true }.

Pause vs. Cancel at Period End

Scenario	Use
Customer explicitly wants to keep the sub, just skip billing for a while	`pause`
Customer wants to end the sub but keep it running through the current cycle	`cancel({ cancelAtPeriodEnd: true })`
Customer wants to end the sub immediately	`cancel({ cancelAtPeriodEnd: false })`

Resume works the same way for both paused and canceled states — tagada.subscriptions.resume({ subscriptionIds: [...] }).

Change Processor

Move a subscription from one processor to another — for example, migrating from Stripe to Checkout.com, or clearing a stuck processor.

Assign a Specific Processor

const { subscription } = await tagada.subscriptions.changeProcessor(
  'sub_xyz789',
  'proc_cko',  // Checkout.com
);

console.log(subscription.processorId); // 'proc_cko'

The next rebill will use Checkout.com instead of the previous processor.

Let TagadaPay Auto-Select

const { subscription } = await tagada.subscriptions.changeProcessor('sub_xyz789');
// No processorId → TagadaPay uses the payment flow strategy

This removes the sticky processor, so the next rebill will be routed by your payment flow (weighted, cascade, etc.).

Use Case: Migrate All Subscriptions from Stripe to NMI

const { data: subscriptions } = await tagada.subscriptions.list({
  per_page: 100,
  filters: {
    'subscriptions.status': ['active'],
    processorIds: ['proc_s1'],  // current: Stripe
  },
});

for (const sub of subscriptions) {
  await tagada.subscriptions.changeProcessor(sub.id, 'proc_nmi');
  console.log(`Migrated ${sub.id} to NMI`);
}

This is a TagadaPay superpower. With a traditional PSP, migrating subscriptions between processors means re-collecting card details. With TagadaPay’s PSP-agnostic vault, you just change the processor ID — the vaulted card works across all processors.

List & Filter Subscriptions

const { data, total, hasMore } = await tagada.subscriptions.list({
  page: 1,
  per_page: 50,
  sort: 'createdAt',
  sort_order: 'desc',
  filters: {
    storeIds: ['store_xxx'],
    'subscriptions.status': ['active', 'trialing'],
  },
});

for (const sub of data) {
  console.log(`${sub.id} — ${sub.status} — next bill: ${sub.nextBillingDate}`);
}

Available Filters

Filter	Type	Example
`subscriptions.status`	`string[]`	`['active', 'past_due']`
`subscriptions.trial`	`boolean`	`true`
`storeIds`	`string[]`	`['store_xxx']`
`processorIds`	`string[]`	`['proc_s1', 'proc_nmi']`
`currency`	`string`	`'USD'`
`customerEmail`	`string`	`'jane@example.com'`
`price`	`{ condition, value }`	`{ condition: 'gte', value: [1000] }`
`date`	`{ condition, value }`	`{ condition: 'between', value: ['2026-01-01', '2026-03-01'] }`
`nextBillingDate`	`{ condition, value }`	`{ condition: 'lte', value: ['2026-03-25'] }`

Retrieve a Subscription

const { subscription } = await tagada.subscriptions.retrieve('sub_xyz789');

console.log(subscription.status);                // 'active'
console.log(subscription.currentPeriodStart);     // '2026-03-01T00:00:00Z'
console.log(subscription.currentPeriodEnd);       // '2026-04-01T00:00:00Z'
console.log(subscription.nextBillingDate);        // '2026-04-01T00:00:00Z'
console.log(subscription.processorId);            // 'proc_s1'
console.log(subscription.paymentInstrumentId);    // 'pi_abc123'
console.log(subscription.cancelAtPeriodEnd);      // false

Webhook Events

Listen for subscription events via webhooks to keep your system in sync:

Event	When it fires
`subscription/created`	New subscription created
`subscription/rebillSucceeded`	Recurring charge succeeded
`subscription/rebillDeclined`	Recurring charge failed
`subscription/pastDue`	Subscription entered past_due after decline
`subscription/paused`	Subscription paused
`subscription/resumed`	Subscription resumed
`subscription/canceled`	Subscription canceled immediately
`subscription/cancelScheduled`	Cancel scheduled for period end
`subscription/rebillUpcoming`	Upcoming rebill (advance notice)

Full Example: Subscription with Trial, Rebill, and Processor Migration

import Tagada from '@tagadapay/node-sdk';

const tagada = new Tagada('your-api-key');
const storeId = 'store_xxx';

// ── 1. Create a subscription with 14-day trial ──────────────────────
const { subscription } = await tagada.subscriptions.create({
  customerId: 'cus_abc123',
  priceId: 'price_monthly_2999',
  storeId,
  currency: 'USD',
  defaultPaymentInstrumentId: 'pi_abc123',
  trialSettings: {
    trialPeriodDuration: 14,
    trialPeriodDurationType: 'day',
  },
});

console.log(`Created: ${subscription.id} — ${subscription.status}`);
// → "Created: sub_xyz789 — trialing"

// ── 2. Later: trial ends, auto-rebill runs ──────────────────────────
// (TagadaPay handles this automatically — no code needed)

// ── 3. Manual rebill (e.g. customer updated their card) ─────────────
const rebillResult = await tagada.subscriptions.rebill(subscription.id);
console.log(`Rebill: ${rebillResult.message}`);

// ── 4. Move subscription from Stripe to Checkout.com ────────────────
const { subscription: updated } = await tagada.subscriptions.changeProcessor(
  subscription.id,
  'proc_cko',
);
console.log(`Processor changed to: ${updated.processorId}`);

// ── 5. Customer wants to cancel at period end ───────────────────────
await tagada.subscriptions.cancel({
  subscriptionIds: [subscription.id],
  cancelAtPeriodEnd: true,
});
console.log('Cancel scheduled at period end');

// ── 6. Customer changes their mind — resume ─────────────────────────
await tagada.subscriptions.resume({
  subscriptionIds: [subscription.id],
});
console.log('Subscription resumed!');

Next Steps

Multi-PSP Routing & Vault

Connect Stripe, NMI, Checkout.com, Airwallex and route payments intelligently

Headless Payments (Frontend)

Build your own checkout UI with client-side card tokenization and 3DS

Node SDK Quick Start

Get started with stores, products, and funnels

API Reference

Full REST API documentation

​Subscriptions & Rebilling

​What Are Subscriptions in TagadaPay?

​Subscription Lifecycle

​Create a Subscription

​Create with a Free Trial

​Manual Rebill

​When to Use Manual Rebill

​Batch Retry All Past-Due Subscriptions

​Automatic Retry on Failure

​Cancel a Subscription

​Cancel Immediately

​Cancel at Period End

​Bulk Cancel

​Resume a Subscription

​Pause a Subscription

​Bulk Pause

​Pause vs. Cancel at Period End

​Change Processor

​Assign a Specific Processor

​Let TagadaPay Auto-Select

​Use Case: Migrate All Subscriptions from Stripe to NMI

​List & Filter Subscriptions

​Available Filters

​Retrieve a Subscription

​Webhook Events

​Full Example: Subscription with Trial, Rebill, and Processor Migration

​Next Steps

Multi-PSP Routing & Vault

Headless Payments (Frontend)

Node SDK Quick Start

API Reference

Subscriptions & Rebilling

What Are Subscriptions in TagadaPay?

Subscription Lifecycle

Create a Subscription

Create with a Free Trial

Manual Rebill

When to Use Manual Rebill

Batch Retry All Past-Due Subscriptions

Automatic Retry on Failure

Cancel a Subscription

Cancel Immediately

Cancel at Period End

Bulk Cancel

Resume a Subscription

Pause a Subscription

Bulk Pause

Pause vs. Cancel at Period End

Change Processor

Assign a Specific Processor

Let TagadaPay Auto-Select

Use Case: Migrate All Subscriptions from Stripe to NMI

List & Filter Subscriptions

Available Filters

Retrieve a Subscription

Webhook Events

Full Example: Subscription with Trial, Rebill, and Processor Migration

Next Steps