Billing

Subscription Integration Guide

Copy page

Overview

The Subscription API enables recurring billing with automatic payment collection. You can create plans, manage subscriptions, and handle the complete subscription lifecycle from initiation to cancellation.

Subscription Lifecycle

Code
 
Plan Created → Subscription Initiated → Payment Processed → Active
                                                        ↓
                                          Past Due → Unpaid / Cancelled

Key Concepts

• Plan: Defines the amount, currency, and billing interval
• Subscription: A customer's recurring billing agreement
• Invoice: Generated automatically per billing cycle
• Payment Intent: Embedded in invoices for payment collection

Quick Start

Step 1: Create a Plan

Code
 
import { SaligPay } from "saligpay-node";

const saligpay = new SaligPay({
    clientId: process.env.SALIGPAY_CLIENT_ID!,
    clientSecret: process.env.SALIGPAY_CLIENT_SECRET!,
    env: "sandbox",
});

await saligpay.authenticate();

const plan = await saligpay.subscriptions.createPlan({
    name: "Premium Monthly",
    amount: 49900, // ₱499.00
    currency: "PHP",
    interval: "monthly",
    interval_count: 1,
    description: "Premium plan billed monthly",
});

console.log("Plan ID:", plan.id);

Step 2: Initiate a Subscription

Code
 
const subscription = await saligpay.subscriptions.initiate({
    plan_id: plan.id,
    customer_email: "customer@example.com",
    customer_name: "Juan Dela Cruz",
    customer_phone: "+639123456789",
    billing_address: {
        line1: "123 Main St",
        city: "Manila",
        state: "Metro Manila",
        postal_code: "1000",
        country: "PH",
    },
});

console.log("Session Token:", subscription.sessionToken);
console.log("Client Secret:", subscription.clientSecret);

Step 3: Process Payment

Code
 
const result = await saligpay.subscriptions.processPayment({
    sessionToken: subscription.sessionToken,
    payment_method_id: "pm_gcash_abc123",
});

console.log("Subscription ID:", result.subscriptionId);
console.log("Status:", result.status);

API Reference

Plan Management

Create Plan

POST /api/subscription/plans

Code
 
{
    "name": "Premium Monthly",
    "description": "Premium subscription plan",
    "amount": 49900,
    "currency": "PHP",
    "interval": "month",
    "intervalCount": 1,
    "billingScheme": "charged_per_interval"
}

List Plans

GET /api/subscription/plans?limit=10&after=plan_xxx

Get Plan

GET /api/subscription/plans/{planId}

Subscription Management

Initiate Subscription

POST /api/subscription/initiate

Code
 
{
    "plan_id": "plan_premium_monthly",
    "customer_email": "customer@example.com",
    "customer_name": "Juan Dela Cruz",
    "customer_phone": "+639123456789",
    "billing_address": {
        "line1": "123 Main St",
        "city": "Manila",
        "postal_code": "1000",
        "country": "PH"
    }
}

Process Subscription Payment

POST /api/subscription/process-payment

Code
 
{
    "sessionToken": "550e8400-e29b-41d4-a716-446655440002",
    "paymentMethodId": "pm_gcash_abc123"
}

Get Subscription

GET /api/subscription/{subscriptionId}

List Subscriptions

GET /api/subscription?status=active&limit=10

Update Plan

PATCH /api/subscription/{subscriptionId}/plan

Code
 
{
    "planId": "plan_enterprise_monthly"
}

Update Payment Method

PATCH /api/subscription/{subscriptionId}/payment-method

Code
 
{
    "paymentMethodId": "pm_grab_pay_xyz"
}

Cancel Subscription

DELETE /api/subscription/{subscriptionId}?reason=requested_by_customer

SDK Reference

SubscriptionResource

Method	Description
initiate(options)	Start subscription with payment setup
processPayment(options)	Process the initial payment
getSession(sessionToken)	Get subscription session details
get(subscriptionId)	Get subscription details
list(query?)	List subscriptions with filters
updatePlan(subscriptionId, dto)	Change plan (next cycle)
updatePaymentMethod(subscriptionId, dto)	Update payment method
cancel(subscriptionId, reason?)	Cancel subscription
createPlan(data)	Create a subscription plan
listPlans(query?)	List plans
getPlan(planId)	Get plan details

Subscription Statuses

Status	Description
incomplete	Initial status; first payment must succeed
incomplete_cancelled	Auto-cancelled after 24 hours if unpaid
active	All invoices paid successfully
past_due	Latest invoice payment failed; auto-retried
unpaid	Invoice failed after 3 retries
cancelled	Subscription manually cancelled

Webhook Events

Handle these subscription webhook events:

Event	Action
subscription.activated	Mark subscription as active
subscription.past_due	Notify customer of failed payment
subscription.unpaid	Suspend service
subscription.cancelled	Clean up resources
subscription.invoice.paid	Log successful payment
subscription.invoice.payment_failed	Log failure, notify customer

Best Practices

• Plan changes take effect on the next billing cycle
• Implement webhook handlers for real-time status updates
• Use getSession() to retrieve payment details for frontend
• Handle past_due status with retry notifications
• Store subscription IDs for customer account management

---

Related Guides:

• Webhooks Guide - For subscription event handling
• Plans SDK - For plan management details