Skip to main content
GET
/
v1
/
subscriptions
/
{subscriptionId}
Get a subscription
curl --request GET \
  --url https://api-eu.flexportal.io/v1/subscriptions/{subscriptionId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Tenant-ID: <tenant-id>'
{
  "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>"
}

Overview

Retrieve complete details for a single subscription, including full cost recovery metrics, lifecycle history, and payment information. This endpoint returns the most comprehensive view of a subscription.

Common Use Cases

  • Subscription Detail Page: Display complete subscription information
  • Cost Recovery Analysis: Review profitability and breakeven analysis
  • Lifecycle Tracking: View extension, upgrade, and replacement history
  • Support Inquiries: Get full context during customer support

Cost Recovery Details

The response includes detailed profitability metrics:
{
  "costRecovery": {
    "acquisitionCost": 1800.00,
    "listPrice": 2499.00,
    "totalCollected": 1548.00,
    "costRecoveryPercent": 86.0,
    "breakevenMonth": 14,
    "monthsActive": 12,
    "monthsRemaining": 12,
    "projectedTotalCollection": 3096.00,
    "projectedMargin": 1296.00,
    "projectedMarginPercent": 72.0
  }
}
MetricDescription
acquisitionCostWhat you paid for the asset
listPriceMSRP/retail price
totalCollectedTotal payments collected so far
costRecoveryPercent(Collected / Cost) × 100
breakevenMonthMonth when cost will be fully recovered
monthsActiveHow long subscription has been active
monthsRemainingMonths until contract ends
projectedTotalCollectionExpected total at contract end
projectedMarginExpected profit at contract end

Lifecycle History

Subscriptions track all lifecycle events:
{
  "extensionHistory": [
    {
      "extendedAt": "2025-06-15T10:30:00Z",
      "extensionMonths": 6,
      "previousEndDate": "2025-06-30",
      "newEndDate": "2025-12-31",
      "reason": "Customer requested extension"
    }
  ],
  "replacementHistory": [
    {
      "replacedAt": "2025-03-10T14:00:00Z",
      "previousSerialNumber": "SN123456",
      "newSerialNumber": "SN789012",
      "reason": "Device malfunction"
    }
  ]
}

Subscription Details

Key fields in the response:
FieldDescription
subscriptionIdUnique identifier
statusCurrent status
customerIdCustomer ID
orderIdOriginal order ID
skuProduct variant SKU
productNameProduct display name
serialNumberCurrent asset serial number
startDateContract start date
endDateContract end date
contractLengthDuration in months
monthlyAmountMonthly billing amount
nextBillingDateNext scheduled payment date
billingGroupIdB2B billing group (if applicable)

Example: Display Subscription Summary

async function getSubscriptionSummary(subscriptionId) {
  const sub = await getSubscription(subscriptionId);

  const isProfitable = sub.costRecovery.costRecoveryPercent >= 100;
  const monthsToBreakeven = sub.costRecovery.breakevenMonth - sub.costRecovery.monthsActive;

  return {
    product: sub.productName,
    customer: sub.customerId,
    status: sub.status,
    monthlyPayment: `€${sub.monthlyAmount}`,
    contractPeriod: `${sub.startDate} to ${sub.endDate}`,
    costRecovery: `${sub.costRecovery.costRecoveryPercent.toFixed(1)}%`,
    isProfitable,
    monthsToBreakeven: isProfitable ? 0 : monthsToBreakeven,
    extensions: sub.extensionHistory?.length || 0,
    replacements: sub.replacementHistory?.length || 0
  };
}

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

Response

Subscription details

rentalId
string
required
tenantId
string
required
assetSerialNumber
string
required
customerId
string
required
sku
string
required
productName
string
required
monthlyAmount
number
required
currency
string
required
status
enum<string>
required
Available options:
active,
cancelled,
ended_completed,
ended_buyout,
ended_upgrade,
ended_early_return
originalContractLength
number
required
contractLength
number
required
startDate
string
required
orderId
string
required
customerEmail
string
required
customerName
string
required
createdAt
string
required
updatedAt
string
required
createdBy
string
required
productId
string
variantId
string
productImageUrl
string
billingGroupId
string
endDate
string
nextBillingDate
string
lastModifiedDate
string
extensionHistory
object[]
actualMonthsRented
number
monthsSaved
number
listPrice
number
listPriceSource
enum<string>
Available options:
variant,
manual,
order_override,
estimated,
unknown
listPriceCapturedAt
string
acquisitionCost
number
acquisitionCostSource
enum<string>
Available options:
variant,
manual,
order_override,
list_price,
unknown
acquisitionCostCapturedAt
string
totalCollected
number
costRecoveryPercent
number
currentProfit
number
breakevenMonths
number
hasReachedBreakeven
boolean
recoveryStatus
enum<string>
Available options:
profitable,
recovering,
at_risk,
no_data
replacementHistory
object[]
buyoutDetails
object
earlyReturnDetails
object
cancellationDetails
object
upgradeFromRentalId
string
customFields
object
notes
string