LogoLogo
System Status
  • Digital River API
  • Getting started
  • Using our services
    • Local pricing
    • Item classification
    • Subscriptions
    • e-Invoicing
  • Integration options
    • Low-code checkouts
      • Implementing a Prebuilt Checkout
      • Implementing a Components checkout
      • Offering local pricing
      • Using a shipping endpoint
      • Processing subscription acquisitions
      • Adding custom fields
      • Offering store credit
      • Displaying policies and getting consent
      • Collecting e-invoice information
      • Handling completed checkout-sessions
    • Direct integrations
      • Standard flow
      • Building checkouts
        • Checking out guest and registered customers
        • Describing line items
          • Setting the price of an item
          • Managing items with shared SKU identifiers
        • Providing address information
        • Handling shipping choice
        • Tax identifiers
        • Applying a discount
        • Setting the customer type
        • Providing the IP address
        • Selecting a currency
        • Initiating a charge
        • Setting the purchase location
        • Configuring taxes
        • Accessing regulatory fee information
        • Localizing invoices and credit memos
        • Providing an upstream identifier
        • Applying store credit
        • Handling e-invoicing requirements
        • Landed cost
        • Tax calculation inputs
        • Selling entities
        • Payment sessions
        • Applying store credit (legacy)
        • Country specs
      • Building payment workflows
        • Handling redirect payment methods
        • Handling delayed payment methods
      • Subscription acquisitions
        • Handling subscription acquisitions
        • Handling external subscription acquisitions
        • Subscription information
      • Digital River coordinated fulfillments
        • Checking inventory levels
        • Using shipping quotes
        • Reserving inventory items
        • Managing a fulfillment order
        • Cancelling a fulfillment order
    • Connectors
  • Order management
    • Processing orders
    • Handling a rejected order
    • Accessing invoices and credit memos
    • Fulfilling goods and services
    • Capturing and cancelling charges
    • Payment reauthorizations
    • Handling reversals
      • Return basics
        • Digital River coordinated returns
        • Third party coordinated returns
      • Refund basics
        • Issuing refunds
        • Refunding asynchronous payment methods
      • Disputes and chargebacks
    • Customer notifications
    • Responding to events
      • Events
        • Key event types
        • All event types
      • Webhooks
        • Creating a webhook
        • Digital River API safelist
        • Digital River signature
      • Expanding events
      • Preventing webhooks from getting disabled
    • Distributor model
  • Subscription Management
    • Managing a subscription
    • Managing an external subscription
  • Payments
    • Payment solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BNP Paribas
          • Configuring BLIK
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BNP Paribas
      • BLIK
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • Pay with Installments France
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Authorization declines
    • PSD2 and SCA
      • How to ensure SCA compliance
    • Payment testing scenarios
  • Product management
    • Product basics
    • Managing SKUs
    • Using product details
    • Grouping SKUs
    • SKU-inventory item pairs
    • Managing inventory items
    • Regulatory fees
      • What are regulatory fees?
        • Fees terminology
        • Regulatory fee management
        • European regulatory fees
        • Compliance obligations
        • WEEE directive requirements
        • Copyright directive requirements
        • Compliance challenges
      • Managing regulatory fees
  • Customer management
    • Customer basics
    • Creating and updating customers
    • Setting up tax exemptions
    • Recording a customer's request to be forgotten
  • Financial reporting
    • Financials basics
    • Sales transactions
      • Returning a list of sales transactions
      • Getting a sales transaction by ID
    • Sales summaries
      • Returning a list of sales summaries
      • Getting a sales summary by ID
    • Payouts
      • Returning a list of payouts
      • Getting a payout by ID
      • Get a list of transactions included in payout by ID
  • Developer resources
    • Digital River API reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline Refund elements
        • Online Banking elements
        • Tax Identifier element
        • Invoice attribute element
        • Delayed Payment Instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
    • DigitalRiverCheckout.js reference
      • Including DigitalRiverCheckout.js
      • Initializing DigitalRiverCheckout.js
        • DigitalRiverCheckout configuration object
      • DigitalRiverCheckout object
        • Configuring Prebuilt Checkout
          • Performing actions
          • Defining experience
        • Components
          • Configuring components
          • Address component
          • Shipping component
          • Tax identifier component
          • Invoice component
          • Wallet component
          • Payment component
          • Compliance component
          • Order summary component
          • Thank you component
        • Rendering a checkout button
          • Performing actions on the checkout button
        • Determining the checkout's status
      • Accessing country and currency
    • DynamicPricing.js reference
    • Postman collection
  • administration
    • Sign in
    • Digital River Dashboard
      • Digital River Dashboard quick start guide
      • Key features
      • Reset your password
      • Test and production environments
      • Account
        • Adding an account
        • Switching accounts
        • Account access
      • Profile settings
        • Viewing your personal information
        • Changing your password
        • Updating your phone number
        • Enabling multi-factor authentication
      • Finance
        • Payouts
          • Viewing your payout details
          • Filtering your payouts
          • Exporting your payouts
        • Sales summaries
          • Viewing your sales summaries details
          • Filtering your sales summaries
          • Exporting your sales summaries
          • Exporting your sales summary details
        • Transactions
          • Viewing your transaction details
          • Filtering your transactions
          • Exporting your transactions
      • Order management
        • Orders
          • Searching for orders
          • Filtering your orders
          • Viewing the order details
          • Cancelling items
          • Fulfilling items
          • Downloading an invoice
          • Downloading a credit memo
          • Creating shipping labels
          • Recording a customer's request to be forgotten
          • Viewing returns and refunds
          • Creating a return
          • Accepting a return
          • Creating a refund
          • Viewing the order's timeline
        • Checkouts
          • Searching for checkouts
          • Filtering your checkouts
          • Viewing the checkout details
        • Prebuilt Checkout links
          • Generate Prebuilt Checkout links
          • View and work with Prebuilt Checkout link details
          • Add a customer during Prebuilt Checkout
          • Add a product during Prebuilt Checkout
      • Customers
        • Viewing customer details
        • Searching for customers
        • Filtering your customers
        • Editing account information
        • Adding a customer
        • Tax IDs and certificates
          • Adding a tax certificate
          • Adding a tax ID
          • Deleting a tax ID
        • Metadata
          • Adding metadata
          • Editing metadata
        • Manage subscriptions from the Customer Details page
        • Disabling a customer
        • Recording a customer's request to be forgotten
        • Deleting a customer
      • Catalog
        • SKUs
          • Viewing the SKU details
          • Searching for SKUs
          • Filtering your SKUs
          • Adding a SKU
          • Editing a SKU
          • Deleting a SKU
          • Adding a fee to a SKU
          • Editing a fee
          • Deleting a fee
          • Viewing product tariff codes
        • Managing customer subscriptions from Digital River Dashboard
      • Developers
        • API keys
          • Updating your API version
          • Getting your API keys
          • Changing the API version for your key
          • Creating a restricted key
          • Editing a restricted key
          • Deleting a restricted key
          • Rotating keys
        • Webhooks
          • Creating a webhook
          • Editing a webhook
          • Deleting a webhook
          • Rotating a webhook's secret
        • API logs
          • Filtering the API log
          • Viewing the API log details
        • Event logs
          • Filtering the events log
          • Viewing the event details
      • Settings
        • Users and roles
          • Roles
          • Searching for a user by name or email
          • Filtering your users and roles
          • Adding a user
          • Editing a user
          • Deleting a user
        • Prebuilt Checkout
        • Payment methods
          • Viewing your payment methods
          • Viewing payment method details
            • Enabling currencies
            • Managing countries
          • Enabling or disabling a payment method
  • General Resources
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
    • Standards and certifications
      • Certification process
      • Compliance requirements
      • Documentation requirements
      • Integration checklists
        • Admin portal
        • Products and SKUs
        • Customers and tax exemptions
        • Checkouts, payment sources, and orders
        • Disclosures, compliance statements, and emails
        • Fulfillments and cancellations
        • Customer portal
        • Order refund synchronization
        • Reversals
        • Error handling
      • Test and use cases
    • Commerce infrastructure
    • Versioning
    • Glossary
