Skip to content

Feature Gating and Paywall Responses

Some Partner API endpoints are restricted to workspaces on a minimum billing plan. When a request targets a gated endpoint and the workspace plan is below the required tier, the API returns HTTP 402 Payment Required instead of performing the operation.

What Is a Feature Gate?

A feature gate is a middleware check that runs before the endpoint handler. It compares the workspace's current plan against the minimum plan required for the feature. If the plan is insufficient, the request is rejected with a 402 response before any business logic executes.

Paywall Response Shape

All 402 responses use the FeatureNotAvailableResponse envelope:

{
  "code": "feature_not_available",
  "message": "This feature requires a plan upgrade",
  "feature": "WORKFLOW_TEMPLATES",
  "required_plan": "ELITE",
  "current_plan": "PRO"
}
Field Type Description
code string Always "feature_not_available"
message string Human-readable explanation
feature string Internal feature identifier that triggered the gate
required_plan string Minimum plan tier needed (PRO, ELITE)
current_plan string The workspace's current plan at the time of the call

Note

This envelope differs from the standard PartnerErrorResponse (error, code, request_id) used by other error statuses. Parse 402 responses separately.

Gated Endpoints

User API (/v1/partner/user/...)

Endpoint Feature Minimum Plan
POST /v1/partner/user/sessions AI Chat Pro
PUT /v1/partner/user/sessions/{id} AI Chat Pro
POST /v1/partner/user/meeting-templates/{id}/apply Templates Pro
POST /v1/partner/user/workflow-runs Workflow Templates Elite
GET /v1/partner/user/meetings/{id}/transcript/export Transcript Export Elite

Pre-Flighting with the Profile Endpoint

To avoid hitting a 402 at runtime, read the workspace plan before calling a gated endpoint:

curl https://api.contio.ai/v1/partner/user/profile \
  -H "Authorization: Bearer <access_token>"

The response includes a plan_type field (FREE, PRO, ELITE, ENT) that you can check against the minimum plan column above.

Plan Tier Hierarchy

FREE < PRO < ELITE < ENT

A workspace on a higher tier has access to all features available to lower tiers.

const PLAN_RANK: Record<string, number> = {
  FREE: 0, PRO: 1, ELITE: 2, ENT: 3,
};

function hasAccess(currentPlan: string, requiredPlan: string): boolean {
  return (PLAN_RANK[currentPlan] ?? -1) >= (PLAN_RANK[requiredPlan] ?? 99);
}

// Example: check before triggering a workflow run (Elite required)
const profile = await sdk.user.getProfile();
if (!hasAccess(profile.plan_type, 'ELITE')) {
  console.log('Workspace must upgrade to Elite for workflow runs');
}

PLAN_RANK = {"FREE": 0, "PRO": 1, "ELITE": 2, "ENT": 3}

def has_access(current_plan: str, required_plan: str) -> bool:
    return PLAN_RANK.get(current_plan, -1) >= PLAN_RANK.get(required_plan, 99)

Upgrade Models

There is no Partner API endpoint to upgrade a workspace plan. How upgrades happen depends on the partner billing mode:

Billing Mode Upgrade Path
FLAT_RATE Workspaces are provisioned at the correct tier. A 402 indicates a provisioning or configuration issue (check DefaultPlanType on the partner app).
PARTNER_MANAGED The partner manages billing externally. Contact your Contio partner manager to adjust plan assignments.
WORKSPACE_MANAGED The workspace owner upgrades through the Contio checkout flow. Surface the 402 to the user and direct them to upgrade in their Contio settings.
NONE Same as WORKSPACE_MANAGED.

Error Handling Example

try {
  const run = await sdk.user.workflowRuns.create({
    workflow_template_id: templateId,
    originating_type: 'meeting',
    originating_id: meetingId,
  });
} catch (error) {
  if (error.status === 402) {
    const body = error.body;
    console.error(
      `Feature "${body.feature}" requires ${body.required_plan} plan ` +
      `(current: ${body.current_plan})`
    );
    // Show upgrade prompt to user
  }
}

HTTP_STATUS=$(curl -s -o response.json -w "%{http_code}" \
  -X POST https://api.contio.ai/v1/partner/user/workflow-runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_template_id": "..."}')

if [ "$HTTP_STATUS" = "402" ]; then
  echo "Plan upgrade required:"
  cat response.json | jq .
fi