Subscription Management via the API

This guide describes the complete flow for creating and managing recurring subscriptions via the Sangho API, from plan creation to lifecycle management.

Subscription sign-up flow

1. Create a Customer for the subscriber
2. Collect a payment method (PaymentIntent with confirm: true)
3. Create the Subscription linking Customer, unit_amount, interval, and PaymentMethod
4. Listen for subscription.created to confirm activation
5. Handle subscription.trial_ending and subscription.past_due events

Failed payment handling (Dunning)

Sangho automatically retries failed payments on the following schedule: D+3, D+7, D+14. After 3 failures, the subscription moves to unpaid status. The subscription.past_due event is emitted on each attempt.

Modify a subscription

To change the amount or payment method, use PATCH: /subscriptions/{id}/. To temporarily pause, use POST: /subscriptions/{id}/pause/.

Complete flow

bash

# 1. Create the customer
curl -X POST https://api.sangho.ga/v1/customers/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "subscriber@example.com", "name": "Jean Ondo"}'
# 2. Create the subscription
curl -X POST https://api.sangho.ga/v1/subscriptions/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cust_xxx",
    "unit_amount": 9900,
    "interval": "month",
    "trial_period_days": 7
  }'