Usage & Billing

This page explains how Cipherion measures usage, enforces plan limits, and calculates billing. Reading it will help you:

• predict the cost of a request before sending it
• understand why a request was rejected
• optimize payloads to reduce billable field counts
• interpret the billing metadata in API responses
• implement client-side safeguards against quota exhaustion

Plans at a Glance

Custom Pricing

For organizations whose usage patterns, compliance requirements, or scale fall outside the standard Free and Pro / Dev tiers, Cipherion offers fully negotiated custom plans. All limits and quotas listed below are configurable on a per-client basis.

What Can Be Customized

How Limits and Quotas Are Applied

Custom plans follow the same enforcement logic as standard plans — the difference is the values used in those checks. For example, if your custom plan specifies a field cap of 2,500 per request, the API enforces that ceiling in place of the standard 1,000. Your billing metadata response (meta.includedFields, meta.billingBlocks, meta.totalPrice) will reflect your negotiated included allowance and block rate.

{
  "meta": {
    "totalFields": 1800,
    "billableFields": 300,
    "billingBlocks": 6,
    "totalPrice": 0.06,
    "includedFields": 1500,
    "excludedFields": 12
  }
}

In this example the client has a negotiated included allowance of 1,500 fields per request and a custom overage block size of 50 fields at a negotiated per-block rate.

Overage Behavior Options

On custom plans, you can choose how the API handles requests that exceed your included field allowance:

Getting a Custom Plan

To discuss a custom pricing arrangement, contact the Cipherion team through the dashboard or reach out directly at support@cipherion.in. Come prepared with:

• Expected monthly encryption and decryption call volumes
• Typical payload field counts (average and peak)
• Any compliance, data residency, or SLA requirements
• Preferred billing cycle and budget constraints

Core Concepts

Before getting into plan-specific rules, it helps to understand the fundamental units Cipherion works with.

Request

A single API call to any encryption or decryption endpoint counts as one request. Regardless of how many fields are inside the payload, each HTTP call is one request against your call quota.

Field

A field is an individual encryptable leaf value inside a payload. Cipherion counts fields recursively — it descends into nested objects and arrays and counts every primitive value it reaches. Container nodes (objects and arrays themselves) are not counted; only the values at the leaves are.

{
  "name": "John Doe",
  "address": {
    "street": "742 Evergreen Terrace",
    "city": "Springfield"
  }
}

This payload contains 3 fields: name, address.street, and address.city. The address object itself is not a field.

Billable Field

A billable field is a leaf value that Cipherion actually encrypts. Fields excluded via exclude_fields or exclude_patterns are removed from the count before any billing calculation takes place. Some value types are also non-billable by definition (see Non-Billable Values below).

Included Field Allowance

Each plan includes a number of fields per request at no additional cost. Fields up to that limit are covered by the base plan. Fields beyond it are billed as overage — but only on plans where overage is enabled.

Free Plan

Call Quotas

Quotas reset automatically at the start of each billing cycle. Cipherion uses anniversary billing — your cycle starts on the day you sign up, not on the first of the calendar month. A user who signs up on April 16 has a cycle running April 16 to May 16.

Field Limits

The Free plan includes 50 fields per request and enforces that as a hard ceiling. Overage is disabled — there is no way to exceed 50 billable fields on a Free plan request. If a request contains more than 50 billable fields, it is rejected before processing.

included fields:  50
max fields:       50
overage:          disabled

Enforcement Behavior

When a request exceeds the field limit:

{
  "success": false,
  "statusCode": 422,
  "message": "Field limit exceeded: your plan allows a maximum of 50 fields per request (this request has 63 fields)."
}

When the call quota is exhausted:

{
  "success": false,
  "statusCode": 429,
  "message": "encryption quota exceeded: your plan includes 1,000 calls per billing period. Upgrade to a paid plan for additional calls."
}

Pro / Dev Plan

Call Quotas

Encryption calls have no monthly cap on the Pro / Dev plan. Decryption calls include 15,000 per billing cycle; additional calls beyond that are billed at a per-call rate.

Field Limits

The first 250 billable fields in any single request are covered by the plan. Fields 251 and beyond trigger overage billing, charged in blocks of 5 fields (see Overage Billing below).

No single request may exceed 1,000 billable fields. Requests above that ceiling are rejected with a 422 regardless of overage being enabled.

Overage Billing

Overage applies on the Pro / Dev plan when a single request contains more billable fields than the included allowance (250).

How Block Billing Works

Overage is billed in blocks of 5 fields. Partial blocks are always rounded up to the nearest whole block.

extra_fields       = max(0, billable_fields - 250)
billed_field_units = ceil(extra_fields / 5)

Example Table

Included fields = 250, block size = 5:

A request with 256 billable fields produces 6 extra fields, which rounds up to 2 billed blocks.

Billing Metadata in the Response

The response meta object includes a full billing breakdown on every request:

{
  "success": true,
  "data": {
    "encrypted": {}
  },
  "meta": {
    "totalFields": 260,
    "billableFields": 10,
    "billingBlocks": 2,
    "totalPrice": 0.02,
    "includedFields": 250,
    "excludedFields": 4
  }
}

How Fields Are Counted

Cipherion counts fields recursively by traversing the entire payload depth-first. Only leaf values are counted — objects and arrays are structural containers and do not add to the field count.

Nested Objects

Each property at the deepest level counts as one field. Intermediate objects do not count.

{
  "user": {
    "name": "John",
    "email": "john@example.com"
  }
}

Counted fields: 2   (user.name, user.email)

Arrays

Each encryptable element in an array counts individually.

