Record a subscription
POST /subscriptions records a subscriber after the onchain handshake.
POST/subscriptions
Call this after the subscriber's approve and create_vault transactions are confirmed. It sets next_billing_date to now, so the first cycle can be pulled right away. A wallet can subscribe to a given plan only once.
Body
plan_iduuidrequired
Plan being subscribed to. Must be a valid UUID.
customer_wallet_addressstringrequired
Subscriber's Stellar account (G...). Must be a valid Ed25519 public key.
Request
curl -X POST http://localhost:3001/subscriptions \
-H "Content-Type: application/json" \
-d '{ "plan_id": "7c1e2d4a-...", "customer_wallet_address": "GDQP...4N2" }'Response 201
{
"message": "Subscription created",
"subscription": {
"id": "b2a9e4c1-...",
"plan_id": "7c1e2d4a-...",
"customer_wallet_address": "GDQP...4N2",
"status": "active",
"next_billing_date": "2026-09-25T10:00:00Z"
}
}Errors
| Status | When |
|---|---|
400 | plan_id is not a valid UUID, or customer_wallet_address is not a valid Stellar public key |
404 | No plan has this plan_id |
500 | Database error, including a wallet that is already subscribed to this plan |