Managing an external subscription

If you're using a third-party subscription service, gain a better understanding of how to submit billing renewals and make updates

If you're not using our subscription service, you can still use the Digital River APIs to manage a subscription after completing the acquisition process. On this page, you'll find information on:

Auto-renewing a subscription

You must send the customer a reminder before auto-renewing a subscription. Configure and submit the renewal request at the start of each new billing cycle. Once the renewal is successfully processed, notify the customer.

Sending the renewal reminder

For auto-renewing subscriptions with terms greater than 30 days, you must notify the subscriber of upcoming renewals 30 days before the renewal date. We recommend that you provide additional notifications as the renewal date approaches.

The Subscription Notifications article provides a complete list of what is required in the renewal reminder (refer to Learning tools for access information).

Configuring the renewal request

At the start of each billing cycle, build a renewal checkout. Prior to order creation, a subscription renewal checkout should contain:

For manual renewals, which require customers' active participation, set chargeType to customer_initiated and autoRenewal to false.

For each items[] in the renewal checkout:

If an acquisition order contains multiple items[] with subscriptionInfo, and each has the same terms, then you can process all of their renewals in the same checkout. If the terms are different, then you should create unique checkouts to renew each.

Since customers accept a subscription's terms during acquisitions, and therefore they've already been added to the billing agreement, it's not necessary to pass terms in the renewal request.

To authorize payment on the subscription renewal, convert the checkout to an order. A 201 Created returns the same billingAgreementId, which you should continue to persist.

{
    "id": "d229fc76-3398-4038-bd90-2e152769bef0",
    "createdTime": "2022-04-07T21:42:48Z",
    "customerId": "533134230336",
    "currency": "USD",
    "email": "anyemail@digitalriver.com",
    "billTo": {
        "address": {
            "line1": "10381 Bren Rd W",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "William Brown",
        "email": "null@digitalriver.com"
    },
    "totalAmount": 10.0,
    "subtotal": 10.0,
    "totalFees": 0.0,
    "totalTax": 0.0,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 0.0,
    "items": [
        {
            "id": "39153fb7-e5d5-498f-9465-005560ba268e",
            "skuId": "0181a7a9-610e-48c5-89e5-84ca06c69f03",
            "amount": 10.0,
            "quantity": 1,
            "tax": {
                "rate": 0.0,
                "amount": 0.0
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "subscriptionInfo": {
                "autoRenewal": true,
                "freeTrial": false,
                "billingAgreementId": "c567f049-9ec4-4c63-829b-efe01427a8a9"
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "updatedTime": "2022-04-07T21:42:48Z",
    "locale": "en_US",
    "customerType": "individual",
    "chargeType": "merchant_initiated",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "liveMode": false,
    "payment": {
        "sources": [
            {
                "id": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
                "type": "creditCard",
                "amount": 10.0,
                "owner": {
                    "firstName": "William",
                    "lastName": "Brown",
                    "email": "null@digitalriver.com",
                    "address": {
                        "line1": "10381 Bren Rd W",
                        "city": "Minnetonka",
                        "postalCode": "55343",
                        "state": "MN",
                        "country": "US"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            }
        ],
        "session": {
            "id": "e007a135-07ea-4cc8-897e-9081f3f7d9d9",
            "amountContributed": 10.0,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "e007a135-07ea-4cc8-897e-9081f3f7d9d9_51266228-527e-4add-a4e8-bac1b141ff46"
        }
    }
}

Notifying customers of a subscription's renewal

Once you either synchronously or asynchronously receive an order in an accepted state, you can fulfill the subscription's products, and then capture payment. Upon receipt of the order.charge.capture.complete, notify end customers within 24 hours that the subscription has been renewed.

The Subscription Notifications article (refer to Learning tools for access information) provides a comprehensive list of the information you're required to include in this notification.

Handling subscription updates

After most subscription change events, you can continue processing renewals using the same billingAgreementId generated during the acquisition.‌

In other scenarios, when the underlying subscription is modified, we recommend that you generate a new billing agreement.

As a rule of thumb, you should create a new billing agreement whenever the scope of a subscription update is not defined in its autorenewal terms.‌

The following provides some common subscription change scenarios and indicates whether a new billing agreement is recommended.

Last updated