A subscription bills a customer for one product price on a schedule. Roamerwave creates each period's invoice and sends the payment request, and you read the results.
If subscriptions are not enabled for your workspace, these calls answer 404 CAPABILITY_DISABLED.
1. Create a product and a price
curl https://api.roamerwave.com/v1/products \
-H "Authorization: Bearer rw_test_…" \
-H "Idempotency-Key: product-membership" \
-H "Content-Type: application/json" \
-d '{
"reference": "membership",
"name": "Monthly membership",
"description": "Unlimited access to the studio."
}'
The response has the product id (starting prod_). Add a price to it:
curl https://api.roamerwave.com/v1/products/prod_…/prices \
-H "Authorization: Bearer rw_test_…" \
-H "Idempotency-Key: price-membership-1350" \
-H "Content-Type: application/json" \
-d '{ "amount": { "minor": "135000", "currency": "KES" } }'
The price has its own id (starting price_). To charge a different amount, add a new price.
2. Subscribe the customer
You need a customer (quick start), the product id and the price id. The anchor says when each period starts: dayOfMonth (1 to 28) for a monthly cadence, or an ISO weekday (1 for Monday to 7 for Sunday) for a weekly one. Set exactly one.
curl https://api.roamerwave.com/v1/subscriptions \
-H "Authorization: Bearer rw_test_…" \
-H "Idempotency-Key: sub-amina-membership" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_…",
"productId": "prod_…",
"priceId": "price_…",
"cadence": "monthly",
"anchor": { "dayOfMonth": 1 }
}'
start chooses the first period. The default, next_period, begins at the next anchor and invoices nothing until then. current_period starts the period containing today and issues its invoice immediately. Periods run on Nairobi time.
A subscription activates when its first invoice is paid. Until then it is not active, and a failed or unknown first payment does not activate it.
3. Follow the billing cycles
curl https://api.roamerwave.com/v1/subscriptions/sub_…/billing-cycles \
-H "Authorization: Bearer rw_test_…"
Each cycle names its period and the invoice issued for it. Read that invoice for its paymentStatus, reconciliationStatus and settlementStatus, exactly as for any other invoice. A cycle whose payment result is unknown stays unknown until the provider's records resolve it. See Take a payment.
4. Pause, resume or cancel
curl -X POST https://api.roamerwave.com/v1/subscriptions/sub_…/pause \
-H "Authorization: Bearer rw_test_…" \
-H "Idempotency-Key: pause-sub-amina-1"
resume and cancel work the same way on /resume and /cancel.
Customers who sign themselves up
Instead of creating the subscription yourself, create a sign-up link with POST /v1/enrollment-links and give it to the customer. They review the plan and terms on a hosted page and set up their payment there. Revoke a link at any time with POST /v1/enrollment-links/{enrollmentLinkId}/revoke.
Messaging consent
A customer you add without confirming their consent to SMS still gets the subscription and its invoices, but Roamerwave sends them no payment request or reminder. Share their checkout link yourself. To record consent when you add a customer, set smsConsentAttested to true only if the customer has agreed to receive payment requests by SMS from you.