API Reference
Subscriptions API
Full reference for Plans, Subscriptions, and Invoices endpoints.
Plans
POST /plans
Create a plan.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Plan display name |
amount | integer | yes | Amount in smallest unit |
currency | string | yes | ISO 4217 currency |
interval | string | yes | day | week | month | year |
interval_count | integer | no | Default 1 |
trial_period_days | integer | no | Default trial length for new subscriptions |
metadata | object | no |
GET /plans/:id
Retrieve a plan.
GET /plans
List all plans. Filter with ?active=true.
POST /plans/:id/archive
Archive a plan. Prevents new subscriptions; existing subscriptions continue.
Subscriptions
POST /subscriptions
Create a subscription.
| Field | Type | Required | Description |
|---|---|---|---|
customer_id | string | yes | Customer to subscribe |
plan_id | string | yes | Plan to subscribe to |
payment_method_id | string | no | Saved payment method to charge |
trial_period_days | integer | no | Override plan default |
trial_end | ISO 8601 | no | Explicit trial end date |
cancel_at_period_end | boolean | no | |
metadata | object | no |
curl https://api.xtopay.co/v1/subscriptions \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_abc123",
"plan_id": "plan_pro_xyz",
"trial_period_days": 14
}'GET /subscriptions/:id
Retrieve a subscription.
PATCH /subscriptions/:id
Update a subscription. Accepted fields: plan_id, proration_behavior, cancel_at_period_end, payment_method_id, trial_end, metadata.
POST /subscriptions/:id/cancel
| Field | Type | Description |
|---|---|---|
cancel_at_period_end | boolean | If true, cancel at end of period; if false, cancel immediately |
POST /subscriptions/:id/reactivate
Reactivate a subscription that was set to cancel at period end but hasn't cancelled yet.
POST /subscriptions/:id/pause
| Field | Type | Description |
|---|---|---|
resumes_at | ISO 8601 | Optional auto-resume date |
POST /subscriptions/:id/resume
Resume a paused subscription.
GET /subscriptions
List subscriptions. Filter with ?customer_id=, ?status=, ?plan_id=.
Invoices
GET /invoices/:id
Retrieve an invoice.
GET /invoices/:id/pdf
Download invoice as PDF. Returns a redirect to a signed URL.
POST /invoices/:id/void
Void an open invoice.
GET /invoices
List invoices. Filter with ?customer_id=, ?subscription_id=, ?status=.