Skip to main content
GET
/
v1
/
subscriptions
List subscriptions
curl --request GET \
  --url https://api-eu.flexportal.io/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Tenant-ID: <tenant-id>'
{
  "rentals": [
    {
      "rentalId": "<string>",
      "tenantId": "<string>",
      "assetSerialNumber": "<string>",
      "customerId": "<string>",
      "sku": "<string>",
      "productName": "<string>",
      "monthlyAmount": 123,
      "currency": "<string>",
      "status": "active",
      "originalContractLength": 123,
      "contractLength": 123,
      "startDate": "<string>",
      "orderId": "<string>",
      "customerEmail": "<string>",
      "customerName": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "createdBy": "<string>",
      "productId": "<string>",
      "variantId": "<string>",
      "productImageUrl": "<string>",
      "billingGroupId": "<string>",
      "endDate": "<string>",
      "nextBillingDate": "<string>",
      "lastModifiedDate": "<string>",
      "extensionHistory": [
        {
          "extensionMonths": 60,
          "oldContractLength": 60,
          "newContractLength": 60,
          "oldMonthlyAmount": 1,
          "newMonthlyAmount": 1,
          "extendedBy": {
            "userId": "<string>",
            "email": "<string>",
            "displayName": "<string>",
            "role": "<string>",
            "memberId": "<string>"
          },
          "oldEndDate": "<string>",
          "newEndDate": "<string>",
          "extendedAt": "<string>",
          "reason": "<string>",
          "notes": "<string>"
        }
      ],
      "actualMonthsRented": 123,
      "monthsSaved": 123,
      "listPrice": 123,
      "listPriceSource": "variant",
      "listPriceCapturedAt": "<string>",
      "acquisitionCost": 123,
      "acquisitionCostSource": "variant",
      "acquisitionCostCapturedAt": "<string>",
      "totalCollected": 123,
      "costRecoveryPercent": 123,
      "currentProfit": 123,
      "breakevenMonths": 123,
      "hasReachedBreakeven": true,
      "recoveryStatus": "profitable",
      "replacementHistory": [
        {
          "oldSerialNumber": "<string>",
          "newSerialNumber": "<string>",
          "reason": "<string>",
          "replacedBy": {
            "userId": "<string>",
            "email": "<string>",
            "displayName": "<string>",
            "role": "<string>",
            "memberId": "<string>"
          },
          "replacedAt": "<string>",
          "damageAssessment": "<string>",
          "insuranceClaim": true,
          "notes": "<string>"
        }
      ],
      "buyoutDetails": {
        "buyoutPrice": 1,
        "calculationMethod": "auto_calculated",
        "reason": "customer_request",
        "processedBy": {
          "userId": "<string>",
          "email": "<string>",
          "displayName": "<string>",
          "role": "<string>",
          "memberId": "<string>"
        },
        "buyoutDate": "<string>",
        "calculationBreakdown": {
          "remainingMonths": 60,
          "remainingMonthsPayment": 1,
          "listPricePercentage": 123,
          "listPriceAmount": 1,
          "flatFee": 1
        },
        "notes": "<string>"
      },
      "earlyReturnDetails": {
        "fee": 1,
        "feeWaived": true,
        "calculationMethod": "auto_calculated",
        "returnCondition": "excellent",
        "reason": "<string>",
        "processedBy": {
          "userId": "<string>",
          "email": "<string>",
          "displayName": "<string>",
          "role": "<string>",
          "memberId": "<string>"
        },
        "returnedAt": "<string>",
        "calculationBreakdown": {
          "method": "remaining_months",
          "remainingMonths": 60,
          "gracePeriodApplied": true,
          "daysFromStart": 1825
        },
        "damageAssessment": "<string>",
        "notes": "<string>"
      },
      "cancellationDetails": {
        "reason": "customer_request",
        "processedBy": {
          "userId": "<string>",
          "email": "<string>",
          "displayName": "<string>",
          "role": "<string>",
          "memberId": "<string>"
        },
        "cancelledAt": "<string>",
        "notes": "<string>"
      },
      "upgradeFromRentalId": "<string>",
      "customFields": {},
      "notes": "<string>"
    }
  ],
  "count": 123,
  "limit": 123,
  "hasMore": true,
  "nextCursor": "<string>"
}

