Skip to main content
POST
/
v1
/
subscriptions
/
calculate-early-return-fee
Calculate early return fee
curl --request POST \
  --url https://api-eu.flexportal.io/v1/subscriptions/calculate-early-return-fee \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "rentalId": "<string>"
}
'
{
  "success": true,
  "earlyReturnFee": 123,
  "remainingMonths": 123,
  "penaltyPercentage": 123
}

​
Overview

Calculate the early return fee for a subscription before processing the actual early return. This endpoint returns a recommended fee based on remaining contract value and your configured policies—use it to present options to customers.
This is a read-only calculation—it doesn’t modify the subscription. Call Early Return to actually process the return.

​
Request Fields

FieldRequiredDescription
subscriptionIdYesThe subscription to calculate for

​
Example Request

{
  "subscriptionId": "sub_abc123"
}

​
Response Structure

{
  "success": true,
  "subscriptionId": "sub_abc123",
  "calculation": {
    "earlyReturnFee": 258.00,
    "breakdown": {
      "remainingContractValue": 516.00,
      "feePercentage": 50,
      "monthsRemaining": 4,
      "monthlyAmount": 129.00
    },
    "costRecovery": {
      "acquisitionCost": 1800.00,
      "totalCollected": 1548.00,
      "projectedWithFee": 1806.00,
      "costRecoveryPercent": 100.3
    }
  }
}

​
Understanding the Calculation

​
Remaining Contract Value

Total value of remaining payments: 
remainingContractValue = monthsRemaining × monthlyAmount

​
Fee Percentage

The percentage of remaining value charged as fee (configured in tenant settings): 
earlyReturnFee = remainingContractValue × (feePercentage / 100)

​
Cost Recovery Impact

The calculation shows whether you’ll recover costs even with early return:
  • projectedWithFee: Total collected + early return fee
  • costRecoveryPercent: Whether acquisition cost is covered

​
Common Use Cases

​
1. Quoting Customers

async function getEarlyReturnQuote(subscriptionId) {
  const calc = await calculateEarlyReturnFee({ subscriptionId });

  return {
    fee: calc.calculation.earlyReturnFee,
    monthsLeft: calc.calculation.breakdown.monthsRemaining,
    regularPayments: calc.calculation.breakdown.remainingContractValue,
    savings: calc.calculation.breakdown.remainingContractValue - calc.calculation.earlyReturnFee,
    message: `Early return fee: €${calc.calculation.earlyReturnFee} (saves €${savings} vs completing contract)`
  };
}

​
2. Comparing Options for Customer

async function getEndingOptions(subscriptionId) {
  const [earlyReturn, buyout] = await Promise.all([
    calculateEarlyReturnFee({ subscriptionId }),
    calculateBuyout({ subscriptionId })
  ]);

  return {
    options: [
      {
        action: 'Complete contract',
        cost: earlyReturn.calculation.breakdown.remainingContractValue,
        outcome: 'Return device at contract end'
      },
      {
        action: 'Early return now',
        cost: earlyReturn.calculation.earlyReturnFee,
        outcome: 'Return device today, pay fee'
      },
      {
        action: 'Buyout',
        cost: buyout.calculation.buyoutPrice,
        outcome: 'Keep device forever'
      }
    ]
  };
}

​
3. Evaluating Fee Waiver

async function shouldWaiveFee(subscriptionId, customerHistory) {
  const calc = await calculateEarlyReturnFee({ subscriptionId });

  // Check if we've already recovered our costs
  const costRecovered = calc.calculation.costRecovery.costRecoveryPercent >= 100;

  // Check customer value
  const isHighValueCustomer = customerHistory.lifetimeRevenue > 5000;

  return {
    fee: calc.calculation.earlyReturnFee,
    recommendWaive: costRecovered && isHighValueCustomer,
    reason: costRecovered
      ? 'Asset costs fully recovered'
      : 'Consider partial waiver for customer retention'
  };
}

​
Presentation Tips

When showing early return fees to customers:
  • Compare to remaining payments: Show savings vs completing contract
  • Explain the policy: Help customers understand the fee rationale
  • Offer alternatives: Present buyout or extension options
  • Be flexible: Consider waivers for good customers or hardship cases

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Body

application/json
​
rentalId
string
required

The subscription ID

Response

Early return fee calculation

​
success
enum<boolean>
required
Available options:
true
​
earlyReturnFee
number
required
​
remainingMonths
number
required
​
penaltyPercentage
number
required