Subscriptions API

Manage subscription products, plans, and inventory items for recurring billing and physical/digital goods.

Base:/v1/SubscriptionProduct, /v1/SubscriptionPlan, /v1/SubscriptionInventoryItem

Products

Subscription products group related plans. A product like 'Pro Suite' can have Monthly, Annual, and Trial plans.

GET

/v1/SubscriptionProduct

List Products

Retrieve all subscription products with OData filtering. Products group related plans together.

Query Parameters

Name	Type	Required	Description
$expand	string	Optional	Media
$orderby	string	Optional	'id desc'
$top	number	Optional	Page size
$skip	number	Optional	Offset
$count	boolean	Optional	Include total count

Response

{
  "@odata.count": 3,
  "value": [
    {
      "id": 1,
      "merchantId": 10,
      "name": "Pro Suite",
      "description": "Full-featured business toolkit",
      "subscriptionProductType": "Service",
      "media": [
        { "mediaUrl": "https://...", "isPrimary": true }
      ],
      "createdDateTime": "2024-01-15T10:00:00Z"
    }
  ]
}

POST

/v1/SubscriptionProduct

Create Product

Create a new subscription product.

Request Body

{
  "name": "Starter Kit",
  "description": "Essential tools to get started",
  "subscriptionProductType": "Service"
}

PATCH

/v1/SubscriptionProduct/{id}

Update Product

Update an existing subscription product.

Path Parameters

Name	Type	Required	Description
id	number	Required	Product ID

DELETE

/v1/SubscriptionProduct/{id}

Delete Product

Delete a subscription product.

Path Parameters

Name	Type	Required	Description
id	number	Required	Product ID

Plans

Pricing and billing plans attached to products.

GET

/v1/SubscriptionPlan

List Subscription Plans

Retrieve all subscription plans with OData filtering.

Query Parameters

Name	Type	Required	Description
$filter	string	Optional	e.g. productId eq 1
$expand	string	Optional	Include related entities
$top	number	Optional	Page size
$skip	number	Optional	Offset
$count	boolean	Optional	Include total count

Response

{
  "@odata.count": 5,
  "value": [
    {
      "id": 1,
      "merchantId": 10,
      "productId": 1,
      "productName": "Pro Suite",
      "name": "Monthly",
      "description": "Billed monthly",
      "status": "Active",
      "amount": "49.99",
      "currency": "USD",
      "timeUnit": "Month",
      "timeInterval": 1,
      "subscriptionBillingType": "Recurring",
      "validFrom": "2024-01-01T00:00:00Z"
    }
  ]
}

POST

/v1/SubscriptionPlan

Create Subscription Plan

Create a new subscription plan linked to a product.

Request Body

{
  "productId": 1,
  "name": "Annual",
  "description": "Billed yearly at a discount",
  "amount": "499.99",
  "currency": "USD",
  "timeUnit": "Year",
  "timeInterval": 1,
  "subscriptionBillingType": "Recurring",
  "status": "Active"
}

PATCH

/v1/SubscriptionPlan/{id}

Update Subscription Plan

Update an existing subscription plan.

Path Parameters

Name	Type	Required	Description
id	number	Required	Plan ID

DELETE

/v1/SubscriptionPlan/{id}

Delete Subscription Plan

Delete a subscription plan.

Path Parameters

Name	Type	Required	Description
id	number	Required	Plan ID

Inventory

Track physical or digital inventory items linked to products.

GET

/v1/SubscriptionInventoryItem

List Inventory Items

Retrieve subscription inventory items with OData filtering by status and product.

Query Parameters

Name	Type	Required	Description
$filter	string	Optional	e.g. status eq 'Available' and productId eq 1
$orderby	string	Optional	'id desc'
$top	number	Optional	Page size
$skip	number	Optional	Offset
$count	boolean	Optional	Include total count

Response

