Subscriptions Overview

OrcaRail Subscriptions let you collect recurring crypto payments from payers. The REST API uses a conventional subscription resource with snake_case fields. OrcaRail adds auto_charge, where OrcaRail's hot wallet pulls each period from the payer's wallet on EVM (ERC-20 allowance and transferFrom) or Solana (SPL token delegation). Auto-charge does not run on Bitcoin.

What are Subscriptions?

A subscription represents a recurring payment agreement between you (the merchant) and a payer. Each billing cycle, you either:

• Send a payment link — OrcaRail creates a PaymentLink for the period and (optionally) emails the payer.
• Auto-charge — The payer approves once (EVM allowance or Solana delegation); OrcaRail pulls the period amount each cycle.

Subscriptions support fixed intervals (day, week, month, year), optional trial periods, and a familiar status lifecycle.

Common fields

Concept	OrcaRail
Customer / payer	payer (user ID or email)
Line item / price	amount + currency + token_id + network_id (single item, crypto-native)
Automatic charging	collection_method: auto_charge (pull via EVM allowance or Solana delegation)
Invoice / pay-by-link each cycle	collection_method: send_payment_link (PaymentLink per cycle, optional email)
Latest payable artifact	latest_payment_link
Status lifecycle	trialing, active, past_due, canceled, paused, completed (crypto-adapted)
Scheduling & metadata	cancel_at_period_end, trial_end, billing_cycle_anchor, metadata

Collection methods

send_payment_link (default)

Each billing cycle, OrcaRail creates a PaymentLink for the subscription amount. You can email the payer (e.g. 1 day before due). The payer opens the link and pays with their wallet as with any one-time payment. No allowance or auto-pull.

• Use when: You want the payer to explicitly approve each payment, or you don't need automatic charging.
• Flow: Billing cron creates PaymentLink → optional email → payer pays via hosted pay app.

auto_charge

The payer approves once for the chosen network: on EVM, an ERC-20 allowance for a total or per-period pattern; on Solana, SPL delegation to OrcaRail's pull path. Each cycle, the billing job uses the hot wallet to pull the period amount (EVM transferFrom or Solana batch transfer).

• Use when: You want true recurring charges without the payer visiting a link every period.
• Flow: Payer approves on first cycle or subscribe page (see approval_spender_address on auto_charge) → each cycle the billing job pulls from the payer → on success the cycle is marked paid; on failure the subscription can move to past_due and the payer is notified.

See Auto-charge for the approval flow, payer-facing steps to approve or revoke, and API details.

Subscription object (response shape)

Responses use snake_case and follow this subscription shape:

{
  "id": "sub_550e8400e29b41d4a716446655440000",
  "object": "subscription",
  "status": "active",
  "collection_method": "send_payment_link",
  "amount": "10.00",
  "currency": "usd",
  "description": "Monthly Pro Plan",
  "token": { "id": "...", "symbol": "USDC", "name": "USD Coin" },
  "network": { "id": "...", "name": "Base", "chain_id": 8453 },
  "interval": "month",
  "interval_count": 1,
  "total_cycles": 12,
  "completed_cycles": 3,
  "billing_cycle_anchor": 1679609767,
  "current_period_start": "2025-03-01T00:00:00Z",
  "current_period_end": "2025-04-01T00:00:00Z",
  "start_date": "2025-01-01T00:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "trial_start": null,
  "trial_end": null,
  "auto_charge": null,
  "payer": { "id": "...", "email": "[email protected]" },
  "latest_payment_link": {
    "id": "...",
    "unique_slug": "...",
    "link": "...",
    "status": "completed"
  },
  "withdrawal_addresses": { "evm": "0x742d..." },
  "metadata": {},
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-03-15T00:00:00Z"
}

When collection_method is auto_charge, the auto_charge object includes payer wallet and token/network IDs, optional allowance_tx_hash, approved_amount, approved_iterations, approval_spender_address (the spender or delegate the payer must approve on-chain), and status. See Auto-charge for approve, revoke, and set-collection-method endpoints.

Example shape when approved:

"auto_charge": {
  "payer_wallet_address": "0x...",
  "payer_network_id": "...",
  "payer_token_id": "...",
  "allowance_tx_hash": "0x...",
  "approved_amount": "120.00",
  "approved_iterations": 12,
  "approval_spender_address": "0x...",
  "status": "approved"
}

Status lifecycle

Status	Description
trialing	In trial period; no payment required until trial ends
active	Current; payment links created each cycle or auto-charge runs
past_due	A cycle payment failed or was overdue
canceled	Subscription ended (immediate or at period end)
paused	Paused (e.g. after trial with no payment method)
completed	All cycles finished (total_cycles reached)

Billing cycle flow

Next steps

• Create a subscription — Create your first subscription via API
• Manage subscriptions — Update, cancel, resume, list
• Auto-charge — EVM and Solana pull flow and payer endpoints
• Subscription webhooks — Event types and payloads
• Trials — Trial periods and behavior