Skip to main content
A subscription ties a customer to a plan for recurring billing. Customers subscribe to a published plan, and the system handles billing at each interval. You can list, retrieve, pay, and cancel subscriptions through the SDK. 
import { createOakClient, createSubscriptionService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const subscriptions = createSubscriptionService(client);

​
Methods

MethodDescription
subscribe(request)Subscribe a customer to a plan
cancel(subscriptionId)Cancel an active subscription
list(query?)List subscriptions with optional filters
get(subscriptionId)Get a subscription by ID
pay(subscriptionId, request)Make a payment on a subscription

​
Subscribe

const result = await subscriptions.subscribe({
  plan_id: 'plan_abc123',
  customer_id: 'cus_abc123',
  payment_method_id: 'pm_xyz789',
});

if (result.ok) {
  console.log('Subscription ID:', result.value.data.id);
  console.log('Status:', result.value.data.status);
}

​
Subscribe request fields

FieldTypeRequiredDescription
plan_idstringYesThe plan to subscribe to
customer_idstringYesThe customer subscribing
payment_method_idstringYesPayment method for billing

​
Cancel a subscription

const result = await subscriptions.cancel('sub_abc123');

if (result.ok) {
  console.log('Subscription cancelled');
}

​
List subscriptions

const result = await subscriptions.list({
  limit: 20,
  offset: 0,
});

if (result.ok) {
  for (const sub of result.value.data) {
    console.log(`${sub.id} — ${sub.status}`);
  }
}

​
Get a subscription

const result = await subscriptions.get('sub_abc123');

if (result.ok) {
  const sub = result.value.data;
  console.log('Plan:', sub.plan_id);
  console.log('Status:', sub.status);
  console.log('Next billing:', sub.next_billing_date);
}

​
Pay a subscription

Manually trigger a payment on a subscription (e.g., for retry after a failed automatic payment): 
const result = await subscriptions.pay('sub_abc123', {
  amount: 2999,
  payment_method_id: 'pm_xyz789',
});

if (result.ok) {
  console.log('Payment processed:', result.value.data);
}

​
Subscription statuses

Subscriptions move through several statuses during their lifecycle, including active, paused, cancelled, and expired states.

​
Response data

FieldTypeDescription
idstringSubscription ID
plan_idstringAssociated plan ID
customer_idstringSubscribing customer ID
statusStatusCurrent subscription status
payment_method_idstringPayment method used
next_billing_datestringNext billing date
created_atstringISO timestamp
updated_atstringISO timestamp