Skip to main content

Subscriptions (SDKs)

The OrcaRail Node.js and PHP SDKs support creating and managing subscriptions with the same REST API contracts (including snake_case request fields where applicable). The examples below use the Node.js SDK; see PHP SDK for the PHP equivalents.

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 or orcarail/orcarail-php. 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
composer require orcarail/orcarail-php

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
}

PHP SDK​

The PHP SDK exposes the same operations on $orcarail->subscriptions, with associative-array parameters and OrcaRailObject responses. Listing is all() rather than list(), since list is a PHP reserved word.

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$subscription = $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'],
]);

echo $subscription->id;
echo $subscription->latest_payment_link?->link;

$page = $orcarail->subscriptions->all(['status' => 'active', 'limit' => 20]);
foreach ($page->data as $sub) {
    echo $sub->id . ' ' . $sub->current_period_end . PHP_EOL;
}

$orcarail->subscriptions->retrieve($subscription->id);
$orcarail->subscriptions->update($subscription->id, ['cancel_at_period_end' => true]);
$orcarail->subscriptions->cancel($subscription->id, [
    'cancellation_details' => ['comment' => 'Switching to annual', 'feedback' => 'other'],
]);
$orcarail->subscriptions->resume($subscription->id);
$orcarail->subscriptions->listPaymentLinks($subscription->id, ['limit' => 10]);

Subscription webhooks use the same static helper as Payment Intents:

$event = \OrcaRail\Webhook::constructEvent(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    getenv('ORCARAIL_WEBHOOK_SECRET'),
);

if ($event->type === 'subscription.payment_link.paid') {
    // credit the cycle for $event->data->object->id
}

See the PHP SDK API Reference for every parameter and return shape.

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​