> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wizzgift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits and tiers

> Account limits, spend caps, and rate limits.

Every account has a tier. Tiers define the limits below; higher tiers (bigger caps, better pricing) are assigned by the Wizzgift team — contact support with your expected volumes. New accounts start on the **starter** tier.

## Reading your limits

Never hardcode limits — read them live from `GET /b2b/account` or `GET /retailer/v1/account`:

```json theme={null}
{
  "tier": "starter",
  "limits": {
    "maxQuantityPerItem": 250,
    "maxItemsPerOrder": 20,
    "maxOrderAmountUSD": 1000,
    "dailySpendCapUSD": 5000,
    "monthlySpendCapUSD": 50000,
    "maxDepositUSD": 2000,
    "rateLimitTier": "moderate",
    "maxOpenCheckouts": 25,
    "dailyCheckoutCreations": 200,
    "maxMarkupPercent": 20
  },
  "usage": {
    "daily": { "spentUsd": 1200, "capUsd": 5000 },
    "monthly": { "spentUsd": 14300, "capUsd": 50000 }
  }
}
```

<Note>
  The values above are illustrative — your actual limits come from your tier plus any per-account overrides, and are always current in the account response.
</Note>

## What each limit controls

| Limit                                     | Applies to                                        |
| ----------------------------------------- | ------------------------------------------------- |
| `maxQuantityPerItem`                      | Quantity on a single order line                   |
| `maxItemsPerOrder`                        | Number of lines in one order                      |
| `maxOrderAmountUSD`                       | USD value of a single order                       |
| `dailySpendCapUSD` / `monthlySpendCapUSD` | Rolling UTC-day / UTC-month B2B spend             |
| `maxDepositUSD`                           | Single deposit size                               |
| `maxOpenCheckouts`                        | Simultaneously pending retailer checkouts         |
| `dailyCheckoutCreations`                  | Retailer checkout creations per UTC day           |
| `maxMarkupPercent`                        | Retailer markup, per checkout and account default |

## Handling limit errors

Exceeding a limit returns `422` with code `B2B_LIMIT_EXCEEDED` and machine-readable details:

```json theme={null}
{
  "error": {
    "code": "B2B_LIMIT_EXCEEDED",
    "message": "Daily spend cap exceeded",
    "details": {
      "limit": "dailySpendCapUSD",
      "limitValue": 5000,
      "current": 4800,
      "requested": 400,
      "window": "day",
      "tier": "starter"
    }
  },
  "requestId": "req_8f3k2"
}
```

Switch on `details.limit` to react: queue the order for the next window (`dailySpendCapUSD`), split it (`maxOrderAmountUSD`, `maxQuantityPerItem`), or surface an upgrade prompt.

## Rate limiting

API traffic is rate-limited per account, keyed to your tier's `rateLimitTier` (`strict`, `moderate`, or `general`). Exceeding it returns `429`:

```json theme={null}
{ "error": "Too many requests", "message": "Rate limit exceeded. Please try again later." }
```

<Note>
  The `429` body is a flat shape, not the standard error envelope — match on the status code, not the body structure.
</Note>

Back off exponentially on `429`. Spread bulk operations (catalog syncs, reconciliation sweeps) instead of bursting them.

## Rebates

Tiers can carry volume rebate offers: spend `targetAmountUsd` within the window and `rewardAmountUsd` is credited to your balance. Progress is returned under `rebates` in the account response — no separate tracking needed.