# Handling external subscription acquisitions
If you're not using [our subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), you can still use the Digital River APIs and [DigitalRiver.js](https://docs.digitalriver.com/digital-river-api/developer-resources/reference) to handle recurring billing, display and acquire acceptance of a subscription's terms, and comply with [PSD2 and SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) mandates.
Integrations that use a third-party subscription service can:
* Supply an upstream [subscription identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#subscription-identifier)
* Use [billing agreements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreements) to maintain SCA compliance
* Flag a subscription as a [free trial](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#free-trial)
* Use the [auto renewal flag](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to ensure that appropriate payment methods are displayed
* Persist a subscription's [terms and conditions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms)
* Specify a subscription's [start time and end time](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#start-and-end-time).
## Building a subscription acquisition
During subscription acquisitions, you need to:
* [Configure the checkout](#configure-the-checkout)
* [Acquire acceptance of the autorenewal terms](#handling-the-autorenewal-terms)
* [Handle the subscription's payment](#handling-payments)
* [Submit the payment authorization request](#submitting-the-acquisition-authorization-request)
* [Notify customers of the acquisition](#notifying-customers-of-a-subscription-acquisition)
### Configure the checkout
Before [order creation](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), a subscription acquisition [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)must contain:
* A `customerId` that references an existing [customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers).
* A [primary payment `sources[]`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) that is [reusable ](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use)and saved to the referenced [customer](https://app.gitbook.com/s/nfnsRxm5nOCJKXwnr6Qv/customers).
* A [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) that is [`customer_initiated`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/initiating-a-charge#customer-initiated), thereby indicating that the customer actively participates in the acquisition process.
In addition, each [`items[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) in the [checkout](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) that has [`subscriptionInfo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1):
* Can use [SKUs](https://docs.digitalriver.com/digital-river-api/product-management/skus#skus) or [`productDetails`](https://docs.digitalriver.com/digital-river-api/product-management/skus#product-details) to represent a [digital or physical product](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital)
* Must set [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to `true`
* Must contain the subscription's [`terms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms)
{% tabs %}
{% tab title="Checkout" %}
```
{
"id": "7e5e832a-0c78-43e1-b136-ced8c156f5b8",
"createdTime": "2022-04-07T20:49:49Z",
"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": "e782d614-1444-4e37-a103-d9726288e0ce",
"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": {
"terms": "Subscription terms accepted by the customer",
"autoRenewal": true,
"freeTrial": false
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"updatedTime": "2022-04-07T20:49:49Z",
"locale": "en_US",
"customerType": "individual",
"chargeType": "customer_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": "965db940-51f6-4f53-bc07-1052ef0d4c32",
"amountContributed": 10.0,
"amountRemainingToBeContributed": 0.0,
"state": "requires_confirmation",
"clientSecret": "965db940-51f6-4f53-bc07-1052ef0d4c32_f9eae301-588a-409c-9d29-3358f19dca4f"
}
}
}
```
{% endtab %}
{% endtabs %}
### Acquiring acceptance of the autorenewal terms
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're using [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) or [DigitalRiver.js with Elements](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).
{% hint style="info" %}
For more details on required disclosures, refer to the [Subscriptions and Auto-Renewal Considerations](https://digitalriver.service-now.com/kb?id=kb_article_view\&sysparm_article=KB0010508) article (refer to [Learning tools](https://docs.digitalriver.com/digital-river-api/general-resources/standards-and-certifications/compliance-requirements#accessing-the-learning-tools) for access information).
{% endhint %}
{% tabs %}
{% tab title="Drop-in payments" %}
In [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts), set each subscription line item's [`autoRenewal`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#auto-renewal) to `true`. In the [`createDropin()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-an-instance-of-drop-in) method's configuration [`options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1), set [`showTermsOfSaleDisclosure`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#show-terms-of-sale-disclosure) to `true`.
These settings prompt [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) to display the combined autorenewal and save payment agreement.
If customers click the [configurable continue button](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#customizing-the-text-of-the-drop-in-button) without agreeing to the terms, Drop-in prevents the transaction from proceeding.
If the customer consents and a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is successfully created, then the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) event's `data` contains the agreed-upon terms (`mandate.terms`) and the time the customer accepted those terms (`mandate.signedTime`).
{% endtab %}
{% tab title="DigitalRiver.js" %}
If you're using DigitalRiver.js, you can present our standardized subscription terms and save the payment agreement by calling the [get compliance details method](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriver-compliance-getdetails-businessentitycode-locale), 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 should then pass `autorenewalPlanTerms.localizedText` to `mandate.terms` in the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method's configuration object.
{% endtab %}
{% endtabs %}
If you configure your workflow correctly, then the customer-accepted autorenewal terms are returned in the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) event's `data` or the response to the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method.
In either case, retrieve `mandate.terms` and use this value to set each of the [checkout's ](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/checkouts)[`items[].subscriptionInfo.terms`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#terms). This ensures that the subscription's terms are added to the [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreement-identifier).
### Handling payments
Customers can create a new source or authenticate a saved source to fund a recurring transaction.
For details, refer to the [subscription section](https://docs.digitalriver.com/digital-river-api/integration-options/building-you-workflows#subscription) on the[ Building payments workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page.
### Submitting the acquisition authorization request
Once the checkout's [`payment.session.state`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/payment-sessions#session-state) is [`requires_confirmation`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/payment-sessions#requires_confirmation), and all [address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#address-requirements-and-validations) are met, [submit the create order request](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier). At that point, Digital River generates a [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscription-information-1#billing-agreement-identifier) and returns its `billingAgreementId` in the response.
{% tabs %}
{% tab title="Order" %}
```javascript
{
"id": "188817490336",
"customerId": "533134230336",
...
"items": [
{
"id": "110359190336",
"skuId": "0181a7a9-610e-48c5-89e5-84ca06c69f03",
...
"subscriptionInfo": {
"terms": "Subscription terms accepted by the customer",
"autoRenewal": true,
"freeTrial": false,
"billingAgreementId": "c567f049-9ec4-4c63-829b-efe01427a8a9"
},
...
}
],
...
"state": "accepted",
...
"checkoutId": "50a72152-4a61-4e4a-b9e1-2ab5db891105"
}
```
{% endtab %}
{% endtabs %}
### Notifying customers of a subscription acquisition
When the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)[`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)is [`accepted`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders), notify customers that their subscription acquisition has been successfully processed. In the [Subscription Notifications](https://digitalriver.service-now.com/kb?id=kb_article_view\&sysparm_article=KB0012073) article (*refer to* [*Learning tools*](https://docs.digitalriver.com/digital-river-api/general-resources/standards-and-certifications/compliance-requirements#accessing-the-learning-tools) *for access information*), you can find a complete list of what is required in this notification.
## Next steps
For details on auto-renewals and updates, refer to [Managing an external subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-an-external-subscription).
---
# 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/integration-options/checkouts/subscriptions/third-party-coordinated-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.