{
  "@odata.count": 50,
  "value": [
    {
      "id": 1,
      "productId": 1,
      "productName": "Pro Suite",
      "serialNumber": "SN-001-ABC",
      "status": "Available",
      "createdDateTime": "2024-03-01T10:00:00Z"
    },
    {
      "id": 2,
      "productId": 1,
      "productName": "Pro Suite",
      "serialNumber": "SN-002-DEF",
      "status": "Rented",
      "createdDateTime": "2024-03-01T10:00:00Z"
    }
  ]
}

POST

/v1/SubscriptionInventoryItem

Create Inventory Item

Add a new inventory item to a subscription product.

Request Body

{
  "productId": 1,
  "serialNumber": "SN-003-GHI",
  "status": "Available"
}

PATCH

/v1/SubscriptionInventoryItem/{id}

Update Inventory Item

Update an inventory item (e.g. change status or serial number).

Path Parameters

Name	Type	Required	Description
id	number	Required	Item ID

Request Body

{
  "status": "Rented"
}

DELETE

/v1/SubscriptionInventoryItem/{id}

Delete Inventory Item

Delete an inventory item.

Path Parameters

Name	Type	Required	Description
id	number	Required	Item ID

Enums

SubscriptionProductType

Service

Digital

Physical

SubscriptionPlanStatus

Active

Inactive

Archived

SubscriptionBillingType

Recurring

OneTime

Usage

TimeUnit

Day

Week

Month

Year

SubscriptionInventoryItemStatus

Available

Rented

Reserved

Discontinued

Types

SubscriptionProductDto

interface SubscriptionProductDto {
  id: number;
  merchantId: number;
  name: string;
  description?: string;
  subscriptionProductType: SubscriptionProductType;
  media?: MediaDto[];
}

SubscriptionPlanDto

interface SubscriptionPlanDto {
  id: number;
  merchantId: number;
  productId: number;
  productName?: string;
  name: string;
  description?: string;
  details?: string;
  status: SubscriptionPlanStatus;
  amount: string;                  // Decimal as string
  currency: string;
  timeUnit: TimeUnit;              // Day, Week, Month, Year
  timeInterval: number;            // e.g. 1 for monthly, 3 for quarterly
  subscriptionBillingType: SubscriptionBillingType;
  validFrom?: string;
  validTo?: string;
}

SubscriptionInventoryItemDto

interface SubscriptionInventoryItemDto {
  id: number;
  productId: number;
  productName?: string;
  serialNumber?: string;
  status: SubscriptionInventoryItemStatus;
}

Usage Examples

Create a product with plans

TypeScript

// Step 1: Create the product
const { data: product } = await client.post('/v1/SubscriptionProduct', {
  name: 'Business Suite',
  description: 'Complete business management toolkit',
  subscriptionProductType: 'Service',
});

// Step 2: Create plans for the product
await client.post('/v1/SubscriptionPlan', {
  productId: product.id,
  name: 'Monthly',
  amount: '29.99',
  currency: 'USD',
  timeUnit: 'Month',
  timeInterval: 1,
  subscriptionBillingType: 'Recurring',
  status: 'Active',
});

await client.post('/v1/SubscriptionPlan', {
  productId: product.id,
  name: 'Annual',
  amount: '299.99',
  currency: 'USD',
  timeUnit: 'Year',
  timeInterval: 1,
  subscriptionBillingType: 'Recurring',
  status: 'Active',
});

Manage inventory items

TypeScript

// List available inventory for a product
const { data } = await client.get('/v1/SubscriptionInventoryItem', {
  params: {
    $filter: "productId eq 1 and status eq 'Available'",
    $count: true,
    $top: 20,
  },
});

console.log(`${data['@odata.count']} items available`);

// Reserve an item
await client.patch(`/v1/SubscriptionInventoryItem/${data.value[0].id}`, {
  status: 'Reserved',
});

// Mark as rented after payment
await client.patch(`/v1/SubscriptionInventoryItem/${data.value[0].id}`, {
  status: 'Rented',
});