Billing
Subscriptions
Build recurring billing with plans, prices, and dunning management.
Overview
Subscriptions allow you to charge customers on a recurring basis. Create products and prices, then subscribe customers to automatically generate invoices and process payments on their billing cycle.
Plans & prices
Flexible billing intervals
Free trials
Configurable trial periods
Smart retries
Automatic dunning management
Create a subscription
Create a subscription by attaching a customer to a price. The API returns the new subscription in active status, computes the first billing period from the price interval, and dispatches a subscription.created webhook.
curl https://paymenthooks.com/api/v1/subscriptions \
-X POST \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_abc123",
"priceId": "price_monthly_pro",
"trialEndAt": "2026-07-22T00:00:00.000Z",
"metadata": { "plan": "pro" }
}'Required fields: customerId and priceId. Optional: gatewayConnectionId (specific gateway), trialEndAt (ISO 8601), and arbitrary metadata. Returns 201 on success, 400 if the required fields are missing, 404 if the price does not exist, or 500 on a server error.
Endpoints & Responses
Complete payload and response for every subscription endpoint. Click copy on any block.
/v1/subscriptionsCreate a subscription{
"customerId": "cus_abc123",
"priceId": "price_monthly_pro",
"gatewayConnectionId": "gwc_abc123",
"trialEndAt": "2026-07-22T00:00:00.000Z",
"metadata": { "plan": "pro" }
}{
"data": {
"id": "sub_abc123",
"customerId": "cus_abc123",
"productId": "prod_abc123",
"priceId": "price_monthly_pro",
"status": "active",
"currentPeriodStart": "2026-05-01T00:00:00.000Z",
"currentPeriodEnd": "2026-06-01T00:00:00.000Z",
"nextPaymentAt": "2026-06-01T00:00:00.000Z",
"trialEndsAt": null,
"metadata": { "plan": "pro" },
"createdAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/subscriptions?page=1&pageSize=10&status=activeList subscriptions{
"data": [
{
"id": "sub_abc123",
"customerId": "cus_abc123",
"priceId": "price_monthly_pro",
"status": "active",
"currentPeriodStart": "2026-05-01T00:00:00.000Z",
"currentPeriodEnd": "2026-06-01T00:00:00.000Z",
"metadata": { "plan": "pro" },
"createdAt": "2026-01-01T00:00:00.000Z"
}
],
"meta": { "total": 24, "page": 1, "pageSize": 10 },
"error": null
}/v1/subscriptions/:idRetrieve a subscription{
"data": {
"id": "sub_abc123",
"customerId": "cus_abc123",
"priceId": "price_monthly_pro",
"status": "active",
"currentPeriodStart": "2026-05-01T00:00:00.000Z",
"currentPeriodEnd": "2026-06-01T00:00:00.000Z",
"cancelAtPeriodEnd": false,
"metadata": { "plan": "pro" },
"merchantId": "mer_abc123",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-05-01T00:00:00.000Z"
},
"error": null
}/v1/subscriptions/:idUpdate a subscription{
"priceId": "price_yearly_pro",
"metadata": { "plan": "pro", "billing": "annual" }
}{
"data": {
"id": "sub_abc123",
"customerId": "cus_abc123",
"priceId": "price_yearly_pro",
"status": "active",
"metadata": { "plan": "pro", "billing": "annual" },
"updatedAt": "2026-05-16T10:30:00.000Z"
},
"error": null
}/v1/subscriptions/:id/pausePause a subscription{
"data": {
"id": "sub_abc123",
"status": "paused",
"pausedAt": "2026-05-16T10:30:00.000Z",
"updatedAt": "2026-05-16T10:30:00.000Z"
},
"error": null
}/v1/subscriptions/:id/resumeResume a paused subscription{
"data": {
"id": "sub_abc123",
"status": "active",
"resumedAt": "2026-05-16T11:00:00.000Z",
"currentPeriodStart": "2026-05-16T11:00:00.000Z",
"currentPeriodEnd": "2026-06-16T11:00:00.000Z",
"updatedAt": "2026-05-16T11:00:00.000Z"
},
"error": null
}/v1/subscriptions/:id/cancelCancel a subscription{
"data": {
"id": "sub_abc123",
"status": "canceled",
"canceledAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:00:00.000Z"
},
"error": null
}Subscription lifecycle
trialingCustomer is in their trial period. No charges until trial ends.activeSubscription is active and billing normally.past_dueLatest invoice payment failed. Retrying per dunning schedule.pausedSubscription is paused. No charges until resumed.canceledSubscription has been canceled. No further charges.unpaidAll retry attempts exhausted. Requires manual action.Dunning & smart retries
When a subscription payment fails, PaymentHooks automatically retries using an intelligent schedule.
- 1Retry 1: 3 days after failure
- 2Retry 2: 5 days after first retry
- 3Retry 3: 7 days after second retry
- 4Final: mark subscription as unpaid