Plans & Limits
Understand the Free plan limits and how the stemp API reports them.
Plans & Limits
Every stemp organization is on a plan. New organizations try Pro free for 30 days. After the trial, or when a paid subscription ends, an organization without a paid plan is on Free, where three limits apply. This page explains the limits and how to handle them in your integration.
Free Plan Limits
| Limit | Free allows | Returns 402 |
|---|---|---|
CUSTOMERS | Stamps for the first 30 customers, by creation date | Adding, removing, setting, or resetting stamps for any later customer |
LOCATIONS | 1 location | Creating a second location (POST /v1/locations) |
TEMPLATES | 1 active template | Creating a second active template (POST /v1/templates/from_preset/{presetId}) |
During the trial and on a paid plan, none of these limits apply. The API does not return an organization's plan; a 402 is the signal that a limit applies.
What Is Not Limited
- New customers — Customer 31 and later still get a wallet pass. Stamping them returns
402; the stamp is not kept. - Earned rewards — Rewards a customer has already earned can still be redeemed.
- Member passes — Organization members are not counted as customers. Their passes can always be stamped.
- Read operations — All read endpoints work as usual.
Error Response
When a request goes past a limit, the API returns 402 Payment Required:
{
"code": "subscription_required",
"limit": "CUSTOMERS"
}| Field | Description |
|---|---|
code | Always subscription_required |
limit | The limit that was reached: CUSTOMERS, LOCATIONS, or TEMPLATES |
Handling Limits
const response = await fetch(
`https://api.stemp.app/api/v1/walletpasses/${walletPassId}/stamps/add`,
{
method: 'POST',
headers: { Authorization: `Bearer ${token}` },
},
)
if (response.status === 402) {
const { limit } = await response.json()
// e.g. limit === 'CUSTOMERS': stamping resumes once the organization upgrades
}Best Practices
- Don't retry — A
402stays until the organization upgrades. Retrying only uses up your rate limit. - Name the limit — Use the
limitfield to tell the user which limit was reached. - Point to stemp — Organizations upgrade in the stemp console or the stemp iOS app, not through the API.