Replace Device - FlexPortal

Replace subscription device

curl --request POST \
  --url https://api-eu.flexportal.io/v1/subscriptions/{subscriptionId}/replace \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "rentalId": "<string>",
  "newSerialNumber": "<string>",
  "newSku": "<string>",
  "damageAssessment": "<string>",
  "insuranceClaim": false,
  "notes": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "rentalId": "<string>",
  "oldSerialNumber": "<string>",
  "newSerialNumber": "<string>",
  "reason": "<string>"
}

POST

subscriptions

{subscriptionId}

replace

Replace subscription device

curl --request POST \
  --url https://api-eu.flexportal.io/v1/subscriptions/{subscriptionId}/replace \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "rentalId": "<string>",
  "newSerialNumber": "<string>",
  "newSku": "<string>",
  "damageAssessment": "<string>",
  "insuranceClaim": false,
  "notes": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "rentalId": "<string>",
  "oldSerialNumber": "<string>",
  "newSerialNumber": "<string>",
  "reason": "<string>"
}

Overview

Replace a faulty or damaged device with a new one of the same type. Unlike upgrades, replacements keep the same subscription terms—the customer gets a working device without changing their contract.

When to Use Replacements

Scenario	Use This
Device is malfunctioning	Replace
Device was damaged	Replace
Customer wants newer model	Upgrade
Customer wants to extend contract	Extend

Request Fields

Field	Required	Description
`newSerialNumber`	Yes	Serial number of replacement device
`reason`	Yes	Reason for replacement

Example Request

{
  "newSerialNumber": "SN987654321",
  "reason": "Battery failure - device won't hold charge"
}

What Happens

When you replace a device:

Previous asset status changed to unavailable
New asset linked to subscription and marked rented_out
Replacement history logged with both serial numbers
Contract terms remain unchanged
Billing continues uninterrupted

Replacement vs Upgrade

Aspect	Replace	Upgrade
Device	Same model	Different/better model
Contract	Unchanged	New contract
Monthly price	Same	May change
Typical reason	Fault/damage	Customer request
Logistics	Same type swap	Different device

Asset Requirements

The replacement serial number must:

Exist in your asset inventory
Match the same SKU as the original (same product type)
Be available (status: available)

Replacement History

After replacement, the subscription tracks all swaps:

{
  "replacementHistory": [
    {
      "replacedAt": "2025-01-20T14:30:00Z",
      "previousSerialNumber": "SN123456789",
      "newSerialNumber": "SN987654321",
      "reason": "Battery failure - device won't hold charge"
    }
  ],
  "currentSerialNumber": "SN987654321"
}

Example: Device Replacement Workflow

async function replaceDevice(subscriptionId, reason) {
  // 1. Get subscription to find SKU
  const subscription = await getSubscription(subscriptionId);

  // 2. Find available replacement of same type
  const { assets } = await listAssets({
    sku: subscription.sku,
    status: 'available',
    limit: 1
  });

  if (assets.length === 0) {
    throw new Error(`No available ${subscription.sku} in inventory`);
  }

  // 3. Process replacement
  const result = await replaceSubscriptionDevice(subscriptionId, {
    newSerialNumber: assets[0].serialNumber,
    reason
  });

  // 4. Schedule return pickup for faulty device
  await scheduleReturnPickup(subscription.serialNumber, subscription.customerId);

  return result;
}

Common Replacement Reasons

Document the reason clearly for tracking and warranty purposes:

Battery failure
Screen damage
Keyboard malfunction
Performance issues
Physical damage (specify type)
Manufacturing defect

Error Handling

Error Code	Cause	Solution
`SUBSCRIPTION_NOT_ACTIVE`	Subscription is not active	Can only replace on active subscriptions
`ASSET_NOT_FOUND`	Replacement serial doesn’t exist	Create asset first
`ASSET_NOT_AVAILABLE`	Replacement asset not available	Use different asset
`SKU_MISMATCH`	Replacement doesn’t match original product	Use same product type

Get Subscription - Check subscription and current device
List Assets - Find available replacement devices
Upgrade Subscription - For changing to different product
Update Asset - Mark returned device for repair

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

newSerialNumber

string

required

Minimum string length: 1

replacementReason

enum<string>

required

Available options:

damaged,

stolen,

defective,

lost

newSku

string

damageAssessment

string

insuranceClaim

boolean

default:false

notes

string

Response

Device replaced

success

enum<boolean>

required

Available options:

true

message

string

required

rentalId

string

required

oldSerialNumber

string

required

newSerialNumber

string

required

reason

string

required

Upgrade Subscription Buyout Subscription

​Overview

​When to Use Replacements

​Request Fields

​Example Request

​What Happens

​Replacement vs Upgrade

​Asset Requirements

​Replacement History

​Example: Device Replacement Workflow

​Common Replacement Reasons

​Error Handling

​Related Endpoints

Authorizations

Headers

Path Parameters

Body

Response

Overview

When to Use Replacements

Request Fields

Example Request

What Happens

Replacement vs Upgrade

Asset Requirements

Replacement History

Example: Device Replacement Workflow

Common Replacement Reasons

Error Handling

Related Endpoints