{
  "tags": ["customer", "premium", "active"]
}

Counted fields: 3

For arrays of objects, the count comes from the leaf values inside each object:

{
  "users": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob",   "email": "bob@example.com" }
  ]
}

Counted fields: 4   (users[0].name, users[0].email, users[1].name, users[1].email)

Non-Billable Values

Some leaf values are never billed, regardless of plan:

{
  "name": "John",
  "nickname": "",
  "age": 34,
  "verified": true,
  "notes": null
}

Counted fields: 2   (name, age)
nickname, verified, and notes are non-billable

Empty Objects

An empty object {} contributes zero fields — it has no leaves to count.

{
  "metadata": {}
}

Counted fields: 0

Exclusion Evaluation Order

Exclusions are applied before counting. The processing pipeline for every request is:

1. Flatten the payload (resolve all paths)
2. Apply exclude_fields  (exact path matches)
3. Apply exclude_patterns  (wildcard name matches)
4. Count remaining leaf values
5. Subtract non-billable value types
6. Apply plan field limit and overage rules

Excluded fields never appear in totalFields, billableFields, or any overage calculation.

Platform-Wide Safety Cap

Regardless of plan, all requests are subject to a hard structural field cap enforced before any database lookup occurs. Requests that exceed this cap are rejected immediately with 413 Payload Too Large:

{
  "success": false,
  "statusCode": 413,
  "message": "Payload too large: maximum 10000 fields allowed per request (received 12400)."
}

This cap is applied to the raw structural field count — including containers, empty objects, and all values — before exclusions are processed. It exists to prevent abuse and protect system stability. It is higher than any plan's field limit and should not be encountered in normal usage.

Exclusions and Billing

Fields excluded via exclude_fields or exclude_patterns are fully removed from every billing calculation. They do not appear in totalFields, they do not trigger overage, and they do not consume the included field allowance.

This makes exclusions an effective tool for cost management. Fields like _id, created_at, updated_at, status, and version fields are rarely sensitive and almost always safe to exclude.

{
  "data": {},
  "passphrase": "your-secure-passphrase",
  "exclude_patterns": ["_id", "__v", "*_at", "status"]
}

Failed Requests and Billing

Not all requests that reach the API are billed. Cipherion uses optimistic counter incrementing with automatic rollback on failure — your quota is only consumed when a request completes successfully.

The counter is incremented optimistically before the encryption or decryption logic runs, to prevent quota-bypass races under concurrent requests. If the handler returns a non-2xx status, the counter is decremented back to its pre-request value. You are never charged for a failed operation.

Deep Encrypt / Deep Decrypt Pricing

There is no separate pricing model for recursive operations. deep_encrypt and deep_decrypt use the same field counting and billing rules as all other endpoints. A payload five levels deep costs the same as a flat payload with the same number of leaf fields. Traversal depth itself is never billed.

Recommended Client-Side Workflow

To avoid unexpected rejections or quota exhaustion, implement the following steps before sending a request:

1. Count leaf fields in the payload
2. Apply your exclusion rules (subtract excluded paths and patterns)
3. Verify the resulting field count is within your plan limit
4. Estimate overage cost if on a paid plan (extra fields / 5, rounded up)
5. Send the request
6. On 429 or 422, surface the error clearly — do not retry blindly

A simple field counter that mirrors Cipherion's logic:

function countBillableFields(data, excludePatterns = []) {
  let count = 0;

  function isNonBillable(value) {
    if (value === null || value === undefined) return true;
    if (typeof value === 'boolean') return true;
    if (typeof value === 'string' && value.trim() === '') return true;
    return false;
  }

  function isExcluded(fieldName) {
    return excludePatterns.some(pattern => {
      const regex = new RegExp(
        '^' + pattern.replace(/\*/g, '[^.\\[\\]]*') + '$'
      );
      return regex.test(fieldName);
    });
  }

  function traverse(node, fieldName) {
    if (fieldName && isExcluded(fieldName)) return;
    if (node === null || typeof node !== 'object') {
      if (!isNonBillable(node)) count++;
      return;
    }
    if (Array.isArray(node)) {
      node.forEach(item => traverse(item, null));
      return;
    }
    Object.keys(node).forEach(key => traverse(node[key], key));
  }

  traverse(data, null);
  return count;
}

// Usage
const fields = countBillableFields(req.body, ['_id', '__v', '*_at']);
console.log(`Estimated billable fields: ${fields}`);

Frequently Asked Questions

Do excluded fields count toward billing?

No. Excluded fields are removed before any counting or billing calculation takes place.

Are arrays counted per element?

Yes. Each encryptable primitive element in an array counts as one field. Array objects are traversed recursively and their leaf values are counted individually.

Are failed validation requests billed?

No. Requests rejected before processing (auth failures, invalid JSON, field limit exceeded) are never billed.

Does deep encryption cost more than flat encryption?

No. Pricing is based on the number of counted leaf fields, not traversal depth or nesting levels.

Are retries billed?

Each successful retry counts as a new request. Failed retries are not billed.

What happens when my Free plan quota runs out?

All further requests are blocked until the next billing cycle. There is no overage or grace period on the Free plan.

What is the maximum payload size?

The platform enforces a hard structural cap of 10,000 fields per request. Requests above this are rejected with 413 before any plan-level checks are performed.

Is null billable?

No. null, undefined, booleans, empty strings, and whitespace-only strings are never billed.

Can I get a custom field cap or call quota?

Yes. Custom plans support fully negotiated limits. See Custom Pricing for details or contact the Cipherion team through the dashboard.