Activating Subscriptions

When a subscription is first created it starts out in the Draft state. In this state the subscription can still be widely modified, because the subscription has not been activated to send out any invoices yet. Once the subscription has been activated these options will be limited, as the changes from then on could affect the billing.

Activating the Subscription

Activating the subscription is quite easy and comes with a few options for customization.

curl --request PUT \
     --url https://api-front.upodi.io/Subscriptions/{subscriptionId}/activate \
     --header 'Authorization: Bearer {ApiKey}' \
     --header 'X-version: {version}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
     {
     		"SendEmail":true
     }'

await _client.Subscriptions.ActivateAsync(subscriptionId,
            new ActivateSubscriptionRequest() { SendEmail = false });

Activating and skipping first billing

Sometimes you will want to skip the first billing on an activation. This can be if you've already covered the first payment outside of Upodi or you're using MobilePay Subscriptions or other payment methods, where the first payment is different to the recurring ones. Here you still want the data to resemble that the customer has an active subscription, especially if you're also using Entitlements, even though the customer should not be billed right now.

In case you want to skip first payment you can simply add the SkipPeriods to the activation like so:

curl --location --request PUT 'https://api-front.upodi.io/Subscriptions/{SubscriptionId}/activate' \
--header 'X-version: {version}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ApiKey}' \
--data-raw '{
    "chargeSettings": [
        {
            "SubscriptionChargeID": "{SubscriptionChargeId}",
            "SkipPeriods": 1
        }
    ]
}'

Activating with a different date as anchor

In some cases you maybe want to activate it now, but have all future billing on a specific day in the month. Maybe it's a monthly subscription and you'd rather want it to bill on the 1st of every month or it's a quarterly and you want all your quarterlies to be billing on the natural quarters of the year.

A simplified example would be a Customer signs up the 15th of June for a monthly billed product of €100/mo, but we want the subscription to be billed every 1st of the month (1st of July). So we pass the 1st of July as the desired proration date, and the first invoice line would result in 15th to 30th of June amounting to €50, and the next coming charge would be the normal entire July for €100.

This can be achieved by inputting the desired date as ProrateDate on the Activate call like so:

curl --request PUT \
     --url https://api-front.upodi.io/Subscriptions/{subscriptionId}/activate \
     --header 'Authorization: Bearer {ApiKey}' \
     --header 'X-version: {version}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
 	 "SendEmail": true,
 	 "ProrateDate": "2023-05-31 23:00:00.000"
}'

await _client.Subscriptions.ActivateAsync(subscriptionId,
            new ActivateSubscriptionRequest()
                { SendEmail = false, ProrateDate = new DateTime(2023, 05, 31, 23, 00, 00) });

Maybe in a more rare case you want to do it per charge, and this can be done by adding the ProrateDate to the ChargeSettings for each of the charges. In order to do this please consult the Activate Subscription endpoint to see the needed inputs.