Add an aggregated subscription

So far we have discussed starting one or more subscriptions and invoicing them concurrently. The following section discusses what happens when we add in a new subscription and have it aggregated.

Subsequent Subscriptions(s)

When adding a new subscription the billing cycle can either be aligned immediately or delayed till the next invoice.

Immediate Alignment

Aligning the first period is the default and recommended way of adding aggregating subscriptions as this generally matches customer expectation of billing behavior.

Delayed Alignment

Aligning the second period can be useful in scenarios where you want to get the full cost up-front but subsequent invoices can be pro-rated, for example annual subscriptions.

To better understand how these behaviors work, let’s walk through some scenarios.

Scenario 1: First Period Alignment

Timeline

Time: P0

1. One subscription is added at the start of January let’s call it:
   1. Sub A
   2. This subscription costs $10/month, an invoice is raised for $10.00.

Time: P1

1. After one month Sub A recurs.
   1. Another invoice is raised for $10.00

Time: P1.5

1. After half a month a new subscription, Sub B, is added.
   1. Sub B cost $20/month
   2. As the common billing date will be the start of March (P2) Sub B is automatically aligned to March.
   3. A invoice is generated for Sub B, this is for the time P1.5 -> P2, half a billing period. As Sub B charges $20/month an invoice for $10 is raised.
      1. monthly cost * pro-ration = invoice cost
      2. $20.00 * 0.5 = $10.00
   4. Notice that no invoice is generated for Sub A

Time: P2

1. At the start of March both Sub A and Sub B generate invoices, for $10 and $20 respectively
2. Both invoices are aggregated together and a final invoice for $30.00 is issued.

Scenario 2: Second Period Alignment

Timeline

Time: P0

1. One subscription is added at the start of January let’s call it:
   1. Sub A
   2. This subscription costs $10/month, an invoice is raised for $10.00.

Time: P1

1. After one month Sub A recurs.
   1. Another invoice is raised for $10.00

Time: P1.5

1. After half a month a new subscription, Sub B, is added.
   1. Sub B cost $20/month
   2. This time the subscription is created with alignPeriodWithAggregatingSubscription property set to false. This causes the subscription to start with a non-pro-rated, full billing cycle of one month. API call
   3. An invoice is issued for $20

Time: P2

1. At the start of March only Sub A generates an invoice for $10, this is because Sub B is still not aligned to the common bill date.
   1. Another invoice is raised for $10.00

Time: P2.5

1. As the common billing date will be the start of April (P3) Sub B is automatically aligned to April.
2. An invoice is generated for Sub B, this is for the time 2.5 -> P3, half a billing period. As Sub B charges $20/month an invoice for $10 is raised.
   1. monthly cost * pro-ration = invoice cost
   2. $20.00 * 0.5 = $10.00

Time: P3

1. At the start of April both Sub A and Sub B generate invoices, for $10 and $20 respectively
2. Both invoices are aggregated together and a final invoice for $30.00 is issued.