​
Overview

Retrieve a paginated list of subscriptions with optional filtering and sorting. Each subscription tracks billing, payments, cost recovery, and the complete lifecycle from activation to completion.

​
Subscription Lifecycle

Order Created → Subscription Created → Active → [Extension/Upgrade/Buyout/Early Return] → Ended
Subscriptions can end through several paths:
  • Contract completed: Reached end date naturally
  • Buyout: Customer purchased the device
  • Early return: Customer returned before contract end
  • Cancellation: Terminated by operator

​
Common Use Cases

Active Subscriptions Dashboard

Monitor active subscriptions, MRR, and contract renewals

Operations Management

Track devices in the field, upcoming end dates, and required actions

Customer Support

Look up customer subscriptions during support inquiries

Financial Reporting

Generate reports on revenue, cost recovery, and profitability

​
Filtering Subscriptions

# Get all active subscriptions
GET /v1/subscriptions?status=active

# Get subscriptions for a customer
GET /v1/subscriptions?customerId=cust_abc123

# Get subscriptions ending this month
GET /v1/subscriptions?endDateFrom=2025-01-01&endDateTo=2025-01-31

# Get subscriptions by product SKU
GET /v1/subscriptions?sku=MACBOOK-PRO-16-M3

# Get subscriptions with specific asset
GET /v1/subscriptions?serialNumber=SN123456789

​
Subscription Status Values

StatusDescription
activeCurrently active subscription
ended_completedContract completed naturally
ended_buyoutCustomer purchased the device
ended_upgradeCustomer upgraded to a new device
ended_early_returnCustomer returned early
cancelledSubscription was cancelled

​
Response Fields

Key fields in each subscription object:
FieldDescription
subscriptionIdUnique subscription identifier
statusCurrent subscription status
customerIdAssociated customer ID
orderIdOriginal order ID
skuProduct variant SKU
productNameProduct display name
serialNumberAssigned asset serial number
startDateSubscription start date
endDateSubscription end date
contractLengthDuration in months
monthlyAmountMonthly billing amount
costRecoveryCost recovery metrics
createdAtISO 8601 timestamp

​
Cost Recovery Metrics

Each subscription includes profitability data: 
{
  "costRecovery": {
    "acquisitionCost": 1800.00,
    "totalCollected": 1548.00,
    "costRecoveryPercent": 86.0,
    "breakevenMonth": 14,
    "monthsRemaining": 10
  }
}

​
Example: Find Subscriptions Ending Soon

// Get subscriptions ending in the next 30 days
const today = new Date();
const thirtyDays = new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000);

const { subscriptions } = await listSubscriptions({
  status: 'active',
  endDateFrom: today.toISOString().split('T')[0],
  endDateTo: thirtyDays.toISOString().split('T')[0],
  sortBy: 'endDate',
  sortDir: 'asc'
});

// These customers might be interested in extensions or upgrades
for (const sub of subscriptions) {
  console.log(`${sub.productName} (${sub.customerId}) ends ${sub.endDate}`);
}

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Query Parameters

​
limit
string

Items per page (default: 50, max: 100)

​
startAfter
string

Cursor for pagination

​
status
string

Filter by status (active, cancelled, ended_completed, ended_buyout, ended_upgrade, ended_early_return)

​
customerId
string

Filter by customer ID

​
orderId
string

Filter by order ID

​
serialNumber
string

Filter by asset serial number

Response

200 - application/json

List of subscriptions

​
rentals
object[]
required
​
count
number
required
​
limit
number
required
​
hasMore
boolean
required
​
nextCursor
string | null
required