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
  • Subscription acquisitions
  • Creating a subscription
  • Handling the acquisition checkout response
  • Displaying terms and acquiring consent
  • Acquiring payment
  • Managing subscriptions after acquisition
  • Trial subscription acquisitions
  • Managing trial subscriptions after acquisition
  1. Integration options
  2. Direct integrations
  3. Subscription acquisitions

Handling subscription acquisitions

If you're pairing the Direct Integration solution with Digital River's subscription service, learn how to handle acquisitions.

PreviousSubscription acquisitionsNextHandling external subscription acquisitions

Last updated 2 months ago

If you're pairing the checkout solution with , this page explains how to process it:

Once you , you must activate the subscription, fulfill the goods, and manage renewals. Refer to the page for details on handling these and other processes.

Subscription acquisitions

During subscription acquisitions, you must:

  • and

Creating a subscription

In , you define subscriptions in items[]. Checkouts can contain either a single items[] with or. We also support .

For each items[].subscriptionInfo in the request:

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

  • Pass terms. To do this, make a request. From the response, retrieve the terms and use that value to set the line item's terms. If you don't send terms, a 400 Bad Request with a code of missing_parameter is thrown.

For details, refer to .

  • Set to true or omit the value. If you set autoRenewal to false, you receive a 400 Bad Request with a code of invalid_parameter.

  • Use freeTrial to set up trial periods. For details, refer to .

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

curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
	"customerId": "0aa4bb94-2995-4689-9b57-f11d1beb18c9",
	"sourceId": "586ffca0-ca4f-4d87-a933-192afa36cc6b",
	"locale": "en_US",
	"email": "jsmith123@digitalriver.com",
	"currency": "USD",
	"items": [{
			"skuId": "d273122b-e78d-4fcb-a1ab-10c07c871ee7",
			"quantity": 5,
			"price": 5.01,
			...
			"subscriptionInfo": {
				"planId": "460d1943-5ac1-48b8-98e8-237c6e3019a7",
				"terms": "These are the terms...."
			},
			"metadata": {
				"key1_ItemLevel": "tets"
			}
	}],
	...
}'

Checkouts with multiple subscriptions

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

Checkouts with subscription and non-subscription items

A common use case for these mixed checkouts is to process transactions that combine a one-time physical product with a digital subscription service.

Handling the acquisition checkout response

{
    "id": "88aaf811-a8a8-4b7a-9a23-5bc0241e039a",
    "createdTime": "2021-08-11T20:06:32Z",
    "customerId": "0aa4bb94-2995-4689-9b57-f11d1beb18c9",
    "currency": "USD",
    "email": "jsmith123@digitalriver.com",
    "billTo": {
        "address": {
            "line1": "10380 Bren Road West",
            "city": "Minnetonka",
            "postalCode": "55343",
            "state": "MN",
            "country": "US"
        },
        "name": "Digital Development",
        "email": "testdummy@digitalriver.com",
        "organization": "DR",
        "additionalAddressInfo": {
            "neighborhood": "Centro"
        }
    },
    "totalAmount": 26.9,
    "subtotal": 25.05,
    "totalFees": 0.0,
    "totalTax": 1.85,
    "totalImporterTax": 0.0,
    "totalDuty": 0.0,
    "totalDiscount": 0.0,
    "totalShipping": 0.0,
    "items": [
        {
            "id": "b0ae5bf9-6df7-4185-91f2-7e2589acbe8d",
            "skuId": "d273122b-e78d-4fcb-a1ab-10c07c871ee7",
            "amount": 25.05,
            "quantity": 5,
            "metadata": {
                "key1_ItemLevel": "tets"
            },
            "tax": {
                "rate": 0.07375,
                "amount": 1.85
            },
            "importerTax": {
                "amount": 0.0
            },
            "duties": {
                "amount": 0.0
            },
            "subscriptionInfo": {
                "subscriptionId": "192a2549-8b16-482e-b1bb-b4a64cd6a0c0",
                "planId": "460d1943-5ac1-48b8-98e8-237c6e3019a7",
                "terms": "Please accept terms",
                "autoRenewal": true,
                "freeTrial": false
            },
            "fees": {
                "amount": 0.0,
                "taxAmount": 0.0
            }
        }
    ],
    "updatedTime": "2021-08-11T20:06:32Z",
    "locale": "en_US",
    "customerType": "individual",
    "sellingEntity": {
        "id": "C5_INC-ENTITY",
        "name": "DR globalTech Inc."
    },
    "liveMode": false,
    "payment": {
        "sources": [
            {
                "id": "586ffca0-ca4f-4d87-a933-192afa36cc6b",
                "type": "creditCard",
                "amount": 26.9,
                "owner": {
                    "firstName": "Digital",
                    "lastName": "Development",
                    "email": "testdummy@digitalriver.com",
                    "address": {
                        "line1": "10380 Bren Road West",
                        "city": "Minnetonka",
                        "postalCode": "55343",
                        "state": "MN",
                        "country": "US"
                    },
                    "organization": "DR",
                    "additionalAddressInfo": {
                        "neighborhood": "Centro"
                    }
                },
                "creditCard": {
                    "brand": "Visa",
                    "expirationMonth": 7,
                    "expirationYear": 2027,
                    "lastFourDigits": "1111"
                }
            }
        ],
        "session": {
            "id": "9fb4036f-5051-4255-9189-16e449d69ca6",
            "amountContributed": 26.9,
            "amountRemainingToBeContributed": 0.0,
            "state": "requires_confirmation",
            "clientSecret": "9fb4036f-5051-4255-9189-16e449d69ca6_3c6275e8-e065-4bb9-b75a-829f62b78c2c"
        }
    }
}
{
    "id": "7f784dd8-a76f-4d3a-84e1-abdc9c7ac3b9",
    "createdTime": "2022-02-07T14:02:46Z",
    "updatedTime": "2022-02-07T14:02:46Z",
    "stateTransitions": {},
    "taxInclusive": false,
    "currency": "USD",
    "planId": "82cbf763-fa27-401a-aa69-5e6640539ce7",
    "state": "draft",
    "items": [
        {
            "price": 100.0,
            "skuId": "bd933514-43fa-40d3-863c-8ff6fce0db76",
            "quantity": 1
        }
    ],
    "liveMode": false
}

