Subscriptions API

Manage your organization's subscription plan.

note

Subscription endpoints need a user session, such as the JWT from the CLI's device-code login, plus x-organization-id. API keys are rejected with 403, and the user must be an owner or admin of the organization. See Authentication.

Create a checkout session

Start a new subscription by creating a Stripe checkout session.

POST /api/v1/subscription/create

curl -X POST https://app.hooklistener.com/api/v1/subscription/create \
  -H "Authorization: Bearer <jwt_token>" \
  -H "x-organization-id: <organization-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro_monthly"
  }'

Field	Type	Description
plan	string	pro_monthly, pro_yearly, production_monthly, production_yearly, scale_monthly or scale_yearly
trial	boolean	Start the 7-day Pro trial. Applies only to Pro plans and organizations that are eligible for the trial; otherwise it is ignored.

Response:

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

Redirect the user to the url to complete payment.

Cancel a subscription

POST /api/v1/subscription/cancel

curl -X POST https://app.hooklistener.com/api/v1/subscription/cancel \
  -H "Authorization: Bearer <jwt_token>" \
  -H "x-organization-id: <organization-id>"

The subscription remains active until the end of the current billing period.

Response:

{
  "status": "success",
  "message": "Subscription will be cancelled at the end of the current period",
  "cancel_at_period_end": true,
  "current_period_end": "2026-10-25T00:00:00Z"
}

Resume a cancelled subscription

If you've cancelled but are still within the billing period, you can resume:

POST /api/v1/subscription/resume

curl -X POST https://app.hooklistener.com/api/v1/subscription/resume \
  -H "Authorization: Bearer <jwt_token>" \
  -H "x-organization-id: <organization-id>"

Response:

{
  "status": "success",
  "message": "Subscription has been resumed",
  "cancel_at_period_end": false,
  "current_period_end": "2026-10-25T00:00:00Z"
}

Plan management

To view your current plan and features, use the organization plan endpoint:

curl https://app.hooklistener.com/api/v1/organizations/<org-id>/plan \
  -H "Authorization: Bearer <jwt_token>" \
  -H "x-organization-id: <organization-id>"

See Plans & Billing for plan comparisons.