Skip to main content

Subscriptions (Node SDK)

The OrcaRail Node.js SDK supports creating and managing subscriptions with the same REST API contracts (including snake_case request fields where applicable).

Merchant vs payer APIs​

The SDK covers merchant-authenticated operations: create, retrieve, update, cancel, resume, list, and list payment links (same as Manage subscriptions).

Payer-facing calls are not in @orcarail/node. Implement them over HTTP from your hosted pay app or browser (no API key), same as the OrcaRail pay UI:

  • POST /api/v1/subscriptions/:id/approve-auto-charge
  • POST /api/v1/subscriptions/:id/revoke-auto-charge
  • POST /api/v1/subscriptions/:id/set-collection-method

See Auto-charge for request bodies and behavior.

Installation​

Same as the main SDK:

npm install @orcarail/node

Client setup​

Use the same client as for Payment Intents; subscriptions use the same auth (API key or Bearer), and merchant subscription collection calls infer organization from the authenticated API key.

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!,
  { baseUrl: 'https://api.orcarail.com/api/v1' }
)

Create a subscription​

const subscription = await orcarail.subscriptions.create({
  description: 'Monthly Pro Plan',
  amount: '10.00',
  currency: 'usd',
  token_id: tokenId,
  network_id: networkId,
  interval: 'month',
  interval_count: 1,
  collection_method: 'send_payment_link',
  total_cycles: 12,
  payer_email: '[email protected]',
  metadata: { plan_id: 'pro_monthly' },
})

console.log(subscription.id)
console.log(subscription.current_period_end)
console.log(subscription.latest_payment_link?.link)

Retrieve a subscription​

const subscription = await orcarail.subscriptions.retrieve(
  'sub_550e8400e29b41d4a716446655440000'
)
console.log(subscription.status, subscription.completed_cycles)

List subscriptions​

const { data, has_more } = await orcarail.subscriptions.list({
  status: 'active',
  limit: 20,
  starting_after: 'sub_previous_id', // optional cursor
})

for (const sub of data) {
  console.log(sub.id, sub.description, sub.current_period_end)
}

Update a subscription​

const updated = await orcarail.subscriptions.update(
  'sub_550e8400e29b41d4a716446655440000',
  {
    cancel_at_period_end: true,
    metadata: { reason: 'customer_requested' },
  }
)

Cancel a subscription​

await orcarail.subscriptions.cancel('sub_550e8400e29b41d4a716446655440000', {
  cancellation_details: {
    comment: 'Switching to annual',
    feedback: 'other',
  },
})

Resume a subscription​

await orcarail.subscriptions.resume('sub_550e8400e29b41d4a716446655440000')
const { data } = await orcarail.subscriptions.listPaymentLinks(
  'sub_550e8400e29b41d4a716446655440000',
  { limit: 10 }
)

Webhook handling​

Subscription events use the same webhook endpoint and constructEvent as Payment Intents:

const event = orcarail.webhooks.constructEvent(
  rawBody,
  req.headers['x-webhook-signature'],
  process.env.ORCARAIL_WEBHOOK_SECRET!
)

switch (event.type) {
  case 'subscription.created':
    console.log('Subscription created:', event.data.object.id)
    break
  case 'subscription.payment_link.paid':
    console.log('Cycle paid:', event.data.object.id)
    break
  case 'subscription.canceled':
    console.log('Canceled:', event.data.object.id)
    break
  case 'subscription.past_due':
    console.log('Past due:', event.data.object.id)
    break
  // ... other subscription.* types
}

Types (TypeScript)​

The SDK exports subscription types aligned with the API:

  • Subscription — full subscription object
  • SubscriptionCreateParams — create payload
  • SubscriptionUpdateParams — update payload
  • SubscriptionCancelParams — cancel payload
  • SubscriptionStatus, SubscriptionInterval, SubscriptionCollectionMethod — enums

See Node SDK API Reference for full type definitions.

Next steps​