Payment Bundling
When a customer has multiple active subscriptions, Odus can charge them in a single payment instead of separate charges per subscription. This reduces transaction fees and simplifies billing statements for your customers.
How It Works
Every minute, Odus checks for subscriptions that are due for renewal. When bundling is enabled, subscriptions belonging to the same customer are grouped together if they meet the bundling criteria. The group is charged as one payment covering all subscriptions in the group.
Enabling Bundling
Bundling is disabled by default. Enable it by sending a POST /merchant-configs/:id request with the following field:
{
"enableRecurringPaymentBundling": true
}
To disable bundling, set the field to false. Bundles that have already been scheduled will still be charged as a single payment. Only billing runs that start after the change will charge subscriptions individually.
Bundling Criteria
Two subscriptions can be bundled together only when all of the following match:
| Criterion | Description |
|---|---|
| Customer | Both subscriptions belong to the same customer |
| Gateway profile | Both use the same payment gateway profile |
| Payment method type | Both use the same payment method type (e.g. card) |
| Capture method | Both have the same capture method |
| Capture delay | Both have the same capture delay setting |
| Currency | Both invoices are in the same currency |
| Renewal window | The later subscription renews within 24 hours of the earlier one |
If any criterion does not match, the subscriptions are charged separately.
Bundle Formation
Within each billing run, subscriptions are sorted by renewal date (earliest first). The subscription due earliest becomes the primary of its bundle. Any other subscription due within 24 hours that shares all criteria with the primary is added to the bundle as a bundled subscription.
Each subscription can only appear in one bundle per billing run.
A customer has three active subscriptions:
- Sub A — renews at 08:00, currency USD, gateway G1
- Sub B — renews at 14:00, currency USD, gateway G1
- Sub C — renews at 08:30, currency EUR, gateway G1
Sub A is the primary. Sub B is within the 24-hour window and shares all criteria, so it is bundled with Sub A. Sub C is within the window, but uses a different currency, so it is charged separately.
Result: one payment for Sub A + Sub B, one payment for Sub C.
Payment and Invoices
A single payment is created for the combined amount of all subscriptions in the bundle. Each subscription in the bundle has its own invoice, and all invoices are attached to that one payment. After a successful charge, every subscription in the bundle advances to its next billing cycle.
Failure Behaviour
Bundled payments follow the same failure behaviour as individual subscription payments:
- If the initial charge fails, Odus starts a payment retry.
- If the retry also fails, all subscriptions in the bundle are cancelled immediately.
A payment failure cancels every subscription in the bundle, not only the one that could not be charged. Make sure your customers have a valid default payment method to minimise the risk of losing access to multiple subscriptions at once.