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>",
  "returnCondition": "excellent",
  "reason": "<string>",
  "earlyReturnFee": 1,
  "damageAssessment": "<string>",
  "notes": "<string>"
}
'

{
  "success": true,
  "rentalId": "<string>",
  "assetSerialNumber": "<string>",
  "earlyReturnFee": 1,
  "currency": "<string>",
  "actualMonthsRented": 60,
  "returnDate": "<string>",
  "message": "<string>"
}

POST

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>",
  "returnCondition": "excellent",
  "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

Scenario	Use Early Return
Customer no longer needs device	Yes
Customer moving/relocating	Yes
Financial hardship	Yes (consider waiving fee)
Device issues	No—use Replace
Customer wants to own device	No—use Buyout

Early Return vs Buyout

Aspect	Early Return	Buyout
Device	Returned to you	Customer keeps
Fee	Early termination fee	Buyout price
Asset	Back in inventory	Removed from inventory
Best for	Customer done with device	Customer wants ownership

Request Fields

Field	Required	Description
`earlyReturnFee`	Yes	The fee to charge
`effectiveDate`	No	When subscription ends (default: today)
`reason`	No	Reason for early return
`waiveFee`	No	Set 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:

Subscription status changes to ended_early_return
Early return details recorded with fee and reason
Future payments cancelled
Asset marked for return processing
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:

Schedule return pickup or provide return instructions
Receive device from customer
Inspect device for damage
Update asset status (available or needs repair)
Process fee payment if applicable

Error Handling

Error Code	Cause	Solution
`SUBSCRIPTION_NOT_ACTIVE`	Subscription is not active	Can only early return active subscriptions
`INVALID_FEE`	Fee must be zero or positive	Provide valid fee amount

Calculate Early Return Fee - Get recommended fee
Get Subscription - Check subscription details
Buyout Subscription - Alternative: customer keeps device
Update Asset - Update returned device status

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

Calculate Buyout Price Calculate Early Return Fee

⌘I

Overview

Products

Customers

Orders

Subscriptions

Assets

Payments

Billing Groups

Files

Exports

Overview

When to Use Early Returns

Early Return vs Buyout

Request Fields

Example: Standard Early Return

Example: Waived Fee (Customer Goodwill)

What Happens

Response Structure

Calculate Before Processing

Early Return Fee Policies

1. Remaining Contract Value

2. Percentage of Remaining

3. Fixed Early Exit Fee

4. Sliding Scale

Completing the Early Return

Error Handling

Authorizations

Headers

Path Parameters

Body

Response

Overview

Products

Customers

Orders

Subscriptions

Assets

Payments

Billing Groups

Files

Exports

​Overview

​When to Use Early Returns

​Early Return vs Buyout

​Request Fields

​Example: Standard Early Return

​Example: Waived Fee (Customer Goodwill)

​What Happens

​Response Structure

​Calculate Before Processing

​Early Return Fee Policies

​1. Remaining Contract Value

​2. Percentage of Remaining

​3. Fixed Early Exit Fee

​4. Sliding Scale

​Completing the Early Return

​Error Handling

​Related Endpoints

Authorizations

Headers

Path Parameters

Body

Response

Overview

When to Use Early Returns

Early Return vs Buyout

Request Fields

Example: Standard Early Return

Example: Waived Fee (Customer Goodwill)

What Happens

Response Structure

Calculate Before Processing

Early Return Fee Policies

1. Remaining Contract Value

2. Percentage of Remaining

3. Fixed Early Exit Fee

4. Sliding Scale

Completing the Early Return

Error Handling

Related Endpoints