Integration v1.0

Partner API Docs

Billing-system-agnostic provisioning API. One integration covers account creation, plan management, SSO, and usage reporting for any billing platform.

Jump to endpoints Become a partner

14

Endpoints

REST

JSON over HTTPS

Bearer

Token auth

Agnostic

Any billing system

Getting started

Authentication and base URL

Every request carries your reseller API key as a Bearer token. All data is automatically scoped to your reseller account.

Bearer token

Include your API key in every request header.

Authorization: Bearer {your_api_key}

Base URLs

https://brandforge.software/api/godmode/v1 Production

https://staging.brandforge.software/api/godmode/v1 Staging

Standard response envelope

Every response follows the same shape. Check success first, then read data for the payload or error on failure.

Success

{
  "success": true,
  "message": "Account created",
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Validation failed"
}
Endpoints

Full API reference

14 endpoints covering the complete account lifecycle. Every endpoint returns the standard envelope.

Connection

GET /provision/ping

Test that your API key is valid and the service is reachable. Use this as a health check in your provisioning module.

Parameters

None

Response 200

Standard envelope with success: true

Catalog

GET /provision/packages

Returns the plans available under your reseller account. Use the slug field as plan_code in subsequent calls.

Parameters

None

Response 200 · data[]

idstringInternal package ID
namestringDisplay name, e.g. "Solo Plan"
slugstringUse as plan_code
product_idstring | nullYour billing product ID if mapped

Account

POST /provision/create

Provision a new customer account. Idempotent on email within a reseller. Send your external IDs to enable billing deep-links.

Request body

emailstring requiredCustomer email
first_namestring requiredCustomer first name
plan_codestring requiredSlug from /provision/packages
last_namestringCustomer last name
company_namestringCompany name
passwordstringOmit to auto-generate
domainstringCustomer domain
client_idstringYour billing client ID
service_id_externalstringYour billing service ID
product_idstringYour billing product ID

Response 201 · data

service_iduuidBrandForge service identifier
emailstringConfirmed email
company_namestringCompany name
statusstring"active"
plan_codestringActive plan slug
domainstring | nullCustomer domain

Errors

409ConflictEmail already used by another account
422ValidationMissing or invalid parameters
POST /provision/suspend

Suspend the entire customer account. All plans and access are frozen.

Request body

service_iduuid requiredBrandForge service ID
POST /provision/unsuspend

Reactivate a suspended account. Access is restored immediately.

Request body

service_iduuid requiredBrandForge service ID
POST /provision/terminate

Cancel and permanently remove the customer account.

Request body

service_iduuid requiredBrandForge service ID
POST /provision/link_account

Set or update external billing IDs on an existing account. Enables upgrade/downgrade deep-links from the BrandForge app back to your billing system.

Request body

service_iduuid requiredBrandForge service ID
client_idstringYour billing client ID
service_id_externalstringYour billing service ID
plan_codestringCurrent plan slug
product_idstringYour billing product ID

Plans

POST /provision/add_plan

Add an additional plan to an account. Additive: existing plans are kept. Credits and limits sum across all active plans.

Request body

service_iduuid requiredBrandForge service ID
plan_codestring requiredPlan slug to add
product_idstringYour billing product ID

Response 200 · data

service_idstringConfirmed service ID
statusstring"active"
added_planstringThe plan that was added
active_plansstring[]All active plan slugs
POST /provision/change_package

Replace the active plan (upgrade or downgrade). Credits and limits carry forward automatically.

Request body

service_iduuid requiredBrandForge service ID
plan_codestring requiredNew plan slug
POST /provision/suspend_plan

Suspend a single plan on a multi-plan account. Other plans stay active.

Request body

service_iduuid requiredBrandForge service ID
plan_codestring requiredPlan slug to suspend

Response 200 · data

service_idstringConfirmed service ID
plan_codestringThe suspended plan
statusstringNew plan status
active_plansstring[]Remaining active plans
POST /provision/unsuspend_plan

Reactivate a suspended plan. The plan resumes with its previous credits and limits.

Request body

service_iduuid requiredBrandForge service ID
plan_codestring requiredPlan slug to reactivate
POST /provision/terminate_plan

Cancel and remove a single plan. Other plans on the account stay active.

Request body

service_iduuid requiredBrandForge service ID
plan_codestring requiredPlan slug to terminate

Session

POST /provision/sso

Generate a short-lived login URL. Open it in the customer's browser and they land authenticated in BrandForge. No second password required.

Request body

service_iduuid requiredBrandForge service ID

Response 200 · data

tokenstringOne-time SSO token
login_urluriRedirect the customer here
plansPlanEntry[]Active plans with credits and workspace limits
PlanEntry object
idstringPlan entry ID
plan_codestringPlan slug
statusstringactive, suspended, etc.
primarybooleanWhether this is the primary plan
creditsintegerCredits on this plan
max_workspacesintegerWorkspace limit on this plan

Status

GET /provision/status

Query a customer's current plan, credit usage, and workspace list. Useful for displaying usage in your client area.

Query parameters

service_iduuid requiredBrandForge service ID

Response 200 · data

package
plan_codestringActive plan slug
max_workspacesintegerWorkspace cap
credits
allocatedintegerTotal credits for this period
usedintegerCredits consumed
remainingintegerCredits left
over_limitbooleanTrue if usage exceeds allocation
period_enddateWhen the current billing period ends
workspaces
totalintegerTotal workspaces created
activeintegerCurrently active
list[]objectEach with id, name, slug
Common questions

API FAQ

Is the API billing-system specific?

No. The API is billing-system-agnostic. WHMCS, Upmind, Blesta, HostBill, or any custom platform all use the same endpoints.

How is authentication handled?

Every request carries your reseller API key as a Bearer token in the Authorization header. All data is automatically scoped to your reseller account.

Can a customer hold multiple plans?

Yes. The add_plan endpoint is additive. A customer may hold multiple plans and credits and limits sum across them. You can also suspend or terminate individual plans independently.

Is account creation idempotent?

Yes. The create endpoint is idempotent on email within a reseller. If the email already exists under your reseller, you get the existing account back instead of a duplicate.

What external IDs can I pass?

Three: client_id (your billing customer), service_id_external (your billing subscription), and product_id (your billing product). These enable deep-links from BrandForge back to your billing system for upgrades and downgrades.

Is there a staging environment?

Yes. Use https://staging.brandforge.software/api/godmode/v1 with your staging API key. Same endpoints, same behaviour, isolated data.

Ready to integrate?

Connect your billing system to BrandForge in hours, not weeks

Grab your API key from the partner portal and start calling endpoints. Full lifecycle in 14 requests.

Get your API key See all integrations
  • REST + JSON
  • Bearer auth
  • Staging environment
  • Any billing platform