Displaying terms and acquiring consent

Acquiring payment

During acquisition checkouts, you can give customers the option to:

Creating a new payment source

let digitalriverpayments = new DigitalRiver("pk_hc_a209389e4588433bb6e00b32466b82c3", {
    "locale": "en_US"
});

let configuration = { 
    "sessionId": "2bc96772-1142-4289-9d20-f6905591d7e4",
    "options": {
        "flow": "checkout",
        "showComplianceSection": true,
        "showSavePaymentAgreement": false,
        "showTermsOfSaleDisclosure": true,
        "usage": "subscription"
    }
    ...
}

let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");
{
    "paymentMethodTypes": [
        "creditCard",
        "payPalBilling",
        "googlePay",
        "klarnaCreditRecurring",
        "msts"
    ]
}

Each payment method, accompanied by the subscription's terms and conditions, is displayed in the modal window.

...
digitalRiver.retrieveAvailablePaymentMethods({
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
    //do something with the result
    console.log(result)
});
...

If the request is successful, the response contains the payment methods that apply to the transaction.

Available payment methods
[
    {
        "type": "creditCard",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Credit Card",
        "localizedDisplayName": "Credit Card"
    },
    {
        "type": "payPalBilling",
        "flow": "redirect",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "PayPal Billing",
        "localizedDisplayName": "PayPal"
    },
    {
        "type": "googlePay",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Google Pay",
        "localizedDisplayName": "Google Pay"
    }
]
  • Set type to the payment method selected by the customer

var payload = {
    "type": "creditCard",
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1",
    "futureUse": true,
    "usage": "subscription",
    ...
    "mandate": {
        "terms": "By checking the box below and completing your purchase..."
    }
}

digitalriver.createSource(payload).then(function(result) {
    if (result.error) {
        //handle errors
    } else {
        var source = result.source;
        //send source to back end
        sendToBackend(source);
    }
});

Authenticating a saved payment source

