P
PUGUH
EN Get Started

Billing & Subscription

PUGUH menangani manajemen subscription, invoicing, dan usage metering sehingga Anda bisa fokus membangun produk.

Paket

PaketHargaTermasuk
FreeRp 03 anggota, 1 aplikasi, 1 GB storage, fitur dasar
ProRp 299K/bulan20 anggota, 5 aplikasi, 10 GB storage, MFA, webhooks
BusinessRp 990K/bulan100 anggota, 25 aplikasi, 100 GB storage, SSO, SCIM, audit streaming
EnterpriseCustomAnggota unlimited, aplikasi unlimited, storage custom, SLA, dedicated support

Siklus Hidup Subscription

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

Membuat 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"
}

Status Subscription

StatusDeskripsi
activeSubscription aktif dan pembayaran berjalan
past_duePembayaran gagal, sedang di-retry
grace_periodDibatalkan tapi masih aktif hingga akhir periode
cancelledDiturunkan ke paket Free
suspendedAkun ditangguhkan karena pelanggaran kebijakan

Invoice

Daftar Invoice

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

Metode Pembayaran

PUGUH menggunakan Midtrans untuk pemrosesan pembayaran di Indonesia.

Menambah Metode Pembayaran

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"
  }'

Metode yang Didukung

MetodeTipe
Kartu Kredit/DebitVisa, Mastercard, JCB
Transfer BankBCA, BNI, BRI, Mandiri
E-WalletGoPay, ShopeePay, OVO

Mengatur Metode Pembayaran Default

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

Usage Metering

Pantau konsumsi resource terhadap kuota paket:

Ringkasan Penggunaan

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 }
  }
}

Penggunaan API Detail

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

Mengubah Paket

Upgrade

Upgrade berlaku segera. Anda akan dikenakan biaya prorata untuk sisa periode billing.

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

Downgrade

Downgrade berlaku di akhir periode billing saat ini. Fitur yang melebihi batas paket baru menjadi read-only.

Batal

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

Setelah pembatalan, Anda memiliki masa tenggang 7 hari di mana Anda bisa mengaktifkan kembali.

Event Webhook

Subscribe ke event billing untuk update real-time:

EventDeskripsi
billing.subscription.createdSubscription baru dimulai
billing.subscription.updatedPaket diubah
billing.subscription.cancelledSubscription dibatalkan
billing.invoice.createdInvoice baru dibuat
billing.invoice.paidPembayaran diterima
billing.invoice.overduePembayaran terlambat
billing.usage.thresholdPenggunaan mendekati batas (80%)

Contoh SDK

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")

Praktik Terbaik

  1. Pantau penggunaan untuk menghindari batas atau biaya tak terduga
  2. Atur webhook billing untuk menangani perubahan subscription secara programatis
  3. Perbarui metode pembayaran untuk menghindari gangguan subscription
  4. Download invoice secara rutin untuk catatan akuntansi
  5. Mulai dengan Free dan upgrade sesuai kebutuhan

Terkait