Processing subscription acquisitions

Gain a better understanding of how to use Digital River's subscription service to process acquisitions in Prebuilt Checkout and Components

If you're pairing either of Digital River's low-code checkout solutions with our subscription service, this page explains how to process:

• Standard subscription acquisitions

• Trial subscription acquisitions

Once Digital River converts the checkout-session to an order, you must activate the subscription, fulfill the goods, and manage renewals. For details on handling these and other processes, refer to the Managing a subscription page.

Subscription acquisitions

During a standard subscription acquisition, your create checkout-session request must pass subscriptionInfo in items[].

For each items[].subscriptionInfo in the request:

• Use planId to associate the subscription with a plan. For details, refer to Defining a business model.

• Include terms. To do this, get the plan that the subscription belongs to before submitting the request. From the response, retrieve the plan's terms and pass that value in the request. If you don't pass terms, a 400 Bad Request with a code of missing_parameter is returned.

• Set autoRenewal to true or omit the value. If you set this parameter to false, a 400 Bad Request with a code of invalid_request is returned.

• If you don't provide a unique subscriptionId, we generate one for you.

Your request must also pass a customerId and should specify a chargeType of customer_initiated.

Acquisition requests can also contain:

• Multiple items[] with subscriptionInfo

• A mix of both subscription and non-subscription items[]

Multiple items[] with subscriptionInfo

Your create checkout-session request can contain multiple items[] with subscriptionInfo. However, all these recurring items[] have to share the same planId and (if you pass your own value) subscriptionId.

If your request contains multiple items[] with subscriptionInfo and they reference different plans, then the following error is returned:

409 Conflict

{
    "type": "conflict",
    "errors": [
        {
            "code": "plan_limit_reached",
            "parameter": "planId",
            "message": "Only one unique subscription plan can be supported in a checkout"
        }
    ]
}

Mixed subscription and non-subscription items[]

Your create checkout-session request can also have a mix of items[], some with and some without subscriptionInfo. This allows you to, for example, process transactions that combine purchasing a one-time physical product with a recurring digital subscription.

Trial subscription acquisitions

You handle free-trial acquisitions in much the same way as standard subscription acquisitions.

However, in free trials, you must slightly modify your create checkout-session request.

For each trial-based items[] in the request:

• Pass a price or aggregatePrice of 0.0

• In its subscriptionInfo:

  • Set freeTrial to true

  • Pass a planId that references a trial period plan.

If your request contains an items[] whose (1) subscriptionInfo.freeTrial is true and its price or aggregatePrice is greater than 0.0 or (2) whose subscriptionInfo.freeTrial is false and its price or aggregatePrice is 0.0, then the following error is thrown:

400 Bad Request

{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "items",
            "message": "The value of the Free Trial flag is not consistent with the item price or the aggregate price."
        }
    ]
}

For details on processing a trial-based subscription after Digital River converts the acquisition checkout-session to an order, refer to Trial subscription management on the Subscription management page.

How Digital River processes your requests

For each items[] with subscriptionInfo sent in the create checkout-session request, Digital River creates a single subscription, sets its to state to draft and then generates an event with a type of subscription.created.

The event's data.object doesn't contain key subscription attributes such as contractBindingUntil, nextReminderDate, currentPeriodEndDate, and nextInvoiceDate. These are populated after you activate the subscription.

Digital River also presents customers with a localized, recurring billing agreement in the payment collection stage and forces them to accept it before they can submit the order.

Prebuilt Checkout

In Prebuilt Checkout, we retrieve the interval and intervalCount of the plan that the subscription belongs to and present this information in the order summary section.

Payment Component

To make the primary payment sources[] reusable, Digital River saves it to the customer referenced by customerId.

Refer to the Managing a subscription page to learn more about activating subscriptions and handling renewals.