Create a subscription

Create a subscription to start collecting recurring payments from a payer.

Endpoint

POST /api/v1/subscriptions

Authentication

Requires Payments Auth: Bearer token (JWT) or API key (Basic).

Request body (snake_case)

Request body uses snake_case:

Parameter	Type	Required	Description
description	string	Yes	Description of the subscription (e.g. "Monthly Pro Plan")
amount	string	Yes	Amount per billing period (e.g. "10.00")
currency	string	Yes	Three-letter ISO currency code (e.g. usd)
token_id	string	Yes	Token ID to receive (e.g. USDC)
network_id	string	Yes	Network ID for receipt
interval	string	Yes	Billing interval: day, week, month, year
interval_count	number	No	Number of intervals per period (default 1)
collection_method	string	No	send_payment_link (default) or auto_charge
total_cycles	number	No	Total billing cycles; omit or null for infinite
billing_cycle_anchor	string	No	ISO timestamp for first period start
cancel_at	string	No	ISO timestamp to cancel at
cancel_at_period_end	boolean	No	If true, cancel at end of current period
days_until_due	number	No	Days after period end before considered overdue
trial_end	string	No	ISO timestamp when trial ends (or "now" to skip trial)
trial_period_days	number	No	Number of trial days from creation
payer_user_id	string	No	Registered payer user ID
payer_email	string	No	Payer email for notifications and payment links
withdrawal_addresses	object	No	Keys: chain type (e.g. evm), value: address
metadata	object	No	Key-value metadata

Response

Returns the full subscription object (see Overview) with status, current_period_start, current_period_end, and (for send_payment_link) the first cycle's payment link when applicable.

Examples

cURL

curl -X POST https://api.orcarail.com/api/v1/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly Pro Plan",
    "amount": "10.00",
    "currency": "usd",
    "token_id": "uuid-for-usdc",
    "network_id": "uuid-for-base",
    "interval": "month",
    "interval_count": 1,
    "collection_method": "send_payment_link",
    "total_cycles": 12,
    "payer_email": "[email protected]"
  }'

JavaScript (fetch)

const response = await fetch('https://api.orcarail.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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' },
  }),
})

const subscription = await response.json()
console.log('Subscription ID:', subscription.id)
console.log('Current period end:', subscription.current_period_end)

With trial

{
  "description": "Pro Plan with trial",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

Auto-charge

{
  "description": "Yearly Pro (auto-charge)",
  "amount": "100.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "year",
  "collection_method": "auto_charge",
  "total_cycles": 1,
  "payer_email": "[email protected]"
}

When using auto_charge, the payer must later approve the ERC-20 allowance (see Auto-charge).

Next steps

• Manage subscriptions — Update, cancel, resume, list
• Auto-charge — Allowance approval flow
• Subscription webhooks — React to subscription events