Subscriptions API

Overview

The Subscriptions API allows authenticated users to retrieve their subscription information including active plans, billing details, payment methods, and subscription features. This replaces the legacy subscription.php endpoint with standard JWT authentication.

Mutating endpoints (v2)

The endpoints below let an authenticated user manage their own subscription end-to-end. They are dispatched through /api using the query field, exactly like the read endpoints.

Access tiers

Two tiers gate the subscription surface, in addition to the user's JWT and ownership check:

• READ — driven by the api_dev_keys.subscription column. Allows getSubscriptions, getSubscriptionDetails, getPaymentHistory, getManageSubscriptionUrl.
• FULL — additional allowlist in api/Subscriptions/access_config.php (per dev key). Allows cancelSubscription, pauseSubscription, resumeSubscription, setAutoRenewal, applyDiscountCode, getCheckoutUrl.

Calls outside the caller's tier return HTTP 403 with SUBSCRIPTION_READ_REQUIRED or SUBSCRIPTION_FULL_REQUIRED.

Endpoint summary

Rate limiting

FULL-tier endpoints use the existing subscription_api_logs table for rate limiting. A user may perform at most 5 state-changing actions per hour; requests beyond that limit return HTTP 429 with RATE_LIMITED.

Webhook URLs

The new architecture exposes one public entry per provider-event. These URLs are what you paste into the gateway's control panel.

Get User Subscriptions

{
  "query": "getSubscriptions"
}

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-Version: 1.3.6" \
  -d '{
    "query": "getSubscriptions"
  }'

{
  "apiVersion": "1.3.6",
  "success": true,
  "subscriptions": [
    {
      "subscriptionId": 1234,
      "subscriptionReference": "ABC123DEF456",
      "title": "VPT 737NG Pro Yearly",
      "groupPackage": "VPT_GLOBAL_Pro",
      "paymentMethod": "2checkout",
      "status": "ACTIVE",
      "isPaused": false,
      "pauseUntil": null,
      "pauseReason": null,
      "autoRenew": true,
      "billing": {
        "frequency": "yearly",
        "interval": "Y",
        "pricePaid": 49.99,
        "currency": "USD",
        "nextBillingDate": "2027-04-15",
        "nextBillingAmount": 49.99,
        "lastPaymentDate": "2026-04-15",
        "cyclesCompleted": null
      },
      "subscriber": {
        "email": null,
        "name": null,
        "cardLast4": "1111"
      },
      "dates": {
        "start": "2026-04-15",
        "end": "2027-04-15",
        "daysRemaining": 274,
        "isActive": true,
        "isExpired": false
      },
      "image": {
        "filename": "VPT_GLOBAL_Pro.jpg",
        "url": "https://api.virtualperformancetool.com/assets/images/subscriptions/VPT_GLOBAL_Pro.jpg"
      },
      "actions": {
        "canPause": true,
        "canCancel": true,
        "canUpgrade": true,
        "canRenew": true,
        "renewalUrl": "https://secure.2checkout.com/renewal/?LICENSE=ABC123DEF456",
        "appleManageUrl": null
      },
      "pricing": {
        "catalogPrice": 79.99,
        "discountPercent": 18,
        "promoCode": "VA-ALLIANCE-18",
        "discountRecurring": true,
        "discountMaxCycles": 3,
        "durationDays": 365,
        "durationLabel": "1 year"
      },
      "features": {
        "level": 3,
        "maxCalculation": 999,
        "isNotam": true,
        "isNnc": true,
        "isMel": true,
        "isCdl": true,
        "isMostFav": true,
        "isBalkedLanding": true,
        "isAllIntersections": true
      }
    }
  ],
  "totalCount": 1
}

Response Fields

Subscription Object

Each subscription in the subscriptions array contains:

Core Fields

Billing Object

Dates Object

Features Object

Actions Object

Flutter / Mobile API (subscription.php)

The VPT Flutter app uses a dedicated HMAC-signed endpoint (subscription.php) that is separate from the JWT-based /api endpoint documented above. All actions in this section are dispatched through this endpoint.

