Price Plan Requirements

Overview

Access to Company API endpoints requires an active Bokio subscription plan that includes API access. If a company's plan does not include API access, requests return 403 Forbidden with a structured error body explaining which plans are available. Note that Private integrations and Public integrations has different price plan requirements.

General API endpoints — OAuth authorization, token management, and connection management — are not restricted by plan as they are for public integration to manage their connections.

📘

Trial access: All API features are available during the 14-day Bokio trial, regardless of plan.

Plan Availability

Public Integrations (Marketplace)

Private Integrations

📘

What's the difference? Public integrations for building integration for other Bokio users or when higher usage levels are needed. Private integrations are created by the company for their own use. For more see

Handling 403 Responses

When a company's plan does not include API access, the API returns a 403 Forbidden response with a JSON body:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "price_plan_feature_required",
  "message": "This feature requires Integrations (API) or a Plus plan",
  "details": {
    "requiredFeature": "PublicApi",
    "availableIn": ["Plus", "Business"],
    "availableAsAddonIn": ["Premium"],
    "isAvailableInTrial": true,
    "isInTrial": false
  }
}

Response Fields

⚠️

Distinguishing plan errors from other 403s: Check for "error": "price_plan_feature_required" in the response body. Other 403 responses (e.g., missing scopes, invalid company membership) will have different error structures.

Recommended Handling

if (response.status === 403) {
  const body = await response.json();

  if (body.error === "price_plan_feature_required") {
    // Plan restriction — guide the user to upgrade
    const plans = body.details.availableIn.join(", ");
    showMessage(`API access requires a ${plans} plan. Please upgrade in Bokio.`);
  } else {
    // Other authorization error (scope, membership, etc.)
    handleAuthError(response);
  }
}

Plan Expiration Warning

When a company's plan is about to expire within 14 days, the API adds a Bokio-Plan-Warning header to successful responses:

HTTP/1.1 200 OK
Bokio-Plan-Warning: Your plan expires on 2025-03-15. API access will be restricted after expiration.
Content-Type: application/json

{ ... normal response body ... }

The header value is a human-readable string containing the expiration date in YYYY-MM-DD format.

⚠️

Important: After the plan expires, API requests will start returning 403 Forbidden. Use this warning period to notify your users before access is lost.

Recommended Handling

Check for the Bokio-Plan-Warning header on every response:

const warning = response.headers.get("Bokio-Plan-Warning");

if (warning) {
  // Extract date and notify the user
  notifyUser(warning);
}

When the Header Appears

Affected Endpoints

Price plan enforcement applies to all Company API endpoints — any endpoint with /companies/{companyId}/ in the path:

• Company Information
• Invoices, Credit Notes, Invoice Payments, Invoice Settlements
• Customers
• Journal Entries
• Chart of Accounts, Fiscal Years
• Bank Payments
• Items
• SIE Import/Export
• Uploads
• Invoice Attachments

Endpoints NOT Affected

These endpoints work regardless of plan:

FAQ

What happens when a trial ends?

If the company does not upgrade to a plan that includes API access, requests will start returning 403 Forbidden. The details.isInTrial field in the error response will be false.

Can I check a company's plan before making API calls?

No. The recommended approach is to handle 403 responses gracefully and check for the Bokio-Plan-Warning header on successful responses to anticipate upcoming restrictions.

What if the company upgrades their plan?

API access is granted immediately after the plan upgrade. No action is needed from the integration — the next API request will succeed.