How to set a proxy traffic limit for each customer
For a plan sold in delivered GB, create a customer key with a raw cap. For a plan sold in prepaid balance GB, select a balance cap and label that unit in checkout. A top-up adds to the key’s lifetime cap. Check the remaining quota, expiry and holds before restoring access.
In this guide
Match the cap to the promise on the order
A customer buying “5 GB of traffic” normally expects to transfer 5 GB across the connection. Set trafficCapGB to 5 and capMode to raw for that offer. Upload and download both count. Use balance when the offer is explicitly sold in balance GB and you want the cap to follow the rate your wholesale account pays.
On a country-tier account, the same balance allowance can carry more raw traffic in cheaper destinations. On a flat-rate account the two meters generally move together. The worked bandwidth statement shows both readings. Decide which one appears on the customer’s receipt before creating a key.
Keep the reseller API secret on your server. Issue a distinct pool access key for each independently metered allowance and store its record ID against the customer. Two people using one shared key draw down the same cap, even if they use different sessions.
What a 3 GB top-up does to a 5 GB key
Suppose a raw-mode key has a 5 GB cap and a valid reading of 4,608 MB used. There are 512 MB left. The customer pays for another 3 GB. After one confirmed additive top-up, the cap is 8 GB and the used counter still reads 4,608 MB if no traffic passed in the meantime.
| Key reading | Before | After |
|---|---|---|
| Cumulative cap | 5 GB | 8 GB |
| Already used | 4,608 MB | 4,608 MB |
| Remaining | 512 MB | 3,584 MB |
The authenticated POST /v1/reseller/pool-keys/{keyId}/topup operation takes addTrafficGB as a whole number. An update setting trafficCapGB to 3 would set the entire cap to 3 GB, already below this customer’s usage. Save a stable operation identifier against the paid order and look up the original operation if delivery times out. A second grant would turn the same sale into 6 GB of extra allowance.
A paid top-up is confirmed, but access is still held
- Read the customer key again. Check the active cap mode, its valid MB counter,
trafficCapGB, expiry,lifecycleHoldsandlifecycleVersion. An unknown counter or expiry calls for a fresh reading. - Check for remaining quota and reseller funding. A customer cap sets a ceiling. Funding comes from your reseller balance. A paid retail order by itself adds no upstream balance.
- Review the hold reasons. A quota top-up preserves holds. For a sole
caphold, a valid expiry and available quota, an authorized operator can request conditional resume with the version just read. If the version changed, read the key again. A payment or manual hold needs its own review.
If the key is usable but the country the customer bought still fails, check the stock for that pool and country. In a support reply, give the measured remainder and the pending action. Keep the customer’s key and your reseller credential out of tickets. The reseller integration guide links to the provider and storefront contracts.
Make the first allowance a launch check
In your own test environment, exercise three orders. For a first purchase, confirm the created key’s cap and meter. For a top-up, deliver the same payment event twice and verify one grant. For a held key, confirm the grant increased the cap while preserving the hold. If an actual payment already cleared, recover the original paid order before making another grant.
Choose the plan’s cap within your account’s per-key ceiling. A finite cap is a whole number of GB. If a customer asks for a monthly allowance, record the period and write down your renewal or carry-over rule before selling it. The shared key uses a cumulative counter, so applying a recurring retail label alone will never reset it. The white-label program guide explains who owns customer billing and support.
Common questions
- Does a traffic cap reserve bandwidth in a particular country?
- The cap limits the key’s metered usage. Country eligibility and live stock are separate checks. Confirm both for the route the customer is buying.
- Can I set a different allowance per session on one key?
- The key’s cap is shared across its sessions. For separately metered customers or allowances, issue distinct keys and associate each record ID with the correct customer.