Subscriptions

Subscriptions enable recurring billing for your customers. Dimebia handles the entire subscription lifecycle from signup to cancellation.

Overview

A subscription represents a recurring billing agreement between you and a customer. Subscriptions automatically generate invoices on a scheduled basis.

Subscription Lifecycle

Active → Past Due → Cancelled/Expired
   ↓
Paused → Resumed

Create a Subscription

POST /api/subscription/create

Request Body

Field	Type	Required	Description
customerId	Long	Yes	Customer ID
planId	Long	Yes	Plan ID
quantity	Integer	No	Number of seats/units (default: 1)
trialDays	Integer	No	Free trial period in days
couponId	String	No	Discount coupon code
metadata	Object	No	Custom key-value pairs

Example

curl -X POST http://localhost:8080/api/subscription/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "customerId": 1,
    "planId": 1,
    "quantity": 5,
    "trialDays": 14
  }'

Subscription Plans

Plans define the pricing and billing cycle for subscriptions:

Field	Description
name	Plan name (e.g., "Pro", "Enterprise")
interval	Billing interval: DAY, WEEK, MONTH, YEAR
intervalCount	Number of intervals (e.g., 2 for bi-monthly)
amount	Price per unit in cents
currency	Currency code
trialDays	Free trial period
metadata	Custom metadata

Billing Cycles

Dimebia supports flexible billing cycles:

• Monthly: Most common, billed every month
• Yearly: Annual billing with discount
• Weekly: For short-term services
• Custom: Define your own intervals

Subscription Status

Status	Description
ACTIVE	Subscription is active
TRIALING	In free trial period
PAST_DUE	Payment failed, retry pending
CANCELLED	Cancelled by user or admin
EXPIRED	Subscription term ended
PAUSED	Temporarily paused

Manage Subscriptions

# Cancel subscription
POST /api/subscription/{id}/cancel

# Update subscription
POST /api/subscription/{id}/update

# Activate paused subscription
POST /api/subscription/{id}/activate

# Mark as past due
POST /api/subscription/{id}/mark-past-due

# Expire subscription
POST /api/subscription/{id}/expire

Metered Billing

For usage-based pricing:

POST /api/subscription/{id}/usage

{
  "quantity": 100,
  "timestamp": "2026-08-18T10:00:00Z",
  "metadata": {
    "apiCalls": 1000
  }
}

Code Examples

Node.js

// Create subscription
const subscription = await client.subscriptions.create({
  customerId: 1,
  planId: 1,
  trialDays: 14,
});

// Cancel at period end
await client.subscriptions.update(subscription.id, {
  cancelAtPeriodEnd: true,
});

// List subscriptions
const subscriptions = await client.subscriptions.list({
  customerId: 1,
  status: 'ACTIVE',
});