Powered by GitBook
On this page
  • Defining a business model
  • Setting up subscription-based products
  • Defining plans
  • Creating and activating plans
  • Discontinuing and deactivating plans
  • Setting up free trials
  • Defining trial and paid plans
  • Supported payment methods with subscriptions
  • Next steps
  1. Using our services

Subscriptions

Gain a better understanding of Digital River's subscription service along with how to define a business model and set up free trials

PreviousItem classificationNexte-Invoicing

Last updated 3 months ago

Digital River offers a -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 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

Once you create the acquisition 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 page.

Defining a business model

You can share among in the subscription service. We recommend not relying on 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 or to define the of any you intend to offer on a subscription basis.

For more details, refer to and .

Defining plans

The following diagram shows how plans define the behavior of subscriptions that belong to them.

Creating and activating plans

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"
}'
curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
    "state": "active"
}'

Discontinuing and deactivating plans

curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
    "state": "discontinued"
}'
curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
    "state": "deactivated"
}'

If you attempt to create subscriptions that belong to discontinued or deactivated plans, an error is thrown during the acquisition checkout.

{
    "type": "bad_request",
    "errors": [
        {
            "code": "plan_not_active",
            "parameter": "planId",
            "message": "Plan 86a05e42-3b94-4ee5-b2a5-267efd8b3704 is not active."
        }
    ]
}

