# Managing a subscription
If you're using [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), you must manage the subscription after completing the acquisition checkout process. On this page, you'll find information on how to:
* [Activate the subscription](#activating-a-subscription)
* [Fulfill the goods](#fulfilling-the-acquisition)
* [Notify customers of a successful acquisition](#notifying-customers-of-a-subscription-acquisition)
* [Renew subscriptions](#renewing-subscriptions)
* [Manage trial subscriptions](#trial-subscription-management)
* [Modify a subscription's payment source](#modifying-subscription-payments)
## Activating a subscription
After the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)[`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)moves to `accepted`, you can activate a [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics). To do this, retrieve each `items[].subscriptionInfo.subscriptionId` from the [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) of the [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 [`order.accepted`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#order.accepted) and send it as a path parameter in a [`POST /subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-id-1).
{% hint style="info" %}
If you're using the [Direct Integrations](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts) checkout solution, you could also get each `items[].subscriptionInfo.subscriptionId` from the body of the [`POST/ orders` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1)response.
{% endhint %}
In the body of the request, set `state` to `active`.
```
curl --location --request POST 'https://api.digitalriver.com/subscriptions/DR_3ce5dc58-6bba-4ee2-b8d1-e1b974a4fe93' \
...
--data-raw '{
"state": "active"
}'
```
No other values can be sent in the body of this request. If you attempt to do so, then the following error is returned:
{% tabs %}
{% tab title="409 Conflict" %}
```javascript
{
"type": "conflict",
"errors": [
{
"code": "restricted_update",
"parameter": "metadata",
"message": "Additional data cannot be updated when updating state to active."
}
]
}
```
{% endtab %}
{% endtabs %}
You can activate a subscription any time after an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` moves to `accepted`. For example, if you're selling a digital service subscription that requires no provisioning, you might build your integration so that the activation request is immediately submitted. In other scenarios, such as when a customer must install and initialize a device, you may decide to build a delay into the activation process.
When you activate the subscription, we search the acquisition [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)for the [primary payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources), retrieve its identifier, and assign that value to `sourceId` in the [subscription object](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics). We will [create a charge](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#how-a-charge-is-created) on the [next invoice date](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice) and attempt to [capture payment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#captures) using this reusable source.
After activation, the following [key subscription attributes](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics) are populated: `contractBindingUntil`, `nextReminderDate`, `currentPeriodEndDate`, `nextInvoiceDate`, and `activated`.
Every subscription contains a `billingAgreementId` that references a [billing agreement](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1#billing-agreements). For [PSD2 and SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) compliance purposes, we continue to associate this billing agreement with the subscription throughout the [subscription's lifecycle](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle).
{% tabs %}
{% tab title="Subscription after activation" %}
```javascript
{
"id": "47ce1ba0-a548-40a2-a601-a43c41fbe68f",
"contractBindingUntil": "2023-02-09T17:40:56Z",
"createdTime": "2022-02-09T17:40:21Z",
"updatedTime": "2022-02-09T17:40:56Z",
"stateTransitions": {
"activated": "2022-02-09T17:40:56Z"
},
"billingAgreementId": "8f1ef7b9-e5c5-46d1-ac14-1c9d566f0f57",
"customerId": "562799360336",
"sourceId": "1fc4353a-e1ab-476b-8ebd-db181c1a21a7",
"taxInclusive": false,
"currency": "USD",
"planId": "82cbf763-fa27-401a-aa69-5e6640539ce7",
"state": "active",
"items": [
{
"price": 100.0,
"skuId": "865a15d2-4e00-4c09-8813-7b82a078491b",
"quantity": 1
}
],
"currentPeriodEndDate": "2022-03-09T17:40:56Z",
"nextInvoiceDate": "2022-03-04T17:40:56Z",
"nextReminderDate": "2022-02-27T17:40:56Z",
"liveMode": false
}
```
{% endtab %}
{% endtabs %}
## Fulfilling the acquisition
Once the [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)`state` is [`accepted`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders), you should fulfill the goods and then [submit the payment capture request](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment).
## Notifying customers of a subscription acquisition
Once a subscription is successfully acquired, you can use the [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 [`order.accepted`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#order.accepted) to trigger an [acquisition confirmation notification](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#acquisition-confirmation).
## Renewing subscriptions
On a [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)[`nextReminderDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-reminder), make sure you [send a renewal reminder to customers](#sending-a-reminder). Your integration should also handle both [successful](#handling-successful-renewals) and [failed](#handling-failed-renewals) billing attempts.
### Sending a reminder
Before attempting to collect a recurring payment, our subscription service determines whether the necessary preconditions are met. If they are, the service opens a [`draft` invoice](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states) and, on the subscription's[ ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)[`nextReminderDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-reminder), creates an [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder).
{% hint style="info" %}
You can configure when you receive this event by setting the plan's [`reminderOffsetDays`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#renewal-reminders).
{% endhint %}
The event's [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) contains the [`subscription` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)along with an [`invoice`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices).
Use the event's data to obtain the customer's contact information and populate your [renewal reminder notification](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#renewal-reminder). This notification (typically an email) should include the subscription's name and a description of its goods, the amount the customer will be charged, and the upcoming billing date.
{% hint style="success" %}
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) includes a complete list of renewal reminder requirements.
{% endhint %}
In `invoice.items[].productDetails` you can access the subscription's product data (such as `name`, `description`, `image`, and `url`) and pass this information to customers in the notification, informing them of what they're being billed for.
{% hint style="info" %}
For details, refer to [How Digital River returns product data](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items#how-digital-river-returns-product-data).
{% endhint %}
There are numerous ways to build your notification. However, we suggest converting any [date-time values](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#dates-and-times) into a more human-readable form. The following are some (partial) examples of what you might add:
*This is a reminder that your* `invoice.description` *subscription is set to renew on or after* `nextInvoiceDate`*. To ensure that your subscription continues without interruption, your* `creditCard.brand` *credit card ending in* `creditCard.lastFourDigits` *will be charged* `invoice.totalAmount` *in* `invoice.currency` *.*
For digital services (such as SaaS), you might also want to include the date and time that customers activated their subscription:
*You activated your subscription via our online store on* `stateTransitions.activated`*.*
Additionally, we suggest you use the reminder event to determine whether the subscription's designated credit card will expire before the [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice). If this is the case, remind customers to update their payment information and provide a link to the appropriate page on your site. For example:
*We noticed that your credit card ending in* `lastFourDigits` *is set to expire* `expirationMonth` *,* `expirationYear`*. This expiration date is prior to your next recurring payment on* `nextInvoiceDate`*. To avoid disruptions to your subscription, please visit your* [*account management page*](https://www.company.com) *and update your payment information.*
### Handling successful renewals
To be notified of a successful billing attempt, [configure a webhook](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks/creating-a-webhook) to listen for the [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.extended`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.extended).
The event's [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) contains the [`subscription` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)along with the [`invoice` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices)used to capture[ payment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#captures). Since settlement has successfully occurred, the invoice's [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)is `paid`.
You could handle `subscription.extended` by calling a function that moves the subscription in your system into a ready to fulfill state and then initiates the fulfillment process.
The event should also trigger a [renewal confirmation message](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#renewal-confirmation) sent to the customer. The following is a partial list of the data you might retrieve from the event and pass in this notification:
* `orderId`: Gives customers access to the identifier of the transaction's [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders).
* `nextInvoiceDate`: Provides customers with the date of the [next billing attempt](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice).
* `name` and `image` in `items[].productDetails`: Reminds customers what products and/or services are included in the subscription.
* `payment.sources[]`: Contains [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) data that you can share with customers so they have basic information on the payment method funding the subscription.
* `totalAmount` and `totalTax`: Informs customers how much they were charged and taxed. The event also contains similar amounts at the `items[]`-level.
{% hint style="info" %}
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) provides a comprehensive list of the information you must include in the renewal notification.
{% endhint %}
### Handling failed renewals
To be notified of renewal problems, you can [configure a webhook(s)](https://docs.digitalriver.com/digital-river-api/administration/dashboard/developers/webhooks/creating-a-webhook) to listen for:
* [Invalid sources and lapsed subscriptions](#invalid-sources-and-lapsed-subscriptions)
* [Payment failures](#subscription.payment_failed)
* [Subscription failures](#subscription.failed)
#### Invalid sources and lapsed subscriptions
If Digital River can't create a billing [invoice ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices)because there's a problem with the [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)saved [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) (in the case of credit cards, this is often an invalid expiration date), then we create an [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.invalid_source`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.source_invalid).
We recommend handling it by informing shoppers that their subscription is at risk of cancellation, requesting a different payment method from them, and then, assuming they provide this information, [updating the subscription's source](#modifying-subscription-payments).
If you don't make this update during the grace period (i.e., the [`collectionPeriodDays` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#collection-period-days)of the subscription’s [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)), then Digital River moves the subscription’s [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)to `lapsed` and creates [`subscription.lapsed`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.lapsed).
Since this is a terminal `state`, reactivating the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)isn't possible, so you'll likely want to discontinue customers' access to the service and provide instructions on restoring it.
#### Payment failures
An [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.payment_failed`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.payment_failed) indicates that Digital River's [autorenewal service](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-billing) failed to [capture payment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#captures).
The event's [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) contains both the `subscription` and the `invoice`.
The [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) most likely stems from changes to the subscription's [payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources). For example, if a [credit card](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/credit-cards) funds a subscription, its billing address could have changed, the customer might have cancelled it, or it might have reached its credit limit.
However, since the [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)of the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)remains `activePendingInvoice`, you might still be able to collect payment.
Whatever the structure of your [dunning process](https://en.wikipedia.org/wiki/Dunning_\(process\)), we recommend you handle [`subscription.payment_failed`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.payment_failed) by using the event's `data.object` to construct a [billing failed notification](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#billing-failed-notification) that:
* Informs customers of the failed payment capture attempt. For example:\
\
\&#xNAN;*We were unable to charge your* `creditCard.brand` *ending in* `creditCard.lastFourDigits`*.*\\
* Provides a link to a page on your site where customers can resolve the issue. For example:\
\
\&#xNAN;*To avoid disruptions to your subscription, please visit your* [*account management page*](https://www.company.com)*.*\\
* Provide your contact information. For example:\
\
\&#xNAN;*If you have any questions, visit our support site at \, contact us at \, or call \.*
If customers click the link, redirect them to a page where they can provide a new payment method.
{% hint style="info" %}
For details, refer to [Account management flows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows#account-management-flows) on the [Building payment workflows](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) page.
{% endhint %}
Once you create a new [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)or [authenticate an existing source](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#authenticating-sources), you must [associate it with the customer](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#attaching-sources-to-customers).
You'll also need to pass the source's identifier in the body of an [update subscription request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id-1).
```
curl --location --request POST 'https://api.digitalriver.com/subscriptions/9a1f34b3-a5f5-4c5d-ab04-9a021b97a26d' \
...
--header 'Authorization: Bearer ' \
...
--data-raw '{
"sourceId": "19f15727-0712-473a-8b78-cc627efc0dfc"
}'
```
Before the next billing attempt, Digital River will void the invoice we couldn't collect and create a new one using the subscription's updated source.
#### Subscription failures
An [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.failed`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.failed) indicates that our autorenewal service could not [capture payment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#captures) during the [designated collection period](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#collection-period-days). As a result, the [invoice ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices)has become `uncollectible` and the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)has moved into a terminally [`failed` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)state.
We recommend you handle [`subscription.failed`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.failed) by setting the subscription status in your system to failed as well.
You should also [send customers a failure notification](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#subscription-failed-notification) that allows them to reactivate their subscription. If customers select this option, you'll need to take them through the acquisition process again.
For example, the notification might:
* Inform customers of the failed renewal.\
\
\&#xNAN;*Despite repeated attempts, we were unable to charge your designated payment method, and as a result, your subscription has been deactivated.* \\
* Provide a link to the page on your site where customers can resolve the issue.\
\
\&#xNAN;*To reactivate your subscription, please visit your* [*account management page*](https://www.company.com)*.* \\
* Provide your contact information.\
\
\&#xNAN;*If you have any questions, visit our support site at \, contact us at \, or call \.*
## Trial subscription management
In this section, you'll find information on:
* [Activating trial subscriptions](#activating-trial-subscriptions)
* [Handling trial conversions](#handling-trial-conversions)
* [Ending trial subscriptions](#ending-trial-subscriptions)
* [Extending free trial periods](#extending-free-trial-periods)
* [Reverting to a free subscription](#reverting-to-a-free-subscription)
### Activating trial subscriptions
You can use the same process to activate both trial and non-trial subscriptions. For details, refer to [Activating a subscription](#activating-a-subscription).
```javascript
curl --location --request POST 'https://api.digitalriver.com/subscriptions/124eeee4-6cf4-40e9-94a6-cba64798fc42' \
...
--data-raw '{
"state": "active"
}'
```
Once activated, a free trial subscription's [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)transitions from `draft` to `activeFree` and the `activatedFree` timestamp is populated.
{% code title="Subscription " %}
```javascript
{
"id": "124eeee4-6cf4-40e9-94a6-cba64798fc42",
"contractBindingUntil": "2022-02-18T15:03:12Z",
"createdTime": "2022-02-11T15:01:31Z",
"updatedTime": "2022-02-11T15:03:12Z",
"stateTransitions": {
"activatedFree": "2022-02-11T15:03:12Z"
},
"billingAgreementId": "6e4d986e-c054-43e0-a233-d6c1e9f60765",
"customerId": "563089630336",
"sourceId": "8687447b-a04d-4838-af6c-0de0810f23a7",
"taxInclusive": false,
"currency": "USD",
"planId": "186cf07e-a1ea-4ec0-9d9a-8aa93b3af43a",
"locale": "en_US",
"state": "activeFree",
"items": [
{
"price": 0.0,
"skuId": "sku_3e5ab173-d52e-4d9e-8888-2a00f6bb188e",
"quantity": 2
}
],
"currentPeriodEndDate": "2022-02-18T15:03:12Z",
"nextInvoiceDate": "2022-02-18T15:03:12Z",
"nextReminderDate": "2022-02-15T15:03:12Z",
"liveMode": false
}
```
{% endcode %}
#### Updating the subscription's price and plan
Immediately following a successful [activation request](#activating-trial-subscriptions), we recommend that your integration use a `POST /subscriptions/{id}` to (1) update the subscription's `planId` so that it references a [paid period plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#paid-period-plans) and (2) for each `items[]`, set the `price` or `aggregatePrice` equal to the post-trial period amount that customers agreed to pay during the subscription acquisition process.
{% code title="POST/ subscriptions/{subscriptionId}" %}
```javascript
curl --location --request POST 'https://api.digitalriver.com/subscriptions/124eeee4-6cf4-40e9-94a6-cba64798fc42' \
...
--data-raw '{
"planId": "f55d07a2-a78f-406a-b6c6-ad8e1cc1531b",
"items": [
{
"price": 29.95,
"skuId": "sku_3e5ab173-d52e-4d9e-8888-2a00f6bb188e",
"quantity": 2
}
]
}'
```
{% endcode %}
After you submit this request, the [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)`planId` references the [paid period plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#paid-period-plans). However, until [`currentPeriodEndDate` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#current-period-end-date)elapses, the trial period plan controls the subscription's behavior.
{% code title="Subscription" %}
```javascript
{
"id": "124eeee4-6cf4-40e9-94a6-cba64798fc42",
"contractBindingUntil": "2022-02-18T15:03:12Z",
"createdTime": "2022-02-11T15:01:31Z",
"updatedTime": "2022-02-11T15:05:08Z",
"stateTransitions": {
"activatedFree": "2022-02-11T15:03:12Z"
},
"billingAgreementId": "6e4d986e-c054-43e0-a233-d6c1e9f60765",
"customerId": "563089630336",
"sourceId": "8687447b-a04d-4838-af6c-0de0810f23a7",
"taxInclusive": false,
"currency": "USD",
"planId": "f55d07a2-a78f-406a-b6c6-ad8e1cc1531b",
"locale": "en_US",
"state": "activeFree",
"items": [
{
"price": 29.95,
"skuId": "sku_3e5ab173-d52e-4d9e-8888-2a00f6bb188e",
"quantity": 2
}
],
"currentPeriodEndDate": "2022-02-18T15:03:12Z",
"nextInvoiceDate": "2022-02-18T15:03:12Z",
"nextReminderDate": "2022-02-15T15:03:12Z",
"liveMode": false
}
```
{% endcode %}
On the [`nextReminderDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-reminder), Digital River creates an [event ](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/events)whose [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) is [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder) and whose [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) contains an [invoice ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices)in a [`draft` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)state.
Assuming you updated the [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)`items[].price` or `items[].aggregatePrice`, the invoice's `totalAmount` will be greater than zero and equal to the aggregated price of all the subscription's `items[]`, plus taxes and fees calculated by Digital River.
This `totalAmount` is how much customers will be charged for the subscriptions [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice), which (if you configured your [trial period plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#trial-period-plans) correctly) should be the same as the [`currentPeriodEndDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#current-period-end-date). In other words, customers won't be charged until the free trial period is over.
### Handling trial conversions
You should [send customers an expiration reminder](#sending-a-free-trial-expiration-reminder) before a trial converts to a paid subscription. After a successful conversion occurs, make sure you also [send a conversion notification](#sending-a-trial-conversion-notification).
#### Sending a free trial expiration reminder
We recommend that you use [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder) to trigger an email (or some other type of notification) to the customer. In the event's payload, `currentPeriodEndDate`, `nextInvoiceDate`, and `totalAmount` provide the data you need to inform customers (1) on what date their free trial is scheduled to expire, (2) when their first payment is scheduled, and (3) in what amount.
#### Sending a trial conversion notification
On the [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice), Digital River moves the [invoice ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)to [`open` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)and the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)to [`activePendingInvoice` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)and then attempts to collect payment for the number of days specified by the [trial period plan's](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#trial-period-plans) `collectionPeriodDays`.
If any of these collection attempts are successful, Digital River marks the invoice as [`paid` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)and the [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions) as [`active`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle), populates the [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)`activated` timestamp and creates an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)whose [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) is [`subscription.extended`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.extended).
You should use `subscription.extended` as a trigger to [notify customers that the trial has been converted into a paid subscription](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#trial-conversion-notification).
{% hint style="info" %}
If payment capture fails, the [invoice ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices)becomes [`uncollectible`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states) , and the [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)moves into a [`failed` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)state. To learn more, refer to [Handling failed renewals](#handling-failed-renewals).
{% endhint %}
### Ending trial subscriptions
Customers may cancel their [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)during its trial period to avoid getting charged. In these cases, you have two options:
* If the subscription's [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)is `draft` (i.e., you haven't activated it yet), you should [delete the subscription](#deleting-a-subscription).
* If you [activated the subscription](#activating-trial-subscriptions) (i.e., its `state` is `activeFree`) then [cancel the subscription](#cancelling-a-subscription).
### Extending free trial periods
Sometimes, you might want to extend a customer's free trial period or keep customers at a no-charge level indefinitely. To do this, after you [activate the subscription](#activating-trial-subscriptions), do *not* update its price. By not performing this operation, a [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)`items[]` will have a `price` or `aggregatePrice` of `0.0`on the `nextInvoiceDate`, and, as a result, Digital River doesn't make any invoice collection attempts, and the subscription's `state` remains `activeFree`.
### **Reverting to a free subscription**
You can also push an [`active` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)subscription back into an [`activeFree` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)state. Offering various subscription pricing tiers is useful, and customers can ask to downgrade their access to the basic or free level.
To do this, send a [`POST /subscriptions/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id) request that updates the `price` or `aggregatePrice` of each of the subscription's `items[]` to `0.0` and the `planId` to an appropriate [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics). On the [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice), the subscription's [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)reverts to `activeFree`.
## Modifying subscription payments
{% hint style="info" %}
For more details on how to modify subscriptions, refer to [Updating subscriptions](#updating-subscriptions).
{% endhint %}
When customers want to manage their subscriptions, you can [retrieve a list of subscriptions](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions) associated with their record:
{% tabs %}
{% tab title="Request" %}
```javascript
curl --location --request GET 'https://api.digitalriver.com/subscriptions?customerId=f9acfc5b-42de-4807-8248-eb1cb8069a04' \
--header 'Authorization: Bearer ' \
...
```
{% endtab %}
{% tab title="Response" %}
```javascript
{
"hasMore": false,
"data": [
{
"id": "eabd010b-26f5-44e7-a91d-1b3e23198310",
"contractBindingUntil": "2022-03-02T16:15:15Z",
"createdTime": "2022-01-31T16:14:10Z",
"updatedTime": "2022-01-31T16:15:15Z",
"stateTransitions": {
"activatedFree": "2022-01-31T16:15:15Z"
},
"billingAgreementId": "fbeabcdd-52d4-48a9-9437-5b4ccf6f8df1",
"customerId": "f9acfc5b-42de-4807-8248-eb1cb8069a04",
"sourceId": "596245ab-8479-4df4-ae1c-853ed0e11073",
"taxInclusive": false,
"currency": "USD",
"planId": "2919a6a2-c3ab-4a5b-8a6a-8f8a72a177a5",
"locale": "en_US",
"state": "activeFree",
"items": [
{
"price": 0.0,
"skuId": "7eee0e8c-b08e-4b9b-b241-8ba4e2a5876a",
"quantity": 1
}
],
"currentPeriodEndDate": "2022-04-28T16:15:15Z",
"nextInvoiceDate": "2022-04-28T16:15:15Z",
"nextReminderDate": "2022-04-27T16:15:15Z",
"liveMode": false
}
]
```
{% endtab %}
{% endtabs %}
For each subscription, access its payment [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)by passing `sourceId` in a [`GET /sources/{sourceId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources#sources-id) request.
To modify a [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)payment [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), its [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)must be `active`, `activeFree`, or `activePendingInvoice`. If you meet this precondition, you can:
* [Update basic credit card information](#update-credit-card-information)
* [Replace the existing source with a new source](#replace-an-existing-source-with-a-new-source)
* [Replace the existing source with a saved source](#replace-an-existing-source-with-a-saved-source)
### Update credit card information
If a [subscription's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions) `sourceId` references a [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)with a `type` of `creditCard`, you can provide customers with the ability to update that card's billing information or expiration date.
{% tabs %}
{% tab title="Subscription" %}
```javascript
{
"id": "f9f73fd2-b56d-40d2-92fe-de4987671c34",
...
"sourceId": "26ab35a7-64f7-4cf5-82e6-18cc444cd993",
...
"state": "activeFree",
...
}
```
{% endtab %}
{% tab title="Source" %}
```javascript
{
"id": "26ab35a7-64f7-4cf5-82e6-18cc444cd993",
"createdTime": "2022-02-11T15:44:33Z",
"type": "creditCard",
"currency": "USD",
"amount": 7.0,
"reusable": true,
"state": "chargeable",
"customerId": "563089660336",
"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"
}
},
"clientSecret": "26ab35a7-64f7-4cf5-82e6-18cc444cd993_4a4be490-2c12-4978-af07-3b2b6b184ba5",
"creditCard": {
"brand": "Visa",
"expirationMonth": 3,
"expirationYear": 2030,
"lastFourDigits": "1111"
},
"liveMode": false
}
```
{% endtab %}
{% endtabs %}
If you want to display the card's current billing information and card information to customers, you can retrieve that data from the [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`owner` and `creditCard` blocks.
#### Billing address information
If customers edit their billing information, present them with a form to enter the full name, email, and address (line 1, line 2, city, state, country, postal code) associated with the credit card.
#### Card expiration date
If customers opt to edit their credit card's expiration date, use a [`cardexpiration` element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriver-createelement) to provide them with an input field.
#### Configuring the update source method
Once customers enter and save their changes, pass the submitted data to [`updateSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#updating-sources). Make sure you configure the appropriate version of the method, depending on whether customers submit updated (a) billing address information, (b) card expiration information, or (c) both. In both versions, you need to add the [source's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`id` and `clientSecret` to the method's configuration object.
### Replace an existing source with a new source
When customers want to change how they pay for a subscription, you can allow them to supply a new payment method.
How you replace a [subscription's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions) current [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)with a new source 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).
The customer's billing information must be collected and stored first in both cases.
{% tabs %}
{% tab title="Drop-in payments" %}
Build the `createDropin()` method's [configuration object](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments):
* In [`options`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#drop-in-options-1), set:
* [`flow`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#flow) to `managePaymentMethods`
* [`usage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#specifying-a-sources-future-use) to `subscription`
* [`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`
* [`showComplianceSection`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#show-compliance-section) to `true`
* Since this is an [account management flow](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows#account-management-flows), you can't use the checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts#payment-session-identifier) to set `sessionId`. As a result, you must pass the billing information you collect from customers in [`billingAddress`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#billing-address).
```javascript
let digitalriverpayments = new DigitalRiver("pk_hc_a209389e4588433bb6e00b32466b82c3", {
"locale": "en_GB"
});
let configuration = {
"options": {
"flow": "managePaymentMethods",
"showComplianceSection": true,
"showTermsOfSaleDisclosure": true,
"usage": "subscription"
},
"billingAddress": {
"firstName": "John",
"lastName": "Doe",
"email": "test@test.com",
"phoneNumber": "952-253-1234",
"address": {
"line1": "16 Byward St",
"city": "London",
"state": "England",
"postalCode": "EC3R 5BA",
"country": "GB"
}
},
...
}
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");
```
Pass the configuration object to [`createDropin()`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#step-6-allow-the-shopper-to-interact-with-hydrate). If the request is successful, the [`onReady`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onready) event contains the transaction's eligible payment methods:
```javascript
{
"paymentMethodTypes": [
"creditCard",
"payPalBilling"
]
}
```
Each payment method and its disclosures will appear in the window. If customers click the button without accepting these agreements and terms, Drop-in blocks the transaction from proceeding.
If customers accept the terms, submit their information, and the resulting create source request is successful, the [`onSuccess`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) event contains a [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)that is [`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) and [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state).
For more details, refer to the [Drop-in payments integration guide](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide) and the [Drop-in payments builder tool](https://drapi.io/drop-in-builder/).
{% endtab %}
{% tab title="Elements" %}
Configure [`retrieveAvailablePaymentMethods()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#digitalriverjs-retrieveavailablepaymentmethodsresponsewithusingfilters) using the following filters:
* Set `currency` to the same value as the [subscription's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)`currency`
* Use the billing address country you collect from customers to set `country`
* Both `supportsStorage` and `supportsRecurring` should be `true`
```javascript
...
digitalriver.retrieveAvailablePaymentMethods({
"currency": "EUR",
"country": "FR",
"supportsStorage": true,
"supportsRecurring": true
}).then(function(result) {
//do something with the result, this could include showing or hiding specific payment methods that are applicable to the display
});
...
```
If the request is successful, the response contains the transaction's eligible payment methods:
```javascript
[
{
"type": "creditCard",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
},
"supportsStorage": true,
"defaultMandate": {
"terms": "Yes, please save this account and payment information for future purchases."
},
"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": "Yes, please save this account and payment information for future purchases."
}
"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": "Yes, please save this account and payment information for future purchases."
},
"displayName": "Google Pay",
"localizedDisplayName": "Google Pay"
}
]
```
For each available payment method:
* [Create the appropriate elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-elements) to collect the customer's sensitive payment information.
* Retrieve `defaultMandate.terms` and display that text with some sort of acceptance control. Your code should be written so that customers must accept these terms before the transaction can proceed.
When customers submit their information, configure and call the [`createSource()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-sources) method:
* Set `type` to the payment method selected by the customer
* Set [`usage`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#specifying-a-sources-future-use) to `subscription` and `futureUse` to `true`
* Use that payment method's `defaultMandate.terms` to set `mandate.terms`
* Since this is an [account management flow](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows#account-management-flows), you can't provide a checkout's [payment session identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts#payment-session-identifier). As a result, you must pass the billing information you collect from customers in `billingAddress`.
```javascript
var payload = {
"type": "creditCard",
"futureUse": true,
"usage": "subscription",
"billingAddress": {
"firstName": "John",
"lastName": "Doe",
"email": "test@test.com",
"phoneNumber": "952-253-1234",
"address": {
"line1": "16 Byward St",
"city": "London",
"state": "England",
"postalCode": "EC3R 5BA",
"country": "GB"
}
},
...
"mandate": {
"terms": "Yes, please save this account and payment information for future purchases."
}
}
digitalriver.createSource(payload).then(function(result) {
if (result.error) {
//handle errors
} else {
var source = result.source;
//send source to back end
sendToBackend(source);
}
});
```
If the create source request is successful, the response contains a [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)that is [`readyForStorage`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#onsuccess) and [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state).
For more details, refer to the [DigitalRiver.js Quick start guide](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/quick-start).
{% endtab %}
{% endtabs %}
Send the [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), [customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers), and [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions) identifiers to your backend.
Use a [`POST /customers/{customerId}/sources/{sourceId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers#customers-id-sources-sourceid) to attach the source to the customer. It flips the source's [`reusable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use) attribute to `true`.
To update the subscription, send its identifier as a path parameter in a [`POST /subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id). In the body of the request, specify the new `sourceId`.
```java
curl --location --request POST 'https://api.digitalriver.com/subscriptions/b8dc06d6-941e-483c-89a1-263874bff3b4' \
...
--data-raw '{
"sourceId": "e4adbcac-1551-4743-9a3e-48dc3883241b"
}
```
If you receive a `200 OK`, notify customers that their subscription's designated payment method has been successfully updated.
### Replace an existing source with a saved source
When customers want to change how they pay for a subscription, you can give them the option of selecting one of their saved payment [sources](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources).
To access these sources, send the [customer's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers)identifier in a [`GET /customers/{customerId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers#customers-id-1) request. From the response, you can retrieve any of the `sources[]`, since, by default, they're all [`chargeable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#source-state) and [`reusable`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use).
{% tabs %}
{% tab title="Customer" %}
```javascript
{
"id": "533319260336",
"createdTime": "2021-05-06T21:51:08Z",
"email": "jackdoe@digitalriver.com",
"shipping": {
"address": {
"line1": "123 Boulevard",
"city": "Saint Paul",
"postalCode": "55155",
"state": "MN",
"country": "US"
},
"name": "John Doe",
"phone": "555-555-5555"
},
"defaultSourceId": "5e359d60-1d23-4234-84ee-e1c9b3ed7edc",
"sources": [
{
"id": "19f47eba-418f-41b3-882c-462e335770e7",
"createdTime": "2022-03-30T21:14:05Z",
"type": "payPalBilling",
"currency": "USD",
"amount": 27.01,
"reusable": true,
"state": "chargeable",
"owner": {
"firstName": "Maya",
"lastName": "Brown",
"email": "null@digitalriver.com",
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"paymentSessionId": "46206596-6559-4f86-9f27-2ccb4d0cc677",
"clientSecret": "19f47eba-418f-41b3-882c-462e335770e7_cc871d23-474d-4a3f-9803-4e98fa39f2ee",
"payPalBilling": {
"token": "12345",
"payerId": "payerId",
"payerStatus": "verified",
"redirectUrl": "https://api.digitalriver.com:443/payments/redirects/b9cd5136-8da3-4e00-97af-8b5fe4b70fdf?apiKey=pk_test_da4311e7b7384b7caf5384fb79808192",
"returnUrl": "http://mypage.com",
"offline": false
}
},
{
"id": "1e80940d-33d2-43d8-89c1-09c8076b2654",
"createdTime": "2021-05-19T19:35:47Z",
"type": "creditCard",
"reusable": true,
"state": "chargeable",
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "null@digitalriver.com",
"address": {
"line1": "10381 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"clientSecret": "1e80940d-33d2-43d8-89c1-09c8076b2654_3ada8e16-3938-4495-af72-5f793ff649c8",
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
}
},
...
}
```
{% endtab %}
{% endtabs %}
Use a selection control to display these saved sources to customers. With credit cards, you can retrieve `brand`, `expirationMonth`, `expirationYear`, and `lastFourDigits` and display this information to customers so they can identify the card. If the customer uses a saved [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), retrieve its unique identifier.
To [update the subscription](#updating-subscriptions), send its identifier as a path parameter in a [`POST/ subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id-1) and, in the request body, specify the selected `sourceId`.
```javascript
curl --location --request POST 'https://api.digitalriver.com/subscriptions/b8dc06d6-941e-483c-89a1-263874bff3b4' \
...
--data-raw '{
"sourceId": "e4adbcac-1551-4743-9a3e-48dc3883241b"
}
```
If you receive a `200 OK`, notify customers that their subscription's designated payment method has been successfully updated.
## Cancelling subscriptions
When you either (1) receive a request from the customer to cancel a subscription, and the request adheres to the terms of the agreement (or you grant the customer a waiver), or (2) you decide to cancel the subscription, send a[`POST /subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id) with `state` set to `cancelled` in the request's payload.
```
curl --location --request POST 'https://api.digitalriver.com/subscriptions/895554f1-0568-4387-8405-551ddb533ff8' \
...
--data-raw '{
"state": "cancelled"
}'
```
No other values can be passed in the body of a cancellation request. If you attempt to do so, the following error is returned:
{% tabs %}
{% tab title="409 Conflict" %}
```javascript
{
"type": "conflict",
"errors": [
{
"code": "restricted_update",
"parameter": "metadata",
"message": "Additional data cannot be updated when updating state to cancelled."
}
]
}
```
{% endtab %}
{% endtabs %}
Only `active` , `activeFree`, and `activePendingInvoice` subscriptions can be cancelled. When you cancel an [`activePendingInvoice` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)subscription, the underlying [`open` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)invoice is moved into a [`void` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/invoices/invoice-basics#invoice-states)state.
A successful cancellation request returns a `200 OK`, moves the subscription into a [`cancelled` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#subscription-lifecycle)state and prevents billing from occurring on the [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice).
On your site's subscription management page, include a cancellation button that, when clicked, sends this cancellation request to Digital River. When you receive a successful response, send the customer a [subscription cancellation confirmation email](https://docs.digitalriver.com/digital-river-api/order-management/customer-notifications#subscription-cancelled-notification) and indicate that no future billing will occur.
## Deleting subscriptions
To delete a [`draft` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)subscription, retrieve its unique identifier, and pass it as a path parameter in a [`DELETE /subscriptions/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id-2) request.
A successful request results in the creation of an [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.deleted`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.deleted).
Only subscriptions whose `state` is `draft` can be deleted. If you attempt to delete a non-`draft` subscription, then the following error is thrown:
{% code title="409 Conflict" %}
```javascript
{
"type": "conflict",
"errors": [
{
"code": "invalid_state",
"parameter": "state",
"message": "Subscription c090749a-8f8f-43a5-8e9c-9b434a710b1c is active, so it cannot be deleted."
}
]
}Java
```
{% endcode %}
If you want to stop recurring payments on an [activated subscription](#activating-a-subscription), you can [cancel the subscription](#cancelling-a-subscription) or [deactivate its plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#discontinuing-and-deactivating-plans).
{% hint style="danger" %}
Deactivating a plan terminates all subscriptions that belong to that plan.
{% endhint %}
## Updating plans
[Updating a plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id-1) changes the behavior of all the [subscriptions ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)it controls. As a result, we generally recommend only using the `POST /plans/{planId}` operation to optimize or phase it out.
For details on how changing a [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)`state` affects a [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics), refer to [Lifecycle of a plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#lifecycle-of-a-plan).
### Ending subscription reminders
To stop renewal reminders from getting generated on a [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics), you need to [update its plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id-1) by assigning a negative integer to [`reminderOffSetDays`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#renewal-reminders).
{% tabs %}
{% tab title="POST /plans/{planId}" %}
```
curl --location 'https://api.digitalriver.com/plans/490bf585-26e0-4413-9263-ed68af3a6cc3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
...
--data '{
"reminderOffsetDays": -1
}'
```
{% endtab %}
{% tab title="200 OK" %}
```json
{
"id": "818c1ab7-5970-4dba-a49e-6e0a394c321a",
"createdTime": "2024-01-22T16:27:25Z",
"updatedTime": "2024-01-24T19:36:48Z",
"terms": "Terms of the plan",
"contractBindingDays": 365,
"interval": "week",
"intervalCount": 1,
"name": "A plan to manage subs that bill once per week",
"billingOptimization": true,
"billingOffsetDays": 1,
"collectionPeriodDays": 1,
"state": "active",
"stateTransitions": {
"activated": "2024-01-22T16:27:25Z"
},
"metadata": {
"key1": "value1",
"key2": "value2"
},
"liveMode": false
}
```
{% endtab %}
{% endtabs %}
When a [subscription ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics)on that [plan ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)moves into its next billing period, Digital River deletes its [`nextReminderDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-reminder). As a result, the [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 [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder) does not get created.
If you make this update to a [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans)`reminderOffSetDays`, then the billing behavior of all of its [subscriptions ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions)remains unchanged.
## Updating subscriptions
A [`POST /subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id) request allows you to both [activate a subscription](#activating-a-subscription) and [cancel a subscription](#cancelling-a-subscription) as well as make updates to any of its following attributes:
* [Associated plan](#associated-plan)
* [Payment source](#associated-payment-source)
* [SKUs and product details](#skus-and-product-details)
* [Product price](#price)
* [Product quantity](#quantity)
A successful request results in the creation of an [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.updated`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.updated).
{% hint style="success" %}
For details on handling subscription updates in free trials, refer to [updating the subscription's price and plan](#updating-the-subscriptions-price-and-plan) in the [Trial management](#trial-subscription-management) section.
{% endhint %}
To successfully update a [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions), its [`state`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state) must be `draft`, `active`, `activeFree`, or `activePendingInvoice`.
When Digital River opens an invoice on [`nextInvoiceDate`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#date-of-next-invoice), we move the subscription's `state` to `activePendingInvoice` and implement a blackout period. As a result, any updates you make to the subscription during this period won't take effect until the next billing cycle.
Therefore, performing a [`GET /subscriptions`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions) or [`GET /subscriptions/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id-1) can't be used to identify a subscription's current state. Instead, these requests return the scheduled settings for the next renewal.
In most cases, if you make a subscription update, we recommend you notify customers (typically by email) of the change. In the email, include a link to the customer's subscription management page, and on that same page, make sure you install a cancellation button that, when clicked, sends a [subscription cancellation request](#cancelling-a-subscription) to Digital River.
#### Associated plan
If you want to modify the timing of a subscription's [renewal reminder event](#sending-a-reminder), when billing is initiated, or the length of the payment collection period, you must associate the subscription with a different `planId`. If you move an `active` subscription to a different [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics), the new settings are applied to future billing periods.
Always acquire the customer's consent before changing a subscription's billing frequency. In most cases, we recommend you create a new subscription. Since billing frequency is defined by a plan's [`interval` and `intervalCount`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics), and these attributes can't be modified in a [`POST /plans/{planId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans#plans-id), you'd need to associate the subscription with a different plan, which can potentially cause issues.
For example, you might have a subscription on an annually renewing plan. If you use a [`POST /subscriptions/{subscriptionId}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions#subscriptions-id) to associate the subscription with a different, monthly-billing plan, then the subscription will remain on its current annual plan until the end of the [contract binding period](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#binding-period). Not until that point will the subscription switch to the monthly plan.
#### Associated payment source
For details, refer to the [Modifying subscription payments](#modifying-subscription-payments) section.
#### SKUs and product details
In an update subscription request, you can either pass `items[].skuId` or `items[].productDetails`.
{% hint style="success" %}
For details, refer to [Managing SKUs](https://docs.digitalriver.com/digital-river-api/product-management/creating-and-updating-skus) or [Using product details](https://docs.digitalriver.com/digital-river-api/product-management/using-product-details).
{% endhint %}
A common use case for this operation is when upgrading or downgrading a customer's subscription service. For example, customers might want to migrate from basic to professional offerings.
#### Price
Digital River's standardized autorenewal terms allow you to make `price` or `aggregatePrice` changes to any of a subscription's line items. You must, however, provide customers advance notification (typically by email) of the change, along with instructions on how to cancel the subscription if they don't agree to the price increase.
#### Quantity
For each of a subscription's `items[]` , the default `quantity` is `1`. So, unless you specify `quantity` when updating a line item in a subscription, its value is automatically set to `1` .
Any updates to `quantity` typically require the customer's consent.
## Handling chargebacks
When any of your [webhook endpoints](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks) receive an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)whose [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) is [`order.chargeback`](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/disputes-and-chargebacks), parse its payload to determine whether the [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)contains a `subscriptionId`. If it does, you should cancel the subscription to avoid further chargebacks and fees.
