Create a recurring charge mandate
Records a recurring charge mandate. Creating one moves no money: the first charge runs at start_at (now when omitted) and the scheduler charges once per interval after that, retrying a failed perio...
/v1/subscriptionsRecords a recurring charge mandate. Creating one moves no money: the first charge runs at start_at (now when omitted) and the scheduler charges once per interval after that, retrying a failed period before the subscription goes past due. Requires subscriptions:write and an Idempotency-Key; an API key may subscribe any user, a user token only itself (forbidden, 403). Refuses user_not_found or merchant_not_found (404), invalid_request (400), and idempotency_key_reuse (409) when the key comes back with a different body.
Authorization
bearerAuth A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.
In: header
Header Parameters
1 <= length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
curl -sS -X POST "$WALLETD_API/v1/subscriptions" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: sub-user-42-foodpass" \ -d '{"user_id": "'$USER_ID'", "merchant_id": "'$MERCHANT_ID'", "plan_name": "FoodPass", "amount": 999, "interval": "monthly"}'{ "id": "0191c2dc-6a91-7b35-8c62-19f4d807ae53", "user_id": "0191c2d4-8f3a-7c51-9b2e-4a6f8d310e27", "merchant_id": "0191c2d6-1a44-7b09-8e73-2c5f9a08d641", "plan_name": "FoodPass", "amount": 999, "commission": 0, "interval": "monthly", "status": "active", "next_charge_at": "2026-09-20T09:20:00Z", "retry_count": 0, "created_at": "2026-09-20T09:20:00Z"}