# Providing subscription information ## Billing agreement identifier A billing agreement identifier is an essential component in managing recurring payments for subscription-based services. It is a unique reference linking a customer's billing consent to regular payment transactions, thus ensuring seamless and secure automatic renewals. This identifier facilitates compliance with regulatory standards such as the [PSD2 Strong Customer Authentication (SCA)](https://info.digitalriver.com/rs/348-QUY-258/images/Digital_River_Guide_to_PSD2_Compliance_2020.pdf) requirements, providing additional security and verification for merchant-initiated transactions. Understanding and implementing billing agreement identifiers is crucial for any business offering subscription services. A billing agreement identifier is a unique reference number assigned to a billing agreement. Customers use this identifier to consent to recurring charges on their credit cards. This identifier is vital for processing subsequent renewals and ensuring compliance with the PSD2 SCA requirements. A billing agreement consists of the [terms](#terms) customers agree to when they consent to have their credit card details applied to any recurring purchase. The identifier of the agreement is then referenced on subsequent renewals. If you sell your product or service as part of a subscription and you want to use an external subscription engine to manage your subscriptions, you *must*: * [Create a product](https://help.digitalriver.com/help/gc/Products/All-Products/Creating-a-product.htm) in [Global Commerce](https://gc.digitalriver.com/gc/ent/login.do) without selecting the Subscription option and [deploy the product](https://help.digitalriver.com/help/gc/Products/All-Products/Deploying-products.htm). * Include the `subscriptionInfo` hash table. Digital River, as the [reseller of record](https://docs.digitalriver.com/commerce-api/master#working-with-digital-river), is required to collect the basic information in this data structure. ## Adding a subscription to a product To add a subscription to a product for a customer, include the `subscriptionInfo` hash table in the `LineItem` array. The `subscriptionInfo` can be added to the following requests: * [`POST /v1/shoppers/me/carts/active`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/carts#v1-shoppers-me-carts-active-1) * [`POST /v1/shoppers/me/carts/active/line-items`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/shoppers/addresses#v1-shoppers-me-addresses-addressid-1) * [`POST /v1/shoppers/me/carts/active/line-items/{lineItemsId}`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/line-items#v1-shoppers-me-carts-active-line-items-lineitemsid) The `subscriptionInfo` should include details about the subscription parameters, such as the billing agreement identifier, the subscription term, and any additional identifiers specific to the product display for the customer. The following [`POST /v1/shoppers/me/carts/active`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/carts#v1-shoppers-me-carts-active) request includes the subscription parameters related to [auto-renewals](#auto-renewal), [free trials](#subscription-lifecycle), and the [terms](#terms) displayed to the customer. You can also provide the [subscription](#subscription-identifier) and the [billing agreement](#billing-agreement-identifier) identifiers. {% tabs %} {% tab title="cURL" %} ```json curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \ --header 'Authorization: Bearer {Your_Acces_Token}' \ ... --data-raw '{ "cart": { "ipAddress": "{{BrowserIP}}", "lineItems": { "lineItem": [ { "quantity": 1, "product": { "id": "{{ExternalSubPID}}" }, "subscriptionInfo": { "autoRenewal": true, "terms": "I agree to have client charge all my future bills on this card", "freeTrial": false, "billingAgreementId": null } } ] } } }' ``` {% endtab %} {% tab title="200 OK response" %} ``` ... "lineItems": { "lineItem": [ { "id": "12151550082", "quantity": "1", "product": {... }, "lineItemState": "Downloadable", "lineItemStateDetails": { "description": "Downloadable - 1", "backOrdered": "0", "shipped": "0", "returned": "0", "pendingReturn": "0" }, "pricing": {... }, "downloads": { "downloadUri" : [ "http://wgtintot12.digitalriver.com/wgt/9B5A4FCEF11DA80C/171F14235882A3D3E56B5723F9D46513279A35381E6ECCFA38DC305C96D769173E906E98A04A2B5B3CFFB85C93D810E7B365B18617EBAE4682F5E46FAD1C55CE291C52E8142F3D624C7461A8833978160451C577DBEF2976/demosft1/software.zip" ] }, "digitalRights": {}, "subscriptionInfo": { "autoRenewal": "true", "terms": "CAPI-395 Anonymous flow", "freeTrial": "false", "startTime": "2020-09-13T00:00:00.000z", "endTime": "2021-09-13T00:00:00.000z", "billingAgreementId": "c713ec4d-5fcf-4a3d-9a0c-bcb214480b8d" } } }, ... ``` {% endtab %} {% endtabs %} ## Getting a billing agreement To get the [`billingAgreementId`](#billing-agreement-identifier), send a [`POST v1/shopper/me/carts/active/submit-cart`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/submit-a-cart#v1-shoppers-me-carts-active-submit-cart) request to submit the cart. The following `200 OK` response includes the `billingAgreementId` from the payment service. {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active/submit-cart' \ --header 'Authorization: Bearer {Your_Acces_Token}' \ ``` {% endtab %} {% tab title="200 OK response" %} ```json ... "lineItems": { "lineItem": [ { "id": "12151550082", "quantity": "1", "product": {... }, "lineItemState": "Downloadable", "lineItemStateDetails": { "description": "Downloadable - 1", "backOrdered": "0", "shipped": "0", "returned": "0", "pendingReturn": "0" }, "pricing": {... }, "downloads": { "downloadUri" : [ "http://wgtintot12.digitalriver.com/wgt/9B5A4FCEF11DA80C/171F14235882A3D3E56B5723F9D46513279A35381E6ECCFA38DC305C96D769173E906E98A04A2B5B3CFFB85C93D810E7B365B18617EBAE4682F5E46FAD1C55CE291C52E8142F3D624C7461A8833978160451C577DBEF2976/demosft1/software.zip" ] }, "digitalRights": {}, "subscriptionInfo": { "autoRenewal": "true", "terms": "CAPI-395 Anonymous flow", "freeTrial": "false", "startTime": "2020-09-13T00:00:00.000z", "endTime": "2021-09-13T00:00:00.000z", "billingAgreementId": "c713ec4d-5fcf-4a3d-9a0c-bcb214480b8d" } } }, ... ``` {% endtab %} {% endtabs %} ## Creating a renewable subscription To create a transaction that charges on the renewal of a subscription, you need to include the `billingAgreementId` and set the `chargeType` to `merchant_initiated` in the [`POST /v1/shoppers/me/carts/active`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/carts#v1-shoppers-me-carts-active-1) request. This ensures that the subscription is renewed automatically using previously obtained billing agreement details. {% tabs %} {% tab title="cURL" %} ```json curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \ --header 'Authorization: Bearer {{Token}}' \ ... --data-raw '{ "cart": { "ipAddress": "{{ServerIP}}", "chargeType": "merchant_initiated", "lineItems": { "lineItem": [ { "quantity": 1, "product": { "id": "{{RenewalPID}}" }, "subscriptionInfo": { "billingAgreementId": "{{billingAgreementId}}" } } ] } } }' ``` {% endtab %} {% endtabs %} ## Automatically renewing a subscription To use the `autoRenewal` parameter, set it to `true` if you want the subscription to renew automatically. This requires customers' consent to store their card information for future billing cycles. Ensure you have obtained this agreement and associated the billing details with the subscription. When you set `autoRenewal` to `true`, you must [attach a Source to the payment option](https://docs.digitalriver.com/commerce-api/payments/sources/using-the-source-identifier#attaching-a-source-to-a-payment-option) associated with the subscription and make sure the [Source is reusable](https://docs.digitalriver.com/commerce-api/payments/sources#reusable-or-single-use). If you set `autoRenewal` to `false`, customers must manually renew the subscription by providing payment details again. Facilitate this process by prompting them to resubmit their payment information at the end of the billing cycle by [creating a new instance of Drop-in](https://docs.digitalriver.com/commerce-api/payments/payments-solutions/drop-in) to collect the payment source. {% tabs %} {% tab title="cURL" %} ```json curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \ --header 'Authorization: Bearer {{Token}}' \ ... --data-raw '{ "cart": { "ipAddress": "{{ServerIP}}", "chargeType": "merchant_initiated", "lineItems": { "lineItem": [ { "quantity": 1, "product": { "id": "{{RenewalPID}}" }, "subscriptionInfo": { "billingAgreementId": "{{billingAgreementId}}" } } ] } } }' ``` {% endtab %} {% endtabs %} ## Free trial A free trial period allows customers to test their membership before committing to a paid subscription. During this period, set the `freeTrial` attribute to `true` in your API request. Collect customers' credit card information upfront, even though no charges will be made initially. Inform Digital River about the collection of credit card details to ensure compliance. When you offer customers a free trial period to test run the membership and also collect their credit card information, ensure that you set the `freeTrial` attribute to `true`. Digital River must be informed of the collection of credit card details, even if no charge occurs. ## Terms The `terms` parameter is used to present the auto-renewal conditions of the subscription to the customer at the time of acquisition. This ensures transparency and complies with legal requirements by informing customers about their subscription renewal's ongoing nature and conditions. ## Subscription identifier The `subscriptionId` is a unique identifier assigned by your subscription management system during the initial subscription acquisition. This identifier is crucial for managing the subscription lifecycle, including renewals and cancellations. It must be included in a `POST /carts` request during the initial acquisition and consistently used in subsequent renewal requests. If the `subscriptionId` provided during a renewal does not match the original one, Digital River will treat the request as a new acquisition rather than a renewal. ## Creating a billing agreement Creating a billing agreement is a key step in managing subscriptions effectively. It ensures that the customer's payment method is securely stored and can be automatically charged for subscription renewals. This guide will walk you through establishing a billing agreement, including associating relevant information with the subscription and submitting the necessary requests to Digital River's API. To create a billing agreement, follow these steps: 1. Ensure that you've [attached a source to the payment option](https://docs.digitalriver.com/commerce-api/payments/sources/using-the-source-identifier#attaching-a-source-to-a-payment-option) associated with the subscription and that the [source is reusable](https://docs.digitalriver.com/commerce-api/payments/sources#reusable-or-single-use). 2. Apply the shopper to the cart, including the `subscriptionInfo` hash table, using a [`POST /apply-shopper`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/apply-a-shopper-to-a-cart#v1-shoppers-me-carts-active-apply-shopper) request, and include `billingAgreementId`. 3. Submit the cart using a [`POST /submit-cart`](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/cart/submit-a-cart#v1-shoppers-me-carts-active-submit-cart) request. After submission, Digital River will generate a billing agreement and return the `billingAgreementId` in the response. {% hint style="info" %} A one-to-one relationship exists between a subscription item and a billing agreement. For example, if your `POST/submit-cart` request contains two line items and both have a `subscriptionInfo` hash table, then Digital River creates two separate billing agreements and returns two billing agreement identifiers. {% endhint %} For each subscription you create, you should persist the `billingAgreementId` that is returned in the response so you can later provide the value when renewing the subscription. ## Using the billing agreement identifier When it's time to process a renewal, retrieve the `billingAgreementId` you persisted with that subscription. Then, you should include the value in the `subscriptionInfo` hash table of a `POST Cart` request. {% hint style="warning" %} You should submit the same `billingAgreementId` when renewing the subscription, even if the customer uses a different credit card to pay for the transaction. {% endhint %} Finally, pass the order identifier returned in the response to a create Cart request. Continue to persist the same `billingAgreementId` for future renewals. ## Commitment price The `commitmentPrice` hash table encapsulates the committed purchase price for a loan or subscription. It appears during a [product retrieval by identifier](https://app.gitbook.com/s/X2fWaY1Kp5sXA1fmOL7z/browse-product-discovery/products#v1-shoppers-me-products-productid) and includes details such as currency and value. This ensures transparency on the total amount a customer commits to for the duration of the subscription or loan. {% tabs %} {% tab title="200 OK response" %} ```json ... "pricing": { "uri": "https://api.digitalriver.com/v1/shoppers/me/products/64578500/pricing", "listPrice": { "currency": "USD", "value": "19.99" }, "salePriceWithQuantity": { "currency": "USD", "value": "19.99" }, "formattedListPrice": "$19.99", "formattedSalePriceWithQuantity": "$17.99", "msrpPrice": { "currency": "USD", "value": "19.99" }, "formattedMsrpPrice": "$2.00", "listPriceIncludesTax": "false", "formattedCommitmentPrice": "$240.00", "commitmentPrice": { "currency": "USD", "value": "240.00" } }, ... ``` {% endtab %} {% endtabs %} A customer must provide a recurring payment method for a commitment-based subscription. When a customer provides a non-recurring payment method for a commitment-based subscription, the system will return the following error: {% tabs %} {% tab title="Error response" %} ```json { "errors": { "error": [ { "relation": "https://api.digitalriver.com/v1/shoppers/CartsResoure", "code": "invalid-payment-method", "description": "Cannot use non-recurring payment method to purchase a commitment type subscription" } ] } } ``` {% endtab %} {% endtabs %}