Manage subscriptions

Update, cancel, resume, and list subscriptions using the Subscriptions API.

Retrieve a subscription

GET /api/v1/subscriptions/:id

Returns the full subscription object. Use this to check status, current_period_end, latest_payment_link, and (for auto_charge) auto_charge details.

Example:

curl https://api.orcarail.com/api/v1/subscriptions/sub_550e8400e29b41d4a716446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

List subscriptions

GET /api/v1/subscriptions

Supports cursor-based pagination and filters.

Query parameters

Parameter	Type	Description
status	string	Filter by status: trialing, active, past_due, canceled, paused, completed
collection_method	string	Filter by send_payment_link or auto_charge
current_period_start	object	Filter by period: gt, gte, lt, lte (ISO timestamps)
current_period_end	object	Same as above for period end
created	object	Filter by created: gt, gte, lt, lte
limit	number	Page size (default 10, max 100)
starting_after	string	Cursor: subscription ID to start after
ending_before	string	Cursor: subscription ID to end before

Example:

curl "https://api.orcarail.com/api/v1/subscriptions?status=active&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response shape:

{
  "object": "list",
  "data": [ { ... subscription objects ... } ],
  "has_more": false
}

Update a subscription

PATCH /api/v1/subscriptions/:id

Partial update. Only send fields you want to change.

Updatable fields

Parameter	Type	Description
description	string	Subscription description
amount	string	New amount per period
currency	string	Currency code
token_id	string	Token ID
network_id	string	Network ID
collection_method	string	send_payment_link or auto_charge
cancel_at	string | null	ISO timestamp to cancel at, or null to clear
cancel_at_period_end	boolean	Cancel at end of current period
days_until_due	number	Days after period end until overdue
trial_end	string	When trial ends (ISO or "now")
metadata	object	Key-value metadata
withdrawal_addresses	object	Chain type → address
pause_collection	object | null	{ "behavior": "void" | "keep_as_draft" } to pause; null to resume

Example (cancel at period end):

curl -X PATCH https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true }'

Example (pause collection):

{
  "pause_collection": { "behavior": "void" }
}

Cancel a subscription

DELETE /api/v1/subscriptions/:id

Cancel immediately or at period end (if you previously set cancel_at_period_end). Request body is optional.

Cancel body (optional)

Parameter	Type	Description
cancellation_details	object	Optional feedback
cancellation_details.comment	string	Free-text comment
cancellation_details.feedback	string	One of: too_expensive, missing_features, switched_service, unused, other

Example:

curl -X DELETE https://api.orcarail.com/api/v1/subscriptions/sub_xxx \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_details": {
      "comment": "Switching to annual",
      "feedback": "other"
    }
  }'

Resume a subscription

POST /api/v1/subscriptions/:id/resume

Resumes a paused subscription. No body required. After resume, the subscription returns to active and the next cycle will create a payment link or run auto-charge as configured.

Example:

curl -X POST https://api.orcarail.com/api/v1/subscriptions/sub_xxx/resume \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

List payment links for a subscription

GET /api/v1/subscriptions/:id/payment-links

Returns payment links (one per billing cycle) for this subscription. Supports pagination (e.g. limit, starting_after, ending_before). Use this to show cycle history or link status per period.

Example:

curl "https://api.orcarail.com/api/v1/subscriptions/sub_xxx/payment-links?limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Next steps

• Create a subscription — Create with trial or auto-charge
• Subscription webhooks — Handle subscription events
• Trials — Trial period behavior