Subscriptions API Reference

Manage customer subscriptions, renewals, upgrades, downgrades, and subscription lifecycle.

Base Path: /api/subscriptions

Overview

The Subscriptions API provides comprehensive endpoints for managing product subscriptions including creation, renewal, suspension, termination, and plan modifications. Supports bulk operations, domain management, and attestation.

Key Operations

API Endpoints

GET /api/subscriptions

List Subscriptions

Gets all subscriptions with OData filtering and pagination.

Authentication

Bearer Token or Service Token

Query Parameters

Parameter Type
$filter string
$orderby string
$skip integer
$top integer

Response

{
  "value": [
    {
      "id": "sub_123",
      "customerId": "cust_456",
      "offerId": "offer_789",
      "status": "active",
      "quantity": 5,
      "startDate": "2026-01-01",
      "renewalDate": "2026-07-01",
      "createdAt": "2026-06-02T10:30:00Z"
    }
  ],
  "count": 50
}
GET /api/subscriptions/aggregated

Get Aggregated Metrics

Gets aggregated subscription metrics and statistics.

Authentication

Bearer Token (reporting roles required)

Query Parameters

Parameter Type
startDate date
endDate date
groupBy string

Response

{
  "totalSubscriptions": 1000,
  "activeSubscriptions": 800,
  "suspendedSubscriptions": 150,
  "terminatedSubscriptions": 50,
  "totalMRR": 50000.00
}
GET /api/subscriptions/{id}

Get Subscription by ID

Gets subscription details by ID.

Authentication

Bearer Token or Service Token

Response

{
  "id": "sub_123",
  "customerId": "cust_456",
  "offerId": "offer_789",
  "status": "active",
  "quantity": 5,
  "startDate": "2026-01-01",
  "renewalDate": "2026-07-01",
  "createdAt": "2026-06-02T10:30:00Z"
}
POST /api/subscriptions

Create Subscription

Creates new subscription.

Authentication

Bearer Token

Request Body

{
  "customerId": "cust_456",
  "offerId": "offer_789",
  "quantity": 5,
  "startDate": "2026-06-02",
  "billingCycle": "monthly",
  "autoRenewal": true
}

Response

{
  "id": "sub_123",
  "status": "active",
  "createdAt": "2026-06-02T10:30:00Z"
}
PUT /api/subscriptions/{id}

Update Subscription

Updates subscription details.

Authentication

Bearer Token

Request Body

{
  "quantity": 10,
  "autoRenewal": false
}

Response

{
  "id": "sub_123",
  "updatedAt": "2026-06-02T11:00:00Z"
}
DELETE /api/subscriptions/{id}

Delete Subscription

Deletes subscription (soft/hard delete).

Authentication

Bearer Token

Response

{
  "success": true,
  "message": "Subscription deleted"
}
POST /api/subscriptions/{id}/sync

Sync Subscription

Syncs subscription with external system.

Authentication

Bearer Token

Response

{
  "success": true,
  "message": "Subscription synced"
}
POST /api/subscriptions/suspend

Suspend Subscription

Suspends subscription.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123",
  "reason": "Payment failed"
}

Response

{
  "id": "sub_123",
  "status": "suspended"
}
POST /api/subscriptions/unsuspend

Unsuspend Subscription

Reactivates suspended subscription.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123"
}

Response

{
  "id": "sub_123",
  "status": "active"
}
POST /api/subscriptions/terminate

Terminate Subscription

Terminates subscription.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123",
  "reason": "Customer request",
  "effectiveDate": "2026-06-15"
}

Response

{
  "id": "sub_123",
  "status": "terminated",
  "terminationDate": "2026-06-15"
}
POST /api/subscriptions/upgrade-quantity

Upgrade Quantity

Upgrades subscription quantity.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123",
  "newQuantity": 10,
  "effectiveDate": "2026-06-02"
}

Response

{
  "id": "sub_123",
  "quantity": 10
}
POST /api/subscriptions/downgrade-quantity

Downgrade Quantity

Downgrades subscription quantity.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123",
  "newQuantity": 3,
  "effectiveDate": "2026-06-02"
}

Response

{
  "id": "sub_123",
  "quantity": 3
}
POST /api/subscriptions/plan-change

Change Plan

Changes subscription plan/offer.

Authentication

Bearer Token

Request Body

{
  "subscriptionId": "sub_123",
  "newOfferId": "offer_999",
  "effectiveDate": "2026-07-01"
}

Response

{
  "id": "sub_123",
  "offerId": "offer_999"
}
POST /api/subscriptions/{id}/renew

Renew Subscription

Renews subscription for next period.

Authentication

Bearer Token

Response

{
  "id": "sub_123",
  "renewalDate": "2026-07-01"
}
POST /api/subscriptions/{id}/generate-renewal-invoice

Generate Renewal Invoice

Generates invoice for subscription renewal.

Authentication

Bearer Token

Response

{
  "invoiceId": "inv_123",
  "amount": 999.99
}
POST /api/subscriptions/bulk-renew

Bulk Renew Subscriptions

Renews multiple subscriptions.

Authentication

Bearer Token

Request Body

{
  "subscriptionIds": ["sub_123", "sub_124", "sub_125"]
}

Response

{
  "renewed": 3,
  "failed": 0
}
POST /api/subscriptions/process-due-renewals

Process Due Renewals

Processes all subscriptions due for renewal.

Authentication

Bearer Token

Response

{
  "processed": 150,
  "failed": 5
}
GET /api/subscriptions/{customerId}/domains

Get Customer Domains

Gets domains associated with customer subscriptions.

Authentication

Bearer Token

Response

{
  "domains": [
    {
      "domain": "example.com",
      "subscriptionId": "sub_123",
      "status": "active"
    }
  ]
}
POST /api/subscriptions/export

Export Subscriptions

Exports subscriptions to CSV or Excel.

Authentication

Bearer Token

Request Body

{
  "format": "csv",
  "filters": {
    "status": "active"
  }
}

Response

File download (CSV/Excel)

Quick Links

← Back to Overview ← Orders API Invoices API → All Endpoints