Retrieve an organization's billing
Reads the organization's Voidhash subscription, this period's usage and charges, and the plans it can switch to.
Only a person with permission to update the organization can read it.
Guide: Plans and billing
AuthorizationBearer <token>
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
Path parameters
organizationId*string
The organization's id, org_....
Examples
curl -X GET "https://api.voidhash.com/api/v1/organizations/org_w5xk2e7q0lzv3n8b1c4d6f9g/billing" \ -H "Authorization: Bearer vh_sk_..."{ "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": "string", "message": "string", "param": "string" }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "person_credential_required", "message": "Only a person can do this; project secret keys cannot." }}{ "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": "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": "billing_unavailable", "message": "This Voidhash deployment does not bill through Stripe." }}Response body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
Errors
| Status | type | code | When |
|---|---|---|---|
| 403 | permission_denied | person_credential_required | For a project secret key or a person without that permission. |
| 403 | permission_denied | permission_denied | For a project secret key or a person without that permission. |
| 503 | unavailable | billing_unavailable | When this deployment does not bill through Stripe. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in Billing
- Update an organization's billing
PATCH - Start a checkout
POST - Open the billing portal
POST
Something wrong or missing on this page? Tell us by email or on Discord.