Skip to main content
POST
/
v1
/
subscriptions
/
{subscriptionId}
/
early-return
Early return a subscription
curl --request POST \
  --url https://api-eu.flexportal.io/v1/subscriptions/{subscriptionId}/early-return \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "rentalId": "<string>",
  "reason": "<string>",
  "earlyReturnFee": 1,
  "damageAssessment": "<string>",
  "notes": "<string>"
}
'
{
  "success": true,
  "rentalId": "<string>",
  "assetSerialNumber": "<string>",
  "earlyReturnFee": 1,
  "currency": "<string>",
  "actualMonthsRented": 60,
  "returnDate": "<string>",
  "message": "<string>"
}

​
Overview

Process an early return when a customer wants to end their subscription before the contract end date. The customer returns the device and may pay an early termination fee based on your policies.

​
When to Use Early Returns

ScenarioUse Early Return
Customer no longer needs deviceYes
Customer moving/relocatingYes
Financial hardshipYes (consider waiving fee)
Device issuesNo—use Replace
Customer wants to own deviceNo—use Buyout

​
Early Return vs Buyout

AspectEarly ReturnBuyout
DeviceReturned to youCustomer keeps
FeeEarly termination feeBuyout price
AssetBack in inventoryRemoved from inventory
Best forCustomer done with deviceCustomer wants ownership

​
Request Fields

FieldRequiredDescription
earlyReturnFeeYesThe fee to charge
effectiveDateNoWhen subscription ends (default: today)
reasonNoReason for early return
waiveFeeNoSet to true to waive the fee

​
Example: Standard Early Return

{
  "earlyReturnFee": 258.00,
  "reason": "Customer relocating abroad"
}

​
Example: Waived Fee (Customer Goodwill)

{
  "earlyReturnFee": 0,
  "waiveFee": true,
  "reason": "Customer hardship - fee waived per manager approval"
}

​
What Happens

When you process an early return:
  1. Subscription status changes to ended_early_return
  2. Early return details recorded with fee and reason
  3. Future payments cancelled
  4. Asset marked for return processing
  5. Final invoice generated for early return fee (if applicable)

​
Response Structure

{
  "success": true,
  "message": "Early return processed",
  "subscription": {
    "subscriptionId": "sub_abc123",
    "status": "ended_early_return",
    "earlyReturnDetails": {
      "returnDate": "2025-01-20",
      "earlyReturnFee": 258.00,
      "monthsRemaining": 4,
      "feeWaived": false,
      "reason": "Customer relocating abroad"
    }
  }
}

​
Calculate Before Processing

Always calculate the fee first using Calculate Early Return Fee: 
async function processEarlyReturn(subscriptionId, reason) {
  // 1. Calculate the fee
  const calc = await calculateEarlyReturnFee({ subscriptionId });

  // 2. Present to customer and get confirmation
  const confirmed = await confirmWithCustomer(calc.earlyReturnFee);

  if (!confirmed) {
    return { cancelled: true };
  }

  // 3. Process the return
  return await earlyReturnSubscription(subscriptionId, {
    earlyReturnFee: calc.earlyReturnFee,
    reason
  });
}

​
Early Return Fee Policies

Common approaches for calculating early return fees:

​
1. Remaining Contract Value

fee = remainingMonths × monthlyAmount

​
2. Percentage of Remaining

fee = remainingMonths × monthlyAmount × 0.5  // 50% of remaining

​
3. Fixed Early Exit Fee

fee = configuredFixedFee  // e.g., €200 flat fee

​
4. Sliding Scale

if (monthsRemaining > 12) {
  fee = monthlyAmount * 3;  // 3 months penalty
} else if (monthsRemaining > 6) {
  fee = monthlyAmount * 2;  // 2 months penalty
} else {
  fee = monthlyAmount;      // 1 month penalty
}

​
Completing the Early Return

After processing:
  1. Schedule return pickup or provide return instructions
  2. Receive device from customer
  3. Inspect device for damage
  4. Update asset status (available or needs repair)
  5. Process fee payment if applicable

​
Error Handling

Error CodeCauseSolution
SUBSCRIPTION_NOT_ACTIVESubscription is not activeCan only early return active subscriptions
INVALID_FEEFee must be zero or positiveProvide valid fee amount

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Path Parameters

​
subscriptionId
string
required

The subscription ID

Body

application/json
​
rentalId
string
required
Minimum string length: 1
​
returnCondition
enum<string>
required
Available options:
excellent,
good,
fair,
poor,
damaged
​
reason
string
required
Minimum string length: 1
​
earlyReturnFee
number
Required range: x >= 0
​
damageAssessment
string
​
notes
string

Response

Early return completed

​
success
boolean
required
​
rentalId
string
required
​
assetSerialNumber
string
required
​
earlyReturnFee
number
required
Required range: x >= 0
​
currency
string
required
​
actualMonthsRented
integer
required
Required range: 0 <= x <= 120
​
returnDate
string
required
​
message
string
required