---
updatedAt: 2026-03-24T07:55:02.000Z
agentTools:
  projectIndex: https://docs.bokio.se/llms.txt
---

# 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)

| Plan         | API Access      | Notes                                           |
| ------------ | --------------- | ----------------------------------------------- |
| **Plus**     | ✅ Included      | Full API access at no extra cost                |
| **Business** | ✅ Included      | Full API access at no extra cost                |
| **Premium**  | 🔧 Add-on       | Requires Integrations (API) add-on              |
| **Basic**    | ❌ Not available | Company must upgrade to use public integrations |

### Private Integrations

| Plan         | API Access      |
| ------------ | --------------- |
| **Plus**     | ✅ Included      |
| **Premium**  | ✅ Included      |
| **Business** | ✅ Included      |
| **Basic**    | ❌ Not available |

> 📘 **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
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

| Field                        | Type      | Description                                                     |
| ---------------------------- | --------- | --------------------------------------------------------------- |
| `error`                      | string    | Always `"price_plan_feature_required"` for plan-related denials |
| `message`                    | string    | Human-readable description                                      |
| `details.requiredFeature`    | string    | The feature required — `"PublicApi"` or `"PrivateApi"`          |
| `details.availableIn`        | string\[] | Plans where this feature is included at no extra cost           |
| `details.availableAsAddonIn` | string\[] | Plans where this feature can be purchased as an add-on          |
| `details.isAvailableInTrial` | boolean   | Whether the feature is available during the Bokio trial         |
| `details.isInTrial`          | boolean   | Whether the company is currently in a trial period              |

> ⚠️ **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
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

| Scenario                | Header Present                     |
| ----------------------- | ---------------------------------- |
| Plan expires in 10 days | ✅ Yes                              |
| Plan expires in 14 days | ✅ Yes                              |
| Plan expires in 15 days | ❌ No                               |
| Plan is not expiring    | ❌ No                               |
| Plan already expired    | ❌ No (request returns 403 instead) |

***

## 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:

| Endpoint                   | Purpose                                      |
| -------------------------- | -------------------------------------------- |
| `POST /token`              | Exchange authorization code or refresh token |
| `GET /authorize`           | OAuth authorization                          |
| `GET /connections`         | List connections                             |
| `DELETE /connections/{id}` | Remove a connection                          |

***

## 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.