Subscriptions

A subscription bills a customer's saved card on a schedule. You state the amount and the interval when you make it. Each charge it makes, the first one included, is an ordinary payment that names the subscription.

Make a subscription

Save the customer's card first, as Customers and saved cards shows. Then:

curl https://api.kashupay.com/v1/subscriptions \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: plan-4471-monthly" \
  -H "Content-Type: application/json" \
  -d '{"customer":"cu_...","payment_method":"pm_...","amount":1500,"currency":"USD","interval":"month","description":"Monthly plan"}'

payment_method must be a card saved for that customer.
interval is day, week, month or year. interval_count makes each period span several intervals, such as 3 months, and a period is at most a year.
The first charge is made at once.

The subscription's status is active once it is billing. current_period_start, current_period_end and next_billing_at say where it is. A subscription that could not be made answers 201 with status failed, the way a declined charge answers a failed payment.

Follow its payments

Every charge arrives as a payment whose subscription names the subscription, with the usual payment.* events. When a renewal is declined, you get a failed payment that names the subscription, and the subscription's status does not change. Decide in your own code what to do next, such as asking the buyer for another card.

To bill now instead of waiting, POST /v1/subscriptions/{id}/charge_now. It bills only when the next charge is due within 12 hours. Otherwise nothing is charged, and the subscription comes back unchanged.

Cancel a subscription

curl https://api.kashupay.com/v1/subscriptions/sb_.../cancel \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: plan-4471-cancel" \
  -H "Content-Type: application/json" \
  -d '{"at_period_end":true}'

By default a cancel takes effect at the end of the current period: cancel_at_period_end becomes true and nothing is billed after the period ends. Send at_period_end false to cancel now. Either way, subscription.canceled arrives once Kashu records that the subscription has ended.

To undo a cancel scheduled for the period's end, POST /v1/subscriptions/{id}/resume. A subscription that has already ended cannot be resumed, and answers 400 subscription_unexpected_state.

Follow a subscription by webhook

subscription.created arrives when it is made. subscription.updated arrives when it changes: it becomes active, its billing dates move, a cancel is scheduled or undone, or it could not be made. subscription.canceled arrives once Kashu records that it has ended.

What is not available yet

A subscription's terms are fixed once it is made. You cannot change its amount, interval or card, start it on a later date, give it a trial, or apply a discount. To change terms, cancel the subscription and make a new one.