Merchant plans and limits: features, limits and upgrade rules
Reference for merchant plan features and limits (API, webhooks, stores, import, parcels, pickup locations), what a legacy plan means, the upgrade-only rule and what a blocked action looks like.
Last updated 22 October 2026 · Last verified 22 October 2026
Purpose#
A merchant plan decides which features an independent platform merchant can use, and how much: parcels per subscription, API calls, webhook URLs, connected stores, pickup locations and couriers. This reference lists every feature flag and limit, what a blocked action looks like, and the upgrade rules.
Who the plans apply to#
- Independent platform merchants. The super admin creates and edits plans under Merchant plans; a merchant cannot change them.
- Not covered by the features or the parcel, API, webhook and store limits: merchants that belong to a delivery company (their subscription is the company's), the account the platform uses for individual (guest) shipping, and everyone when no merchant plan is active in the system. The pickup-location check has no exceptions: it runs for any merchant whenever a merchant plan is active.
- Without an active subscription, a merchant cannot create parcels or use plan features, but the wallet and plan pages stay open.
Check your plan and usage#
Open the plan page
Choose Plan and subscription under Finance in the side menu.
Read your subscription and usage
Your current subscription shows the plan, start and end dates, and the duration (monthly or yearly). Your plan usage shows used / maximum for "Parcels during subscription" and, when the feature is on, "API requests today", "Webhook URLs" and "Connected stores"; ∞ means no limit.
Upgrade if needed
On a plan card press Pay from balance (the dollar price is deducted from the shipping balance after you confirm) or Pay via … when a gateway is enabled for plans. With a gateway, the wallet is credited with the plan price and the plan is then activated.
- Choose the pickup place
- Choose the delivery company
- Enter the recipient's name and phone
- Set the cash-on-delivery amount
- Your invoice number, to recognise the parcel later
Features (flags)#
Each plan switches these on or off. Plan cards show a tick, or a struck-through line when off, with a shortened label (the bracketed part dropped) and the API, webhook and store limits added.
| Flag | Label (super admin form and messages) | When it is off |
|---|---|---|
api |
API (API keys to connect with any system) | API keys cannot be generated; every /api/v1 call answers 403 plan_feature. |
webhooks |
Webhook (parcel updates to your system) | Adding a URL is refused; POST /api/v1/webhooks answers 403 plan_feature (the other webhook endpoints do not check this flag); events stop being sent. |
stores |
Store integrations (Salla, WooCommerce, Shopify) | Connecting a store or generating a store key is refused. |
import |
Import parcels from Excel | The import page redirects to the plan page with a warning. |
own_carrier |
Connect your own account with shipping companies | Saving your own carrier credentials is refused. |
warehouses |
Warehouse service | The warehouse service is unavailable unless the super admin enabled it for you by hand; the service itself must also be switched on. |
reports_export |
Export reports (CSV) | CSV export of parcel reports and of the statement is refused with a warning. |
live_tracking |
«تتبّع المناديب المباشر على الخريطة (لمناديب شركتك الخاصة)» (live courier map for your own company's couriers) | The map page shows the denial message. |
Limits#
For parcels, enter 0 for no limit (the field is required). For api_per_minute, api_per_day, webhooks_max and stores_max, an empty or 0 value means no plan limit.
| Setting | Meaning | Default in the new-plan form | When exceeded |
|---|---|---|---|
Parcels (parcel_count) |
Parcels created from the start date to the expiry date of the subscription, deleted ones excluded | none | New parcels are refused from every source (panel, import, API, stores) |
api_per_minute |
API requests per minute | 60 | 429 rate_limited |
api_per_day |
API requests per day, reset at midnight | 5000 | 429 rate_limited |
webhooks_max |
Webhook URLs (the system maximum is 10) | 3 | Adding a URL is refused (API: 422 limit_reached) |
stores_max |
Connected stores; re-linking the same store does not count | 1 | Linking is refused |
| Pickup locations | Number of pickup locations allowed; never below 1 (0 or empty counts as 1); warehouse locations do not count | 1 | Adding a location is refused |
| Couriers | Couriers of your own delivery company; 0 allows none | set per plan | Adding a courier is refused |
On top of the plan limits, the API has fixed throttles per route: 120 requests per minute for the whole /api/v1 group, 60 for POST /parcels, 30 for GET /statement, 20 for POST /webhooks and 10 for the webhook test. A plan limit above these cannot be used in full, and a 429 response without the rate_limited code comes from these fixed throttles, not from the plan (see the rate-limits guide).
Legacy plans#
A plan created before features were added keeps its features unset: every flag is on, there are no API, webhook or store limits and its parcel count is not enforced, until the super admin opens it, sets the features and saves (the edit form warns about this). Once saved, an unticked flag is off. The pickup-location and courier limits stored on the plan itself still apply, as for any plan.
Upgrade-only rules#
A plan saved with the monthly cycle lasts 30 days and one saved with the yearly cycle 365 days; a plan created before the cycle option keeps its original day count (shown on the plan card) until the super admin saves it again. While a subscription is active you cannot renew it early or move down.
- Allowed: a higher level, or monthly to yearly at the same level; never from a yearly plan to a monthly one, even at a higher level.
- Refused: the same plan, a lower level, yearly to monthly, or another plan of the same level and cycle.
- An upgrade starts today and the old subscription ends yesterday. The full new price is charged and the unused days of the old plan are not credited. A price of 0 charges nothing.
- With no active subscription you can choose any plan.
What a blocked action looks like#
In the API the message arrives in Arabic by default, and in English only when the client sends an Accept-Language header that starts with en. The error code (plan_feature, rate_limited, validation_failed, limit_reached, api_not_allowed) is the same in both languages.
| Situation | Message in the English interface | Where |
|---|---|---|
| Parcel limit | "You have reached your plan limit: 100 parcels during the subscription period (until 2026-11-30), and you used 100. Upgrade your plan or renew the subscription to continue." | Error list on the New parcel form, a result row in the import, 422 validation_failed in the API |
| Feature off | "Feature «Export reports (CSV)» is not included in your current plan — upgrade your plan from the subscription page." | Warning titled "Plan", or 403 plan_feature in the API |
| No subscription | "You do not have an active merchant plan subscription — subscribe to use «…»." For parcels: "The merchant subscription to a merchant plan has expired or does not exist — renew the subscription to create parcels." | Same places |
| API rate | "You have reached your plan limit: 60 order Per minute. Wait 30 seconds or upgrade your plan." | 429 with retry_after and a Retry-After header |
| Other limits | "You have reached your plan limit: 3 webhook links. Upgrade your plan to add more." / "Your plan allows 2 pickup locations only, and you have 2. Upgrade the plan to add more locations." | The form that adds the item |
| Pickup locations, no subscription | "No active merchant plan subscription — subscribe first to be able to add pickup locations." | The form that adds a location, for every merchant |
Common mistakes#
- Expecting to extend the current plan: it is refused until it ends; upgrade instead.
- A flag is on but a call is refused: check the usage bars, the daily and per-minute API limits, the fixed per-route API throttles and the webhook and store limits.
- API calls fail without a subscription: with plans enabled, no active subscription means every
/api/v1call answers 403plan_feature. Company merchants get 403api_not_allowed.
Limits and permissions#
- Only the super admin edits plans. Checks run on the server for the panel, the API, imports and connected stores.
- Plan cards list only active plans.
- Webhook events keep being sent after a plan expires, but stop if the active plan lacks the
webhooksflag. - Some of these messages have no English translation, and the English API-limit wording is imperfect: it reads "order Per minute".