# Billing and pricing

> How a third-party app is paid today: wallet charges with the billing scope, the per-charge cap, the revenue split and what is not open to outside apps.

Source: https://hekana.dev/apps/billing

> **Status, 2026-10-25.** Third-party apps have **one** way to earn: charging the store's wallet with `POST /charge`. Subscription plans, free trials, upgrades, downgrades and one-time purchases exist in the platform for Hekana's own apps only. There is no API for outside apps to define them, and no price is shown for a third-party app in the app list. If you need recurring billing, your app has to decide when to call `/charge` itself.

## Pricing models

| Model | First-party apps | Third-party apps |
| - | - | - |
| Free | Yes | Yes. A third-party app is listed as free with no price. |
| Usage | Yes | Through `POST /charge` with `type: "usage"`, one call per billable event. |
| Subscription | Tiers per 30-day period, a 14-day trial on the first paid tier, proration on upgrade, a 3-day grace on a failed renewal | Not available as a platform feature. `type: "subscription"` is only a label on a charge you make yourself. |
| One-time purchase | Mechanism built, nothing on sale yet | Not available. |
| Charging a shopper's saved card | Foundations only, cannot charge | Not available. |

## Charge a store

`POST https://api.hekana.com/api/v1/apps-api/charge`, scope `billing`. The scope spends the store's wallet, so ask for it only if you charge. 30 requests a minute.

```json title="POST /charge (request body)"
{
  "amountCents": 2500,
  "reference": "invoice:2026-11:store-abc",
  "description": "November usage",
  "type": "usage"
}
```

- `amountCents`: a whole number of piastres, at least 1, **at most 50,000 (500 EGP) per charge**. For more, make several charges.
- `reference`: your own id, up to 128 characters. It makes the charge idempotent: sending it again returns the first charge instead of charging twice.
- `description`: optional, up to 200 characters.
- `type`: `usage` (default) or `subscription`. A label only.

The reply:

```json title="reply (data)"
{
  "chargeId": "<id>",
  "amountCents": 2500,
  "hekanaCutCents": 500,
  "developerNetCents": 2000,
  "idempotentReplay": false
}
```

Each charge is split: Hekana's share is a percentage stored per app (20 percent by default), rounded, and your net is the remainder, so the two always add up to the amount.

Errors:

| Status | `message` | Meaning |
| - | - | - |
| 400 | `amount_must_be_positive_integer`, `amount_exceeds_per_charge_cap` | The amount is not valid or is over 50,000. |
| 403 | `insufficient_funds` | The wallet could not cover it. Nothing was charged and the reference can be used again after a top-up. |
| 403 | `app_unavailable` | The app is not approved. |
| 409 | `charge_in_progress` | The same reference is mid-charge. Retry shortly. |

## Earnings

`GET /earnings` (scope `billing`) returns `{ earnedCents }`: the sum of your settled net amounts across all of your apps. Only settled charges count.

> **Payouts are not covered here.** The Apps API reports what you have earned. How and when earnings are paid out is not part of the API and is not documented on this site yet; contact Hekana before you build a paid app.

## Prices are in EGP

Every amount is in piastres. The wallet is the store's Hekana wallet, in EGP.