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, simplifies billing statements for your customers, and can improve payment success rates by reducing the number of charges.
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 bundle contains at most 5 subscriptions (1 primary + 4 bundled). If a customer has more eligible subscriptions, they are split into multiple bundles, each charged separately.
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.
FAQ
I believe the subscriptions should have been bundled but they were charged separately. Why?
Check the bundling criteria above and cross-reference with the affected subscription details in the dashboard. Common reasons for subscriptions not being bundled include:
- The subscriptions use different payment method types. For example, one subscription is set to pay by card while another uses PayPal.
- If you're using cascades, it's possible that one of the subscriptions has a different gateway profile chosen by the cascade rules. For example, you're using Gateway A as the default, but fall back to Gateway B if the charge fails, and one subscription successfully charges on Gateway A while the other fails and falls back to Gateway B - in this case, the subscriptions won't have a matching gateway profile and won't be bundled together.
Can the bundling criteria be customised?
No, the criteria are fixed and cannot be customised. This is needed to ensure that the behaviour is predictable and consistent for all merchants using bundling. The criteria are designed to balance the benefits of bundling (reduced fees, simplified billing) with the need to ensure that bundled subscriptions are compatible for charging together.