Update an organization's billing
Changes the plan, schedules or undoes the subscription's cancellation at the period's end, or sets the spend cap, and returns the billing.
The changes apply in that order, and repeating a request is safe. A plan change moves an active Stripe subscription immediately; to subscribe for the first time, create a checkout session.
Guide: Plans and billing
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
Path parameters
The organization's id, org_....
Request body
application/json
TypeScript definitions
Use the request body type in TypeScript.
Moves the Stripe subscription to this plan version from availablePlans, effective now.
True ends the subscription when the period ends; false undoes a pending cancellation.
The spend cap in minor units of currency, at least the plan's base price and at most 1,000,000,000; null removes it.
Examples
curl -X PATCH "https://api.voidhash.com/api/v1/organizations/org_w5xk2e7q0lzv3n8b1c4d6f9g/billing" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "spendCap": 20000 }'{ "organizationId": "org_w5xk2e7q0lzv3n8b1c4d6f9g", "currency": "USD", "subscription": { "plan": { "id": "bplanv_g4r7w2t9k5m1x8c3v6b0n4q2", "planId": "bplan_g4r7w2t9k5m1x8c3v6b0n4q2", "key": "growth", "name": "Growth", "description": "For apps with paying customers.", "highlights": [ "1M events a month", "Unlimited paywalls", "Email support" ], "version": 3, "collection": "stripe_checkout", "basePrice": 4900, "currency": "USD", "meters": [ { "meter": "events", "included": 1000000, "overage": { "blockSize": 100000, "tiers": [ { "upTo": 4000000, "pricePerBlock": 400 }, { "upTo": null, "pricePerBlock": 250 } ] } }, { "meter": "page_views", "included": 500000, "overage": null } ] }, "status": "active", "collection": "stripe_checkout", "isInForce": true, "currentPeriodStart": "2026-11-01T00:00:00.000Z", "currentPeriodEnd": "2026-12-01T00:00:00.000Z", "isCanceledAtPeriodEnd": false, "hasBillingPortal": true, "scheduledChange": null }, "usage": { "periodStart": "2026-11-01T00:00:00.000Z", "periodEnd": "2026-12-01T00:00:00.000Z", "pausedBy": null, "isSpendCapAvailable": true, "spendCap": 20000, "currentCharge": 5700, "meters": [ { "meter": "events", "unit": "event", "used": 1184210, "included": 1000000, "isHardLimit": false, "overageCharge": 800, "percentUsed": 118, "isApproachingLimit": false, "isOverLimit": true, "isPaused": false, "pausedBy": null }, { "meter": "page_views", "unit": "event", "used": 212480, "included": 500000, "isHardLimit": true, "overageCharge": 0, "percentUsed": 42, "isApproachingLimit": false, "isOverLimit": false, "isPaused": false, "pausedBy": null } ] }, "availablePlans": [ { "id": "bplanv_f2k8m4x9c1v6b3n7q0w5e2r8", "planId": "bplan_f2k8m4x9c1v6b3n7q0w5e2r8", "key": "free", "name": "Free", "description": null, "highlights": [ "100K events a month", "One paywall" ], "version": 2, "collection": "none", "basePrice": 0, "currency": "USD", "meters": [ { "meter": "events", "included": 100000, "overage": null }, { "meter": "page_views", "included": 50000, "overage": null } ], "isOffered": false }, { "id": "bplanv_g4r7w2t9k5m1x8c3v6b0n4q2", "planId": "bplan_g4r7w2t9k5m1x8c3v6b0n4q2", "key": "growth", "name": "Growth", "description": "For apps with paying customers.", "highlights": [ "1M events a month", "Unlimited paywalls", "Email support" ], "version": 3, "collection": "stripe_checkout", "basePrice": 4900, "currency": "USD", "meters": [ { "meter": "events", "included": 1000000, "overage": { "blockSize": 100000, "tiers": [ { "upTo": 4000000, "pricePerBlock": 400 }, { "upTo": null, "pricePerBlock": 250 } ] } }, { "meter": "page_views", "included": 500000, "overage": null } ], "isOffered": false } ]}{ "error": { "type": "invalid_request", "code": "plan_unavailable", "message": "This plan is not available to the organization.", "param": "planVersionId" }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "permission_denied", "message": "Insufficient permissions." }}{ "error": { "type": "not_found", "code": "organization_not_found", "message": "There is no organization org_w5xk2e7q0lzv3n8b1c4d6f9g, or this credential cannot use it.", "param": "organizationId" }}{ "error": { "type": "conflict", "code": "plan_change_conflict", "message": "Another billing change for this organization is in progress; try again." }}{ "error": { "type": "internal", "code": "internal_error", "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing." }}{ "error": { "type": "unavailable", "code": "string", "message": "string", "param": "string" }}Response body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
Errors
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request | plan_unavailable | For a planVersionId not in availablePlans. |
| 400 | invalid_request | spend_cap_below_base_price | For a cap under the plan's base price. |
| 409 | conflict | plan_change_conflict | While the plan cannot change now, such as without a Stripe subscription or during another change. |
| 409 | conflict | no_stripe_subscription | When there is no Stripe subscription to cancel or resume. |
| 409 | conflict | spend_cap_unavailable | When the plan has no usage pricing to cap. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in Billing
Something wrong or missing on this page? Tell us by email or on Discord.