# Managing an external subscription If you're not using [our subscription service](/digital-river-api/using-our-services/subscriptions.md), you can still use the Digital River APIs to manage a subscription after completing the [acquisition process](/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions.md). On this page, you'll find information on: * [Auto-renewing a subscription](#auto-renewing-a-subscription) * [Updating the subscription](#handling-subscription-changes) ## Auto-renewing a subscription You must [send the customer a reminder](#sending-the-renewal-reminder) before auto-renewing a subscription. [Configure and submit the renewal request](#configuring-the-renewal-request) at the start of each new billing cycle. Once the renewal is successfully processed, [notify the customer](#notifying-customers-of-a-subscriptions-renewal). ### 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](https://digitalriver.service-now.com/kb?id=kb_article_view\&sys_kb_id=785fc80adbd8341046e8d6aa48961907) article provides a complete list of what is required in the renewal reminder (*refer to* [*Learning tools*](/digital-river-api/general-resources/standards-and-certifications/compliance-requirements.md#accessing-the-learning-tools) *for access information*). ### Configuring the renewal request At the start of each billing cycle, build a renewal [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts). Before [order creation](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier), a subscription renewal checkout should contain: * A `customerId` that references the same [customer ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/customers)contained in the acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders) * A [`sources[]`](/digital-river-api/payments/payment-sources.md) that is [reusable](/digital-river-api/payments/payment-sources.md#reusable-or-single-use), saved to the referenced customer, and has the same `id` as the [primary source](/digital-river-api/payments/payment-sources/using-the-source-identifier.md#primary-payment-sources) in the acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders) * A [`chargeType`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md) set to [`merchant_initiated`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md#merchant-initiated), thereby instructing Digital River to notify payment processors that a server auto-generated the authorization request {% hint style="warning" %} For manual renewals, which require customers' active participation, set `chargeType` to [`customer_initiated`](/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge.md#customer-initiated) and [`autoRenewal`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#auto-renewal) to `false`. {% endhint %} For each [`items[]`](/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items.md) in the renewal [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts): * Set [`subscriptionInfo.autoRenewal`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#auto-renewal) to `true` * Pass the same [`subscriptionInfo.billingAgreementId`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#billing-agreements) assigned to that item in the acquisition. Unless a [change event](#handling-subscription-changes) requires creating a new [billing agreement](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#billing-agreements), use this identifier throughout a subscription's lifecycle.‌ If an acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders) contains multiple `items[]` with `subscriptionInfo`, and each has the same [`terms`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#terms), then you can process all of their renewals in the same [checkout](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts). If the `terms` are different, then you should create unique [checkouts ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/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`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#terms) in the renewal request. To authorize payment on the subscription renewal, [convert the checkout to an order](/digital-river-api/order-management/creating-and-updating-an-order.md#creating-an-order-with-the-checkout-identifier). A `201 Created` returns the same `billingAgreementId`, which you should continue to persist. {% tabs %} {% tab title="Checkout" %} ``` { "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" } } } ``` {% endtab %} {% endtabs %} ### Notifying customers of a subscription's renewal Once you either [synchronously](/digital-river-api/order-management/creating-and-updating-an-order.md#accepted) or [asynchronously](/digital-river-api/order-management/creating-and-updating-an-order.md#listening-for-the-order-accepted-event) receive an [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders) in an [`accepted`](/digital-river-api/order-management/creating-and-updating-an-order.md#handling-accepted-orders) state, you can [fulfill](/digital-river-api/order-management/fulfillments.md) the subscription's products, and then [capture payment](/digital-river-api/order-management/informing-digital-river-of-a-fulfillment.md). Upon receipt of the [`order.charge.capture.complete`](/digital-river-api/order-management/informing-digital-river-of-a-fulfillment.md#successful-charge-captures), notify end customers within 24 hours that the subscription has been renewed. The [Subscription Notifications](https://digitalriver.service-now.com/kb?id=kb_article_view\&sys_kb_id=785fc80adbd8341046e8d6aa48961907) article (*refer to* [*Learning tools*](/digital-river-api/general-resources/standards-and-certifications/compliance-requirements.md#accessing-the-learning-tools) *for access information*) provides a comprehensive list of the information you must include in this notification. ## Handling subscription updates After most subscription change events, you can continue processing renewals using the same [`billingAgreementId`](/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1.md#billing-agreements) 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.
ScenarioDetailsSame or new billingAgreementId?
Modifying payment methods

The payment method is updated mid-term or the customer supplies a new payment method. Two common examples are when the customer performs a mid-term update of a credit card's expiration date or, during a manual renewal, the

customer provides a credit card that is different from the one used when acquiring the subscription.

Same
Metered billingSome subscriptions use a metered approach to billing. For example, an API subscription service might allow only a certain number of requests per month. When customers exceed that pre-defined threshold, they are charged on a per request basis, potentially causing their monthly bills to fluctuate.Same
Free trials

After a designated period of time, it's common for free trials to convert to paid subscriptions. Unless a customer actively cancels the trial, these conversions are typically automatic.


As long as the acquisition agreement specifies this condition, you should continue using the same billing agreement in all post-conversion transactions.

Same
UpgradesWhen you receive a customer-initiated request to upgrade the subscription to a higher service level, we recommend you generate a new billing agreement. For example, a customer currently enrolled in a $100/month plan might request an upgrade to a $200/month plan.New
Modifying a subscription's billing cycle or durationA customer requests a modification to a subscription's billing cycle or duration. For example, the customer might want to switch from monthly to annual billing.New
Updating a subscription's quantity

This describes a customer-initiated change to the quantity of a subscription line item.

​

In this scenario, since Digital River's standardized autorenewal terms do not stipulate that the customer's saved payment information can be used for quantity modifications, you need to generate a new billing agreement.

New
Adding a new subscriptionA customer purchases an add-on subscription product or service and the add-on requires creating a unique line item with subscription information.New
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/digital-river-api/subscription-management/managing-an-external-subscription.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.