P
PUGUH
ID Get Started

Billing & Subscription

PUGUH handles subscription management, invoicing, and usage metering so you can focus on building your product.

Plans

PlanPriceIncludes
FreeRp 03 members, 1 app, 1 GB storage, basic features
ProRp 299K/month20 members, 5 apps, 10 GB storage, MFA, webhooks
BusinessRp 990K/month100 members, 25 apps, 100 GB storage, SSO, SCIM, audit streaming
EnterpriseCustomUnlimited members, unlimited apps, custom storage, SLA, dedicated support

Subscription Lifecycle

plaintext 
Free (default)
  → Upgrade to Pro/Business
    → Active subscription
      → Renews monthly (auto-charge)
      → OR: Cancel → grace period (7 days) → downgrade to Free

Enterprise: Contact sales → custom agreement → manual activation

Creating a Subscription

Via API

bash 
curl -X POST https://api-puguh.arsaka.io/billing/subscriptions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -d '{
    "plan": "pro",
    "billing_cycle": "monthly",
    "payment_method_id": "pm_abc123"
  }'

Response:

json 
{
  "id": "sub_abc123",
  "organization_id": "org_xxx",
  "plan": "pro",
  "status": "active",
  "billing_cycle": "monthly",
  "current_period_start": "2026-02-20T00:00:00Z",
  "current_period_end": "2026-03-20T00:00:00Z",
  "created_at": "2026-02-20T10:00:00Z"
}

Subscription Status

StatusDescription
activeSubscription is active and payment is current
past_duePayment failed, retrying
grace_periodCancelled but still active until period ends
cancelledDowngraded to Free plan
suspendedAccount suspended for policy violation

Invoices

List Invoices

bash 
curl https://api-puguh.arsaka.io/billing/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Response:

json 
{
  "items": [
    {
      "id": "inv_abc123",
      "number": "INV-2026-0001",
      "amount": 299000,
      "currency": "IDR",
      "status": "paid",
      "period_start": "2026-01-20T00:00:00Z",
      "period_end": "2026-02-20T00:00:00Z",
      "paid_at": "2026-02-20T00:05:00Z",
      "pdf_url": "/billing/invoices/inv_abc123/pdf"
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20,
  "has_next": false,
  "has_prev": false
}

Download Invoice PDF

bash 
curl https://api-puguh.arsaka.io/billing/invoices/inv_abc123/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o invoice.pdf

Payment Methods

PUGUH uses Midtrans for payment processing in Indonesia.

Add Payment Method

bash 
curl -X POST https://api-puguh.arsaka.io/billing/payment-methods \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "credit_card",
    "token": "tok_from_midtrans_snap"
  }'

Supported Methods

MethodType
Credit/Debit CardVisa, Mastercard, JCB
Bank TransferBCA, BNI, BRI, Mandiri
E-WalletGoPay, ShopeePay, OVO

Set Default Payment Method

bash 
curl -X POST https://api-puguh.arsaka.io/billing/payment-methods/pm_abc123/default \
  -H "Authorization: Bearer YOUR_TOKEN"

Usage Metering

Track resource consumption against plan quotas:

Get Usage Overview

bash 
curl https://api-puguh.arsaka.io/billing/usage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Organization-ID: YOUR_ORG_ID"

Response:

json 
{
  "plan": "pro",
  "period": "2026-02",
  "metrics": {
    "api_calls": { "used": 45000, "quota": 100000, "percent": 45.0 },
    "members": { "used": 8, "quota": 20, "percent": 40.0 },
    "applications": { "used": 3, "quota": 5, "percent": 60.0 },
    "storage_bytes": { "used": 2147483648, "quota": 10737418240, "percent": 20.0 },
    "webhooks": { "used": 5, "quota": 10, "percent": 50.0 }
  }
}

Detailed API Usage

bash 
curl https://api-puguh.arsaka.io/billing/usage/api-calls?period=2026-02 \
  -H "Authorization: Bearer YOUR_TOKEN"

Changing Plans

Upgrade

Upgrades take effect immediately. You'll be charged a prorated amount for the remaining billing period.

bash 
curl -X POST https://api-puguh.arsaka.io/billing/subscriptions/sub_abc123/change \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"plan": "business"}'

Downgrade

Downgrades take effect at the end of the current billing period. Features beyond the new plan's limits become read-only.

Cancel

bash 
curl -X POST https://api-puguh.arsaka.io/billing/subscriptions/sub_abc123/cancel \
  -H "Authorization: Bearer YOUR_TOKEN"

After cancellation, you have a 7-day grace period during which you can reactivate.

Webhook Events

Subscribe to billing events for real-time updates:

EventDescription
billing.subscription.createdNew subscription started
billing.subscription.updatedPlan changed
billing.subscription.cancelledSubscription cancelled
billing.invoice.createdNew invoice generated
billing.invoice.paidPayment received
billing.invoice.overduePayment past due
billing.usage.thresholdUsage approaching limit (80%)

SDK Examples

TypeScript

typescript 
import { PuguhClient } from '@arsaka/puguh-sdk';

const client = new PuguhClient({ apiKey: 'YOUR_KEY' });

// Get current subscription
const sub = await client.billing.getSubscription('org_abc');
console.log(sub.plan, sub.status);

// Get usage
const usage = await client.billing.getUsage('org_abc');
console.log(`API calls: ${usage.metrics.api_calls.percent}% used`);

// List invoices
const invoices = await client.billing.listInvoices('org_abc');

Python

python 
from puguh_sdk import PuguhClient

client = PuguhClient(api_key="YOUR_KEY")

# Get subscription
sub = client.billing.get_subscription("org_abc")
print(f"Plan: {sub.plan}, Status: {sub.status}")

# Get usage
usage = client.billing.get_usage("org_abc")
print(f"API calls: {usage.metrics['api_calls']['percent']}% used")

Best Practices

  1. Monitor usage to avoid unexpected limits or charges
  2. Set up billing webhooks to handle subscription changes programmatically
  3. Keep payment methods updated to avoid subscription interruption
  4. Download invoices regularly for accounting records
  5. Start with Free and upgrade as your needs grow

Related