Base URL

GET  https://api.virtualperformancetool.com/subscription.php?action=ACTION
POST https://api.virtualperformancetool.com/subscription.php?action=ACTION

Request Headers

Signature Algorithm

$secret    = hash('sha256', $userId . SAFETY_CODE);
$message   = $apiKey . $timestamp . $action;
$signature = hash_hmac('sha256', $message, $secret);

Confirmation Tokens (State-Changing Actions)

Every POST action that modifies subscription state requires a confirmation_token in the JSON body. The token is generated client-side and is valid for 10 minutes.

// Build a confirmation token (requires SAFETY_CODE)
$timestamp = time();
$data  = $action . '_' . ($subscriptionId ?? 'general') . '_' . $timestamp . '_' . $userId;
$hash  = hash_hmac('sha256', $data, SAFETY_CODE);
$token = base64_encode(json_encode([
    'action'          => $action,
    'subscription_id' => $subscriptionId,
    'timestamp'       => $timestamp,
    'user_id'         => $userId,
    'hash'            => $hash,
]));

Action Summary

★ = state-changing; requires confirmation_token in body; counts against the 5/h rate limit.

Gateway Capabilities

Not every payment gateway supports server-side management. When an unsupported operation is attempted the API returns HTTP 422 with error code OPERATION_NOT_SUPPORTED and a manage_url field pointing to the provider's self-service portal.

Get Payment History

