Using the Expired Card Optimizer

Learn how to use the Expired Card Optimizer (ECO) for a third-party subscription engine renewal orders.

The Expired Card Optimizer (ECO) is a Billing Optimization feature used to optimize the subscription renewal for credit cards only. It is designed to renew orders for the Digital River subscription engine as described in Providing subscription information. However, as described below, you can use the ECO to renew subscriptions for a third-party subscription engine (that is, a non-Digital River subscription engine).

Renewing subscriptions that do not use the Digital River subscription engine

To use ECO to renew a subscription that does not use the Digital River subscription engine, insert both the subscriptionInfo and billingOptimization in the lineItem array when you create a cart using POST /v1/shoppers/me/carts/active for a third-party subscription engine.

Only provide the information used in this example to renew orders when not using the Digital River subscription engine. An expired credit card does not occur during the initial acquisition, so this information is not required during the initial acquisition.

cURL

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Your_Authorization}' \
--data-raw '{
    "cart": {
        "ipAddress": "{{BrowserIP}}",
        "lineItems": {
            "lineItem": [
                {
                    "quantity": 2,
                    "product": {
                        "id": "{{productId}}"
                    }
                    "billingOptimization": {
                        "subscriptionId": "{{SubscriptionId}}",
                        "segmentId": "{{SubscriptionId}}"+"{{segmentCount}}",
                        "renewalAttemptNumber": 3
                    }
                    "subscriptionInfo": {
                        "autoRenewal": true,
                        "terms": "I agree to have the client charge all my future bills on this card",
                        "freeTrial": false,
                        "startTime": "2020-08-01T00:00:00.000Z",
                        "endTime": "2021-08-01T00:00:00.000Z",
                        "billingAgreementId": "{{BillingAgreementID}}"
                    }
                }
            ]
        },
        "chargeType": "merchant_initiated"
    }
}'

Parameter	Definition
subscriptionInfo	The subscription information should indicate the order uses a third-party subscription engine. Note that Digital River does not validate data from non-Digital River subscription engines.
billingOptimization	To trigger an ECO, provide the following subscription information under billingOptimization: subscriptionId–The subscription's unique identifier. The subscriptionId is a string of up to 32 characters. segmentId–The unique segment identifier for each renewal term must be unique across all of Digital River's client's subscriptions. The segmentId is a string of up to 32 characters. The segment identifier value changes after each renewal attempt and increments upwards (for example, 7654321seg2, 7654321seg3). You can format the segmentId as follows: "segmentId": "{{subscriptionId}}"+{{segmentCount}}", Where the value for subscriptionId is a string of up to 32 characters. renewalAttemptNumber–The number of billing attempts for the current renewal. Then the value resets to 1 after each successful renewal. At the time of the first renewal attempt, ECO generates an incremented expiration date schedule that lives in a Billing Optimization table.

The renewal orders for a Digital River subscription provide all the necessary information. Therefore, there is no need for you to insert this information manually.