API Reference

Plan-upgrade error contract

Every ScoopDesk Pro endpoint that rejects a request because the workspace's plan is insufficient returns the same JSON shape with HTTP status 402 Payment Required. This contract is regression-tested in CI and will not change without a version bump.

Response shape

{
  "error": "plan_upgrade_required",
  "code": "plan_upgrade_required",
  "message": "SMS blasts require the Pack plan or higher.",
  "feature": "sms_blasts",
  "current_plan": "solo",
  "required_plan": "pack",
  "upgrade_url": "/pricing"
}

Fields

error & code — both always equal "plan_upgrade_required". Stable; safe to switch on.
message — human-readable, safe to surface in UI.
feature — which gated capability was attempted (see table below).
current_plan — solo, pack, command, or unknown.
required_plan — minimum plan that unlocks the feature.
upgrade_url — relative URL to send the user to upgrade.

Gated features

feature	required_plan	Surface
sms_blasts	pack	POST /functions/v1/send-sms-blast
tech_weekly_summaries	pack	POST /api/public/hooks/tech-weekly-summaries
quickbooks_export	command	Insert into invoice_exports (RLS) + export endpoints
automations_active_cap	pack	Solo workspaces are capped at 3 simultaneously enabled automations

Client handling

The web app catches any 402 with this shape and renders a global upgrade modal pointing at /app/settings#subscription. Third-party integrations should match on code === "plan_upgrade_required" and surface message directly.

See /pricing for the full plan matrix.