...
digitalRiver.retrieveAvailablePaymentMethods({
    "sessionId": "1c86a97f-45ea-4d73-8c99-ca533e392ab1"
}).then(function(result) {
    //do something with the result
    console.log(result)
});
...
Available payment methods
[
    {
        "type": "creditCard",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Credit Card",
        "localizedDisplayName": "Credit Card"
    },
    {
        "type": "payPalBilling",
        "flow": "redirect",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "PayPal Billing",
        "localizedDisplayName": "PayPal"
    },
    {
        "type": "googlePay",
        "flow": "standard",
        "supportsRecurring": true,
        "supportsFreeTrial": true,
        "images": {
            "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
        },
        "supportsStorage": true,
        "defaultMandate": {
            "terms": "I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur at a future date."
        },
        "displayName": "Google Pay",
        "localizedDisplayName": "Google Pay"
    }
]
{
    "id": "533319260336",
    ...
    "sources": [
        {
            "id": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
            ...
            "type": "creditCard",
            "reusable": true,
            "state": "chargeable",
            ...
            "clientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
            ...
        },
        {
            "id": "19f47eba-418f-41b3-882c-462e335770e7",
            ...
            "type": "payPalBilling",
            "reusable": true,
            "state": "chargeable",
            ...
            "clientSecret": "19f47eba-418f-41b3-882c-462e335770e7_cc871d23-474d-4a3f-9803-4e98fa39f2ee",
            ...
        }
    ],
    ...
}
{
    "id": "50a72152-4a61-4e4a-b9e1-2ab5db891105",
    ...
    "payment": {
        "session": {
            "id": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
            ...
        }
    }
}
...
digitalriver.authenticateSource({
    "sessionId": "f5dd814a-ecee-4f7e-bf7c-4635f0c19c91",
    "sourceId": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
    "sourceClientSecret": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc_bf74c04c-8586-41e2-964a-f5e618d2b7e3",
    "returnUrl": "https://mypage.com"
});
...

Managing subscriptions after acquisition

Trial subscription acquisitions

POST /checkouts
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
...
--data-raw '{
    "customerId": "563089630336",
    "sourceId": "8687447b-a04d-4838-af6c-0de0810f23a7",
    "locale": "en_US",
    "email": "jdoe@digitalriver.com",
    "currency": "USD",
    "items": [
        {
            "skuId": "sku_3e5ab173-d52e-4d9e-8888-2a00f6bb188e",
            "quantity": 2,
            "price": 0.0,
            "subscriptionInfo": {
                "planId": "186cf07e-a1ea-4ec0-9d9a-8aa93b3af43a",
                "terms": "The terms of the subscription",
                "autoRenewal": true,
                "freeTrial": true
            }
        }       
    ]
}'

If you create or update a checkout and (1) freeTrial is true and price or aggregatePrice contain a value that's greater than 0.0 or (2) freeTrial is false and price or aggregatePrice are 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."
        }
    ]
}

Managing trial subscriptions after acquisition

In subscription acquisitions, make sure you also set the checkout's to customer_initiated.

can contain multiple with . All the recurring items, however, must share the same planId and (if you set the value) subscriptionId. Once you submit the request, Digital River adds these line items to a single subscription.

If you attempt to with multiple items[] that reference different plans, then the following error is returned:

Digital River's subscription service supports building checkouts containing subscription and non-subscription line items and successfully . However, the subscription line items must all .

After you submit the request, Digital River creates a , sets it to state to draft and then generates an with a of .

In the response's body and the event's data.object, the uniquely identifies that subscription. At a minimum, make sure you persist this value.

At this point, no additional subscription line items can be added to the checkout. Furthermore, you're restricted to .

Since Digital River's subscription service doesn't support manual renewals, always returns true .

Refer to the page for details on how to handle manual renewals, where you invite customers to actively renew subscriptions at a designated time.

If you , you'll notice that key fields have yet to be populated at this stage of the acquisition process. This is because the subscription's state is still draft and the contractBindingUntil, nextReminderDate, currentPeriodEndDate, and nextInvoiceDate are generated when you .

During acquisitions, you must disclose a subscription's terms and then acquire the customer's active acceptance of them. How you do this depends on whether you use or . In either case, the should match those displayed to customers.

For required disclosures, see the article (refer to for access information).

A subscription's terms are displayed in the modal window if you're using . For details, see the on this page.

If you're using , present our standardized subscription terms and save the payment agreement by calling the , retrieving autorenewalPlanTerms.localizedText and then displaying that text with an appropriate acceptance control.

Your code should be written so customers can accept these terms before the checkout can proceed. You can then use autorenewalPlanTerms.localizedText to set mandate.terms in the method's configuration object.

After you , the subscription's terms are stored in the .

or

How you create a payment to fund a recurring transaction depends on whether your integration uses or .

For more details, refer to the on the page.

After , configure :

Use the checkout's to set sessionId

If your integration sends the customer's billing information in the billTo, then it's not necessary to pass billingAddress

In , set:

to checkout

to true

to subscription

to true and to false. These two settings (along with the value of true), prompt Drop-in payments to display the combined autorenewal and save payment agreement.

Pass the configuration object to createDropin()and in the appropriate container. If the request is successful, returns the transaction's eligible payment methods:

If customers click the without agreeing to the terms, Drop-in prevents the transaction from proceeding.