Setting up free trials

Checkout solution
Article

Defining trial and paid plans

Trial period plans

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 .

Plan
{
    "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
}

Paid period plans

Plan
{
    "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
}

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.

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

Once you've , you should set up that define the behavior of your subscriptions.

At a minimum, you should specify a plan's and terms, designate its , set up , and configure its and .

When you create a plan using the 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.

A 201 Created response contains a unique plan identifier. The request also triggers an with a of plan.created. If the state is draft when you're ready to launch, send its identifier as a path parameter in a and use the request's body to set state to active.

The plan must be active before you can add to it. For details, refer to the and .

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 . 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 request.

Refer to the and for details on how discontinuing or deactivating a plan affects its associated subscriptions.

You can configure a customer's subscription to include a free trial period. This section provides information on 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:

in

in

Once you create the acquisition containing the subscription, you must convert it from trial to paid. For details, refer to .

Before offering free trials, you must configure and deploy plans for your trial .

Refer to for general information on plans and their relationship to subscriptions.

For each subscription you intend to offer on a trial basis, you should define a and . 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:

Your trial period controls the behavior during its first billing cycle.

For free trial plans, set billingOffsetDays to 0. This configuration results in a subscription whose initial billing cycle has the same and , thereby ensuring that the first payment capture attempt occurs after the trial period ends.

The value you give reminderOffsetDays determines when the 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 . If this proves unsuccessful, our will continue making capture attempts for the number of days you specify.

You must also define a paid period that governs the 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.

Refer to the page for a complete list of such payment methods.

In acquisition checkouts, you can combine a primary source with one or more secondary sources. Refer to the page for details on .

Supported payment methods
defining trial and paid plans
Defining plans
trial
paid period plan
Low-code checkouts
Processing subscription acquisitions
Direct Integrations
Handling subscription acquisitions
Prebuilt Checkout
Direct Integrations
Low-code checkouts
Processing subscription acquisitions
Direct Integrations
Handling subscription acquisitions
PSD2 and SCA
Managing a subscription
SKUs
Managing SKUs
Using product details
How to define a business model
How to configure plans for free trials
Using payment methods to fund subscriptions
payment source
Managing sources
built a product catalog
Processing subscription acquisitions
Handling subscription acquisitions
reusable
type
digital products
SKUs
productDetails
basic and compliance data
digital product
Trial subscription acquisitions
Trial subscription acquisitions
order
plans
plans
name
contract length and billing frequency
renewal reminders
billing offset days
collection period days
POST /plans
event
plan's
POST /plans/{planId}
subscriptions
Lifecycle of a plan
Subscription lifecycle
nextInvoiceDate
POST /plans/{planId}
Lifecycle of a plan
Subscription lifecycle
subscriptions
plan
subscription's
nextInvoiceDate
currentPeriodEndDate
billing optimization service
plan
subscription
order
combining primary and secondary payment sources
Trial subscription management
subscription.reminder