On-Demand Subscriptions Guide

​

Overview

• Create an on-demand subscription (authorize a mandate with optional initial price)
• Trigger subsequent charges with custom amounts
• Track outcomes using webhooks

​

Prerequisites

• Dodo Payments merchant account and API key
• Webhook secret configured and an endpoint to receive events
• A subscription product in your catalog

​

How on-demand works

1. You create a subscription with the on_demand object to authorize a payment method and optionally collect an initial charge.
2. Later, you create charges against that subscription with custom amounts using the dedicated charge endpoint.
3. You listen to webhooks (e.g., payment.succeeded, payment.failed) to update your system.

​

Create an on-demand subscription

​

Create an on-demand subscription

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});

async function main() {
  const subscription = await client.subscriptions.create({
    billing: { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'customer_123' },
    product_id: 'prod_sub_123',
    quantity: 1,
    payment_link: true,
    return_url: 'https://example.com/billing/success',
    on_demand: {
      mandate_only: true, // set false to collect an initial charge
      // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
      // product_currency: 'USD',
      // product_description: 'Custom initial charge',
      // adaptive_currency_fees_inclusive: false,
    },
  });

  // If payment_link was true, redirect the customer to authorize the mandate
  console.log(subscription.payment_link);
}

main().catch(console.error);

{
  "subscription_id": "sub_123",
  "payment_link": "https://pay.dodopayments.com/checkout/...",
  "customer": { "customer_id": "customer_123", "email": "alex@example.com", "name": "Alex Doe" },
  "metadata": {},
  "recurring_pre_tax_amount": 0,
  "addons": []
}

​

Charge an on-demand subscription

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);

{ "payment_id": "pay_abc123" }

​

Payment retries

​

Principles for safe retry policies

• Backoff mechanism: Use exponential backoff between retries.
• Retry limits: Cap total retries (3–4 attempts max).
• Intelligent filtering: Retry only on retryable failures (e.g., network/issuer errors, insufficient funds); never retry hard declines.
• Card testing prevention: Do not retry failures like DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Vary metadata (optional): If you maintain your own retry system, differentiate retries via metadata (e.g., retry_attempt).

​

Suggested retry schedule (subscriptions)

• 1st attempt: Immediate when you create the charge
• 2nd attempt: After 3 days
• 3rd attempt: After 7 more days (10 days total)
• 4th attempt (final): After another 7 days (17 days total)

​

Avoid burst retries; align to authorization time

• Anchor retries to the original authorization timestamp to avoid “burst” behavior across your portfolio.
• Example: If the customer starts a trial or mandate at 1:10 pm today, schedule follow-up retries at 1:10 pm on subsequent days per your backoff (e.g., +3 days → 1:10 pm, +7 days → 1:10 pm).
• Alternatively, if you store the last successful payment time T, schedule the next attempt at T + X days to preserve time-of-day alignment.

​

Decline codes you should not retry

• STOLEN_CARD
• DO_NOT_HONOR
• FRAUDULENT
• PICKUP_CARD
• AUTHENTICATION_FAILURE
• LOST_CARD

​

Implementation guidelines (no code)

• Use a scheduler/queue that persists precise timestamps; compute next attempt at the exact time-of-day offset (e.g., T + 3 days at the same HH:MM).
• Maintain and reference the last successful payment timestamp T to compute the next attempt; do not bunch multiple subscriptions at the same instant.
• Always evaluate the last decline reason; stop retries for hard declines in the skip list above.
• Cap concurrent retries per customer and per account to prevent accidental surges.
• Communicate proactively: email/SMS the customer to update their payment method before the next scheduled attempt.
• Use metadata only for observability (e.g., retry_attempt); never try to “evade” fraud/risk systems by rotating inconsequential fields.

​

Track outcomes with webhooks

• subscription.active: Mandate authorized and subscription activated
• subscription.failed: Creation failed (e.g., mandate failure)
• subscription.on_hold: Subscription placed on hold (e.g., unpaid state)
• payment.succeeded: Charge succeeded
• payment.failed: Charge failed

​

Testing and next steps

​

Troubleshooting

• 422 Invalid Request: Ensure on_demand.mandate_only is provided on creation and product_price is provided for charges.
• Currency errors: If you override product_currency, confirm it’s supported for your account and customer.
• No webhooks received: Verify your webhook URL and signature secret configuration.