If customers consent to the terms and submit their payment information and the resulting create source request is successful, then the event's data contains a that is and . The object also contains the agreed-upon terms (mandate.terms) and the time the customer accepted those terms (mandate.signedTime).

For details, refer to the and the .

After , send the checkout's to your front end and use it to set sessionId in the configuration object of .

Based on these payment methods, to collect the customer's sensitive payment information.

After customers select a payment method, , and submit their payment information, configure :

Use the checkout's to set sessionId.

Set to subscription and futureUse to true

Use the to set mandate.terms

If your integration passes a customer's billing information in the billTo, then it's not necessary to send billingAddress

If the create source request is successful, the response contains a that is and .

For more information, refer to the .

Next, send the identifier and to your backend.

Submit a POST /customers/{customerId}/sources/{sourceId} to attach the source to the customer. This flips the source's attribute to true You can usethe object in both the subscription's acquisition and as the designated source in renewals.

Once saved to the customer, your integration should .

You should also retrieve mandate.terms from the source and use this value to set each of the . This ensures that the subscription's terms are added to the .

do not currently support retrieving saved payment methods.

If you give customers the option to select a saved payment source during subscription acquisitions, then after , send the to your front end and use it to set sessionId in the configuration object of .

For each payment method contained in the response, determine if its type matches the type of one or more of the sources[]. If it does, you can retrieve those saved sources[] from the and display them as options on your payments page.

If the customer selects a saved source, passes its sources[].id and sources[].clientSecret (along with the checkout's ) to . This method determines whether is required.

If the response status is complete or authentication_not_required, the method resolves, allowing your integration to .

For additional details, refer to the section on on the page.

After you , you'll need to activate the subscription and process renewals. To learn more, refer to the page.

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

In , however, you must configure the checkout slightly differently.

Once customers initiate checkout, determine whether their cart contains trial-based subscription products. If it does, use items[].subscriptionInfo to describe those products in your .

You can also add non-trial subscription products, as well as non-subscription products, to the same checkout. All the subscription line items, however, must reference the same plan. For details, refer to .

Each trial-based subscription line item in the request must specify a price of 0.0, set freeTrial to true, and pass a planId that references a .

Refer to on the page for details on how to process a trial subscription after you .

chargeType
Third party subscription services
Drop-in payments integration guide
Drop-in payments builder tool
Elements integration guide
Drop-in payments
Drop-in payments
Acquiring payment section
createSource()
Create a new payment source
Authenticate a saved payment source
agreed-upon terms
standard acquisitions
Checkouts with multiple subscriptions
Direct Integrations
Digital River's subscription service
Managing a subscription
subscriptionInfo
Standard subscription acquisitions
Free trial subscription acquisitions
Create a subscription
handle the response
Display terms and acquire consent
Obtain payment information
multiple subscription line items
mixed cart checkouts
Displaying terms and acquiring consent
Trial subscription acquisitions
items[]
subscriptionInfo
Drop-in payments
DigitalRiver.js with elements
Subscriptions and Auto-Renewal Considerations
DigitalRiver.js with elements
Drop-in payments
DigitalRiver.js with elements
Building payment workflows
strong customer authentication
Building payment workflows
Managing a subscription
Managing a subscription
reference the same plan
building a checkout with subscription information
building a checkout with subscription information
accept the terms
building a checkout with subscription information
subscriptionId
autoRenewal
free trials
trial period plan
type
autoRenewal
Defining a business model
billing agreement
autoRenewal
items[].subscriptionInfo.terms
billing agreement
converting those checkouts to orders
convert an acquisition checkout to an order
convert the checkout to an order
convert the checkout to an order
convert the checkout to an order
what product information can be updated
Learning tools
subscription.created
get compliance details method
create the appropriate elements
createSource()
usage
createDropin()
options
flow
showComplianceSection
usage
mount Drop-in payments
onReady
configurable continue button
reusable
subscriptions section
retrieving saved payment sources during subscription acquisitions
checkouts
GET /plans/{planId}
plan's
Checkouts
create checkouts
POST/ checkouts
subscription
event
plan's
terms
source
checkout's
showTermsOfSaleDisclosure
showSavePaymentAgreement
checkout's
onSuccess
readyForStorage
chargeable
source
checkout's
readyForStorage
chargeable
source
customer
source
checkout's
customer's
customer
POST /checkouts
retrieveAvailablePaymentMethods()
retrieveAvailablePaymentMethods()
authenticateSource()
retrieve the subscription
payment session identifier
payment session identifier
payment session identifier
payment session identifier
payment session identifier
attach the source to the checkout
attach the authenticated source to the checkout
activate the subscription
Trial subscription management