Subscription API
Manage subscriptions, usage tracking, billing, and plan upgrades
Overview
The Subscription API provides endpoints for managing user subscriptions, monitoring usage, accessing billing information, and handling plan upgrades or downgrades.
💳
Real-time Usage Tracking
All endpoints provide real-time access to subscription status, usage metrics, and billing information.
GET
/subscriptions/current
Retrieve the current subscription details for the authenticated user.
Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Response (200 OK)
{
"success": true,
"data": {
"subscription_id": "sub_abc123",
"user_id": "usr_xyz789",
"tier": "professional",
"status": "active",
"current_period_start": "2025-10-01T00:00:00Z",
"current_period_end": "2025-11-01T00:00:00Z",
"cancel_at_period_end": false,
"pricing": {
"amount": 19900,
"currency": "USD",
"interval": "month"
},
"features": {
"transactions_limit": 10000,
"users_limit": 10,
"integrations_limit": 5,
"storage_gb": 50,
"api_rate_limit": 5000
}
}
}
GET
/subscriptions/usage
Get current usage metrics for the authenticated user's subscription.
Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Query Parameters
| Parameter | Type | Description |
|---|
| period | string | current, last_month, last_7_days, last_30_days (default: current) |
Response (200 OK)
{
"success": true,
"data": {
"period": {
"start": "2025-10-01T00:00:00Z",
"end": "2025-11-01T00:00:00Z"
},
"usage": {
"transactions": {
"used": 3847,
"limit": 10000,
"percentage": 38.47
},
"users": {
"used": 7,
"limit": 10,
"percentage": 70.0
},
"integrations": {
"used": 3,
"limit": 5,
"percentage": 60.0
},
"storage": {
"used_gb": 23.5,
"limit_gb": 50,
"percentage": 47.0
},
"api_calls": {
"used": 125847,
"limit": 100000,
"percentage": 125.85,
"overage_charges": 2584
}
},
"warnings": [
{
"type": "api_overage",
"message": "You have exceeded your API call limit by 25.85%",
"action": "Consider upgrading to Business plan"
}
]
}
}
POST
/subscriptions/upgrade
Upgrade or downgrade the current subscription to a different tier.
Request Body
{
"new_tier": "business",
"interval": "month",
"proration": true
}
Parameters
| Field | Required | Description |
|---|
| new_tier | Yes | free, starter, professional, business, enterprise |
| interval | No | month or year (default: month) |
| proration | No | Apply proration credits (default: true) |
Response (200 OK)
{
"success": true,
"data": {
"subscription_id": "sub_abc123",
"previous_tier": "professional",
"new_tier": "business",
"effective_date": "2025-10-30T12:00:00Z",
"proration_credit": 9950,
"next_invoice_amount": 39950,
"next_invoice_date": "2025-11-01T00:00:00Z"
}
}
POST
/subscriptions/cancel
Cancel the current subscription (takes effect at period end).
Request Body
{
"reason": "switching_to_competitor",
"feedback": "Need more advanced features",
"cancel_immediately": false
}
Response (200 OK)
{
"success": true,
"data": {
"subscription_id": "sub_abc123",
"status": "active",
"cancel_at_period_end": true,
"cancellation_date": "2025-11-01T00:00:00Z",
"access_until": "2025-11-01T00:00:00Z"
}
}
GET
/subscriptions/invoices
Retrieve billing invoices for the authenticated user.
Query Parameters
| Parameter | Type | Description |
|---|
| limit | number | Number of invoices to return (default: 10, max: 100) |
| starting_after | string | Invoice ID for pagination |
Response (200 OK)
{
"success": true,
"data": {
"invoices": [
{
"id": "inv_abc123",
"number": "INV-2025-001234",
"status": "paid",
"amount_due": 19900,
"amount_paid": 19900,
"currency": "USD",
"period_start": "2025-10-01T00:00:00Z",
"period_end": "2025-11-01T00:00:00Z",
"created": "2025-10-01T00:00:00Z",
"paid_at": "2025-10-01T00:05:23Z",
"pdf_url": "https://api.organiko.ai/v1/invoices/inv_abc123/pdf"
}
],
"has_more": true,
"total_count": 24
}
}
GET
/subscriptions/invoices/:id
Retrieve a specific invoice by ID.
Response (200 OK)
{
"success": true,
"data": {
"id": "inv_abc123",
"number": "INV-2025-001234",
"status": "paid",
"line_items": [
{
"description": "Organiko.ai Professional Plan",
"quantity": 1,
"amount": 19900,
"period": {
"start": "2025-10-01T00:00:00Z",
"end": "2025-11-01T00:00:00Z"
}
},
{
"description": "API Overage (25,847 calls)",
"quantity": 1,
"amount": 2584
}
],
"subtotal": 22484,
"tax": 0,
"total": 22484,
"amount_paid": 22484,
"currency": "USD",
"pdf_url": "https://api.organiko.ai/v1/invoices/inv_abc123/pdf"
}
}
GET
/subscriptions/payment-methods
List all saved payment methods for the authenticated user.
Response (200 OK)
{
"success": true,
"data": {
"payment_methods": [
{
"id": "pm_abc123",
"type": "card",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2026
},
"is_default": true
}
]
}
}
Common Error Codes
| Code | Status | Description |
|---|
| subscription_not_found | 404 | No active subscription found |
| invalid_tier | 400 | Invalid subscription tier specified |
| payment_failed | 402 | Payment method declined or failed |
| usage_limit_exceeded | 429 | Subscription usage limit exceeded |
Subscription Webhooks
Receive real-time notifications when subscription events occur (upgrades, cancellations, payment failures, etc.)
Learn about Webhooks →