Skip to main content
POST
Replace subscription device

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

Request Fields

Example Request

What Happens

When you replace a device:
  1. Previous asset status changed to unavailable
  2. New asset linked to subscription and marked rented_out
  3. Replacement history logged with both serial numbers
  4. Contract terms remain unchanged
  5. Billing continues uninterrupted

Replacement vs Upgrade

Asset Requirements

The replacement serial number must:
  1. Exist in your asset inventory
  2. Match the same SKU as the original (same product type)
  3. Be available (status: available)

Replacement History

After replacement, the subscription tracks all swaps:

Example: Device Replacement Workflow

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

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