{
  "success": true,
  "message": "Payment history retrieved successfully",
  "user_id": 42,
  "payments": [
    {
      "id": 101,
      "subscription_id": 7,
      "amount": 49.99,
      "currency": "EUR",
      "payment_method": "2checkout",
      "payment_date": "2026-04-15 10:23:00",
      "status": "complete",
      "transaction_id": "104815628",
      "gateway": "2checkout"
    }
  ],
  "total_count": 6,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Pause / Resume / Cancel

All three actions update the local subscription status and synchronise the change to the payment gateway where supported (see Gateway Capabilities). For PayPal subscriptions the NVP API is tried first and the REST API is used as a fallback. A gateway_warning field is included in the response if the gateway sync fails — the local status is still updated in that case.

Pause Subscription

{ "success": true, "subscription_id": 7, "previous_status": "Running", "new_status": "paused" }

Resume Subscription

{ "success": true, "subscription_id": 7, "previous_status": "paused", "new_status": "Running" }

Cancel Subscription

{ "success": true, "subscription_id": 7, "previous_status": "Running", "new_status": "Cancelled" }

Change Plan (2Checkout only)

Change the product on an active 2Checkout subscription. Moves to any plan in the catalogue — upgrades are prorated at the gateway (price difference charged immediately) while downgrades are re-prorated server-side so the unused value carries over as extra days at the new daily rate (see Plan Change Server Behaviour). Validate the target plan against the tier hierarchy below.

Product Tier Hierarchy

Change Plan (Mobile API)

// Upgrade (prorated charge applied immediately):
{
  "success": true,
  "subscription_id": 7,
  "previous_pcode": "VPT_73NG_STANDARD_M",
  "new_pcode": "VPT_73NG_PRO_Y",
  "note": "Price difference has been prorated and will be charged immediately."
}

// Downgrade (no charge, date_end extended by re-prorating remaining value):
{
  "success": true,
  "subscription_id": 7,
  "previous_pcode": "VPT_73NG_PRO_Y",
  "new_pcode": "VPT_73NG_STANDARD_Y",
  "note": "Downgrade applied. Remaining paid value re-prorated at the new daily rate; date_end has been extended."
}

Plan Change Server Behaviour

Independently of which client triggers a plan change (Mobile API, 2Checkout Customer Area, or admin tooling), the server-side IPN/LCN dispatcher enforces the following rules so the subscriptions table stays consistent:

• One active row per user. Whenever a CREATE or plan-change event lands a row for user X, every other row of X with status Running or Paused is automatically moved to Superseded. This fixes the historical bug where an upgrade from Lite → Pro would leave the old Lite row active.
• Upgrades trust the gateway date. 2Checkout charges the price difference at the moment of the upgrade and supplies a new LICENSE_EXP_DATE; we copy it verbatim onto the (kept) subscription row.
• Downgrades are re-prorated server-side. 2Checkout does NOT refund the unused portion of the more expensive plan. To honour the value already paid we extend date_end using:

  remainingDays   = max(0, oldDateEnd - today)
  remainingValue  = remainingDays / oldDurationDays × oldPricePaid
  newDailyRate   = newPrice / newDurationDays
  extendedDays   = floor(remainingValue / newDailyRate)   // capped at 1095 d
  newDateEnd     = today + extendedDays

  Worked example — user on Pro-Y (100 €, 365 d) downgrades to Lite-Y (50 €, 365 d) with 339 days remaining:
  remainingValue = 339/365 × 100 ≈ 92.88 €, newDailyRate = 50/365 ≈ 0.137 €/d, extendedDays ≈ 678 d ⇒ roughly two extra years on Lite, as expected.
• Lateral changes (same tier, different billing cycle) transfer the remaining days 1:1.
• LCN plan detection. 2Checkout downgrades typically arrive only as an LCN with STATUS=ACTIVE and a changed NEXT_RENEWAL_PRICE — the LCN payload does not carry the new PCODE. The dispatcher detects the price change, calls GET /subscriptions/{ref}/ on 2Checkout to read the current PCODE, resolves it to a local products.id, and reroutes the event through the plan-change handler.

2Checkout Control Panel prerequisites

• Enable BOTH webhooks (Setup → System Settings → Notifications): IPN (instant payment notifications) AND LCN (license change notifications). LCN is what carries the downgrade signal.
• Webhook secrets must match the values stored in config.php (TWOCHECKOUT_*_SECRET).
• The native 2Checkout proration setting can stay at its default — the server re-computes date_end for downgrades regardless, so flipping it does not change the user-visible outcome.

Change Payment Method (2Checkout only)

{
  "success": true,
  "subscription_id": 7,
  "checkout_url": "https://secure.2checkout.com/myaccount/payment-update/I-XXXXXXXXXXXX",
  "instructions": "Open checkout_url in a webview for the user to update their payment details."
}

Request Refund (2Checkout only)

{
  "success": true,
  "subscription_id": 7,
  "order_ref": "104815628",
  "refund_status": "pending",
  "message": "Refund initiated. Status will be confirmed via webhook."
}

PayPal → 2Checkout Migration

Allows a user with an active PayPal subscription to migrate to a 2Checkout subscription, carrying over remaining days with a tier-aware day bonus. Upgrading yields a higher bonus; downgrading transfers days 1:1 (no bonus). The flow is non-destructive: the PayPal subscription is only cancelled once the new 2CO subscription is confirmed by the payment gateway IPN.

Migration Day Bonus by Direction

Option A — Direct API (Recommended)

Use the paypal2checkoutMigration query on the standard /api endpoint (FULL tier, JWT auth). This is a two-step process:

1. Call getCheckoutUrl to generate a purchase URL for the target 2CO plan. Open it in a webview.
2. After the webview closes, poll getSubscriptions until the new 2CO subscription row appears, then call paypal2checkoutMigration with both IDs.

{
  "success": true,
  "alreadyMigrated": false,
  "remainingDays": 147,
  "bonusDays": 161,
  "newExpiryDate": "2025-09-10 00:00:00",
  "paypalCancelStatus": "ok",   // "ok" | "failed"
  "warning": null
}

Option B — Mobile API (Legacy Flow)

The subscription.php Mobile API offers a more granular 4-step intent-based flow for apps that need polling.

Flow Overview

1. Call migration_preview (GET) — check eligibility and receive the checkout URL.
2. Call migration_start (POST) — create a migration intent; receive intent_id.
3. Open checkout_url in an in-app webview — user completes the 2CO purchase.
4. Poll migration_status (GET) with intent_id — wait for "status": "completed".
5. If user cancels before paying: Call migration_cancel (POST) to discard the intent.

Step 1 — Migration Preview

{
  "success": true,
  "eligible": true,
  "paypal_subscription": {
    "id": 3,
    "date_end": "2026-08-12",
    "product_title": "VPT Standard Yearly"
  },
  "source_product_code": "VPT_73NG_STANDARD_Y",
  "target_product_code": "VPT_73NG_STANDARD_Y",
  "migration_direction": "same",
  "remaining_days": 85,
  "bonus_pct": 10,
  "bonus_extra_days": 9,
  "bonus_days": 94,
  "bonus_description": "Your remaining 85 day(s) will carry over with a 10% bonus (9 extra day(s) added to your new 2Checkout subscription).",
  "checkout_url": "https://secure.2checkout.com/checkout/buy?merchant=XXXX&prod=VPT_73NG_STANDARD_Y&...",
  "available_targets": [
    { "pcode": "VPT_73NG_PRO_Y",      "plan_label": "Pro-Y",      "direction": "upgrade",   "bonus_pct": 20, "bonus_extra_days": 17, "total_days": 102, "is_default": false },
    { "pcode": "VPT_73NG_PRO_M",      "plan_label": "Pro-M",      "direction": "upgrade",   "bonus_pct": 20, "bonus_extra_days": 17, "total_days": 102, "is_default": false },
    { "pcode": "VPT_73NG_STANDARD_Y", "plan_label": "Standard-Y", "direction": "same",      "bonus_pct": 10, "bonus_extra_days": 9,  "total_days": 94,  "is_default": true  },
    { "pcode": "VPT_73NG_STANDARD_M", "plan_label": "Standard-M", "direction": "same",      "bonus_pct": 10, "bonus_extra_days": 9,  "total_days": 94,  "is_default": false },
    { "pcode": "VPT_73NG_LITE_Y",     "plan_label": "Lite-Y",     "direction": "downgrade", "bonus_pct": 0,  "bonus_extra_days": 0,  "total_days": 85,  "is_default": false },
    { "pcode": "VPT_73NG_LITE_M",     "plan_label": "Lite-M",     "direction": "downgrade", "bonus_pct": 0,  "bonus_extra_days": 0,  "total_days": 85,  "is_default": false }
  ],
  "existing_pending_intent_id": null,
  "notes": "Your PayPal subscription will be cancelled automatically after the 2Checkout purchase is confirmed."
}

{
  "success": true,
  "eligible": false,
  "reason": "NO_ELIGIBLE_PAYPAL_SUBSCRIPTION",
  "reason_description": "No active, unmigrated PayPal subscription was found for this account."
}

Step 2 — Migration Start

{
  "success": true,
  "intent_id": 14,
  "checkout_url": "https://secure.2checkout.com/checkout/buy?...",
  "expires_at": "2026-05-20 14:35:00",
  "target_product_code": "VPT_73NG_PRO_Y",
  "migration_direction": "upgrade",
  "bonus_pct": 20,
  "bonus_extra_days": 17,
  "bonus_days": 102,
  "instructions": "Open checkout_url in a webview. After purchase, poll migration_status with the intent_id for completion."
}

Step 4 — Migration Status (Polling)

{
  "success": true,
  "intent_id": 14,
  "status": "completed",
  "target_product_code": "VPT_73NG_PRO_Y",
  "migration_subscription_id": 22,
  "completed_at": "2026-05-19 14:41:00",
  "new_subscription": {
    "id": 22,
    "date_end": "2027-08-21",
    "status": "Running",
    "product": 5
  }
}

Step 5 — Migration Cancel (Optional)

{
  "success": true,
  "intent_id": 14,
  "status": "expired",
  "message": "Migration cancelled. Your PayPal subscription is unchanged."
}

Migration from Legacy Endpoint

If your application previously used the standalone subscription.php endpoint with HMAC-SHA256 authentication, here is what changes: