# Subscriptions Digital River offers a [PSD2 and SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca)-compliant subscription management service that automatically schedules and processes recurring payments. The service allows you to offer customers free trials and numerous ways to fund recurring transactions. On this page, you'll find information on: * [How to define a business model](#defining-a-business-model) * [How to configure plans for free trials](#setting-up-free-trials) * [Using payment methods to fund subscriptions](#supported-payment-methods-with-subscriptions) How you do subscription acquisitions depends on the checkout solution(s) you've selected. Use the following table to access the appropriate article: | Checkout solution | Article | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Low-code checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts) | [Processing subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/processing-subscription-acquisitions) | | [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) | [Handling subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions) | Once you create the acquisition [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)containing the subscription, you must activate the subscription, fulfill the goods, and manage renewals. For details on how to handle these and other processes, refer to the [Managing a subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page. ## Defining a business model You can share [digital products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) among [plans](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics) in the subscription service. We recommend not relying on [SKUs ](https://docs.digitalriver.com/digital-river-api/product-management/skus#skus)to model subscription entitlements. We also suggest using different plans for your offerings since you can use them to model cohorts for reporting purposes. Digital River's subscription service models recurring billing. It's not intended to model subscription access or entitlements. As a result, you cannot call the service to determine a customer's current access level. Subscription metadata and client data linked to the subscription are useful for modeling details irrelevant to Digital River and within the plan's terms. ### Setting up subscription-based products With Digital River's subscription service, you can either use [SKUs](https://docs.digitalriver.com/digital-river-api/administration/dashboard/catalog/skus) or [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/skus#product-details) to define the [basic and compliance data](https://docs.digitalriver.com/digital-river-api/product-management/skus#basic-versus-compliance-product-data) of any [digital product](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital) you intend to offer on a subscription basis. For more details, refer to [Managing SKUs](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus) and [Using product details](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details). ### Defining plans Once you've [built a product catalog](#setting-up-subscription-based-products), you should set up [plans ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans)that define the behavior of your subscriptions. At a minimum, you should specify a plan's [name ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#name)and terms, designate its [contract length and billing frequency](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#contract-length-and-interval), set up [renewal reminders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#renewal-reminders), and configure its [billing offset days](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#billing-offset) and [collection period days](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#collection-period-days). The following diagram shows how plans define the behavior of subscriptions that belong to them.
### Creating and activating plans When you create a plan using the [`POST /plans`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-1) request, you can set `state` to `draft` or `active`. If you're using Digital River as the system of record before deployment, you may decide creating `draft` plans is beneficial. We will generate one for you if you don't specify a unique `id` in the create plan request. ``` curl --location --request POST 'https://api.digitalriver.com/plans' \ ... --data-raw '{ "name": "Example Plan", "terms": "These are the terms...", "contractBindingDays": 365, "interval": "year", "intervalCount": 1, "reminderOffsetDays": 30, "billingOffsetDays": 5, "collectionPeriodDays":30, "state": "draft" }' ``` A `201 Created` response contains a unique plan identifier. The request also triggers an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of `plan.created`. If the [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics) `state` is `draft` when you're ready to launch, send its identifier as a path parameter in a [`POST /plans/{planId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id-1) and use the request's body to set `state` to `active`. ``` curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \ ... --data-raw '{ "state": "active" }' ``` The plan must be `active` before you can add [subscriptions ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)to it. For details, refer to the [Lifecycle of a plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#lifecycle-of-a-plan) and [Subscription lifecycle](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle). ### Discontinuing and deactivating plans When managing plans within the Digital River system, it's important to understand the implications of discontinuing and deactivating them. Discontinuing a plan allows subscription renewals to continue, but you cannot add new ones. In contrast, deactivating a plan terminates all associated active subscriptions on their [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice). This section will guide you through adjusting a plan's state and highlight the differences between these two actions. When you want to discontinue or deactivate a plan, specify the desired `state` in the payload of a [`POST /plans/{planId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id-1) request. {% tabs %} {% tab title="Discontinue" %} ```javascript curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \ ... --data-raw '{ "state": "discontinued" }' ``` {% endtab %} {% tab title="Deactivate" %} ```javascript curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \ ... --data-raw '{ "state": "deactivated" }' ``` {% endtab %} {% endtabs %} If you attempt to create subscriptions that belong to `discontinued` or `deactivated` plans, an error is thrown during the acquisition checkout. {% tabs %} {% tab title="400 Bad Request" %} ``` { "type": "bad_request", "errors": [ { "code": "plan_not_active", "parameter": "planId", "message": "Plan 86a05e42-3b94-4ee5-b2a5-267efd8b3704 is not active." } ] } ``` {% endtab %} {% endtabs %} Refer to the [Lifecycle of a plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#lifecycle-of-a-plan) and [Subscription lifecycle](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle) for details on how discontinuing or deactivating a plan affects its associated subscriptions. ## Setting up free trials You can configure a customer's subscription to include a free trial period. This section provides information on [defining trial and paid plans](#defining-trial-and-paid-plans) before deployment.\ \ How you handle subscription acquisitions that involve free trials depends on the checkout solution(s) you've selected. Use the following table to access the relevant content: | Checkout solution | Article | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Prebuilt Checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout) | [Trial subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/processing-subscription-acquisitions#managing-trial-subscription-acquisitions) in [Processing subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/processing-subscription-acquisitions) | | [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) | [Trial subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions#managing-trial-subscription-acquisitions) in [Handling subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions) | Once you create the acquisition [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)containing the subscription, you must convert it from trial to paid. For details, refer to [Trial subscription management](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#trial-subscription-management). ### Defining trial and paid plans Before offering free trials, you must configure and deploy plans for your trial [subscriptions](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics). {% hint style="success" %} Refer to [Defining plans](#defining-plans) for general information on plans and their relationship to subscriptions. {% endhint %} For each subscription you intend to offer on a trial basis, you should define a [trial](#trial-period-plans) and [paid period plan](#paid-period-plans). The following diagram shows how you might set up two plans that result in a seven-day free trial period followed by a monthly, recurring billing cycle:
#### Trial period plans Your trial period [plan ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)controls the [subscription's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics) behavior during its first billing cycle. The plan's `interval` and `intervalCount` determine the trial period's length. If, for example, you want to offer a 31-day free trial period, set `interval` to `day` and `intervalCount` to `31` . For free trial plans, set `billingOffsetDays` to `0`. This configuration results in a subscription whose initial billing cycle has the same [`nextInvoiceDate` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice)and [`currentPeriodEndDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#current-period-end-date), thereby ensuring that the first payment capture attempt occurs after the trial period ends. The value you give `reminderOffsetDays` determines when the [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder) event is created. For example, a `reminderOffsetDays` of `3` results in creating a `subscription.reminder` event three days before the trial period's conclusion. Use `collectionPeriodDays` to define the number of days when Digital River will attempt to capture payment. Once the trial period ends, Digital River will initially attempt to charge the customer's designated [payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources). If this proves unsuccessful, our [billing optimization service](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#billing-optimization) will continue making capture attempts for the number of days you specify. {% code title="Plan" %} ```javascript { "id": "186cf07e-a1ea-4ec0-9d9a-8aa93b3af43a", "createdTime": "2022-02-11T14:41:43Z", "updatedTime": "2022-02-11T14:41:43Z", "terms": "7-day free trial plan terms", "contractBindingDays": 7, "interval": "day", "intervalCount": 7, "name": "7-day SaaS free trial", "billingOptimization": true, "billingOffsetDays": 0, "collectionPeriodDays": 4, "reminderOffsetDays": 3, "state": "active", "stateTransitions": { "activated": "2022-02-11T14:41:43Z" }, "liveMode": false } ``` {% endcode %} #### Paid period plans You must also define a paid period [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics) that governs the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)after its trial conversion. The following plan bills customers monthly, and in every billing cycle, Digital River makes the first payment capture attempt three days before the end period date. {% code title="Plan" %} ```javascript { "id": "f55d07a2-a78f-406a-b6c6-ad8e1cc1531b", "createdTime": "2022-02-11T14:42:53Z", "updatedTime": "2022-02-11T14:42:53Z", "terms": "The terms of a one-year plan that is billed monthly," "contractBindingDays": 365, "interval": "month", "intervalCount": 1, "name": "SaaS monthly billing plan", "billingOptimization": true, "billingOffsetDays": 3, "collectionPeriodDays": 7, "reminderOffsetDays": 4, "state": "active,"", "stateTransitions": { "activated": "2022-02-11T14:42:53Z" }, "liveMode": false } ``` {% endcode %} ## **Supported payment methods with subscriptions** When setting up a payment in acquisitions or modifying a subscription's payment source, customers must select the payment methods they want to use for recurring transactions. Refer to the [Supported payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) page for a complete list of such payment methods. {% hint style="success" %} In acquisition checkouts, you can combine a [reusable](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use) primary source with one or more secondary sources. Refer to the [Managing sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier) page for details on [combining primary and secondary payment sources](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#combining-primary-and-secondary-payment-sources). {% endhint %} ## Next steps To learn more about how you interact with subscriptions during checkouts, use the following table to access the appropriate article: | Checkout solution | Article | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Low-code checkouts](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts) | [Processing subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/processing-subscription-acquisitions) | | [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) | [Handling subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions) | --- # 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/using-our-services/subscriptions.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.